From 8935bce29ecf46124f09a3c4c3cdd357b07e8b18 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sat, 6 Jun 2026 23:12:42 -0500 Subject: [PATCH 1/2] Introduce "type names" section to the style guide Resolves #1821 This enhancement to the style guide was motivated by a desire to resolve some inconsistent phrasing in the docs, which caused some disagreement in a CPython docs PR. The new section describes guidance for how type names should be documented. Class references or unlinked class styling are preferred, and other styles are described for use only when they are superior to the class name. --- documentation/style-guide.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 73618f9ae..15dd78045 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,6 +116,27 @@ Unix 1970s. +Type names +========== + +When writing the names of types in prose, prefer to write the name of the type +exactly as it appears in source, styled as a class reference or an unlinked +class. For example, refer to dict as ``:class:`dict`‌`` or ``:class:`!dict`‌``. + +Links should be used according to the :ref:`guidance on links `. + +Some type names are commonly understood ideas or nouns outside of Python. +For example, "tuples" are a general programming concept, as distinct from the +``tuple`` type. When referring to general ideas, do not style the relevant word +as a type. + +Many types have descriptive names which do not exactly match their type +name. For example, "context variables" describes ``contextvars.ContextVar``, +and "partial function" may be used to describe an application of +``functools.partial``. Use these names only when they serve to clarify the text +better than the type name itself would, and put them in lowercase. + + Use simple language =================== From 1328257625d1bd968e28be93aebbb7c19e72e88b Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sun, 7 Jun 2026 07:27:26 -0500 Subject: [PATCH 2/2] Apply suggestion from @StanFromIreland Co-authored-by: Stan Ulbrych --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 15dd78045..7d1abd7b7 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -119,7 +119,7 @@ Unix Type names ========== -When writing the names of types in prose, prefer to write the name of the type +When writing the names of types in prose, write the name of the type exactly as it appears in source, styled as a class reference or an unlinked class. For example, refer to dict as ``:class:`dict`‌`` or ``:class:`!dict`‌``.