Title: Feature: Expand the style-guide to cover how type names should be written in prose · Issue #1821 · python/devguide · GitHub
Open Graph Title: Feature: Expand the style-guide to cover how type names should be written in prose · Issue #1821 · python/devguide
X Title: Feature: Expand the style-guide to cover how type names should be written in prose · Issue #1821 · python/devguide
Description: Describe the enhancement or feature you would like In order to smooth out stylistic debates about how docs are spelled, the style-guide page should provide guidance about how type-names should be written. There are various cases in the s...
Open Graph Description: Describe the enhancement or feature you would like In order to smooth out stylistic debates about how docs are spelled, the style-guide page should provide guidance about how type-names should be w...
X Description: Describe the enhancement or feature you would like In order to smooth out stylistic debates about how docs are spelled, the style-guide page should provide guidance about how type-names should be w...
Opengraph URL: https://github.com/python/devguide/issues/1821
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Feature: Expand the style-guide to cover how type names should be written in prose","articleBody":"### Describe the enhancement or feature you would like\n\nIn order to smooth out stylistic debates about how docs are spelled, the style-guide page should provide guidance about how type-names should be written.\n\nThere are various cases in the stdlib in which we refer to a type vs a more general idea (for example: `tuple` vs \"tuples\").\nThere are also cases in which documentation wants to refer to a type as an established idea in the relevant domain rather than the type (for example: \"thread-local storage\" vs `threading.local`).\nFinally, there are cases where the name of the idea is related to the type name, as in \"deque\" for `collections.deque` or \"Context Variable\" for `contextvars.ContextVar`.\n\nThe style-guide should provide rules for which style to use when writing a type name in prose, so that we avoid and can heal pages like the current `contextvars` docs, which use `ContextVar`, \"Context Variable\", and \"context variable\".\n\nI propose the following rule as an addition to the style guide below the [specific words section](https://devguide.python.org/documentation/style-guide/#specific-words):\n\n> Type names\n> ----------\n>\n> 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```.\n>\n> Links should be used according to the `guidance on links \u003clinks>`.\n>\n> 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.\n>\n> 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.\n\n\n### Describe alternatives you have considered\n\nMake CPython doc issues and edits without establishing style guide guidance, trying to make things consistent organically over time.\n(I think this is unlikely to succeed, but it is possible.)\n\n### Additional context\n\nIn [a recent CPython docs PR](https://github.com/python/cpython/pull/150325), we found that we could not write text that was consistent across different modules because those modules had different styles for referring to relevant classes by name.\n\nSome docs use class names verbatim, as they appear in source, and code-quoted. For example, the new `frozendict` type is generally written exactly as it is named, styled as a class or link/ref: \"`frozendict`\".\n\nSome docs use class names as though they are ordinary nouns. For example, the [`deque` docs](https://docs.python.org/3/library/collections.html#collections.deque) refer to \"deques\", without code quoting or linking.\n\nA small category of docs refer to the class name as though it is a proper noun. At time of writing, I can only find `Context Variables` as an example of this.","author":{"url":"https://github.com/sirosen","@type":"Person","name":"sirosen"},"datePublished":"2026-06-03T17:15:41Z","url":"https://github.com/python/devguide/issues/1821"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d8c0abba-7419-2ec2-1b9f-847af6c68dc1 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 825E:1F52F6:C7F25D:10C7B59:6B005191 |
| html-safe-nonce | 620c1de91ec0e24e7cfdf51df02270dc5ffd614b5355e5fa40bfa67e5f65b511 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4MjVFOjFGNTJGNjpDN0YyNUQ6MTBDN0I1OTo2QjAwNTE5MSIsInZpc2l0b3JfaWQiOiIyMTM0NDg0NjM0OTIxMDk1NTY5IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 75ae974d60ab8e624ff5ff3d45af41e9352b0e910a2bec5ee823a8feebd73ac7 |
| hovercard-subject-tag | issue:4582071676 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/devguide/1821/issue_layout |
| twitter:image | https://opengraph.githubassets.com/ae4effd8800bb55aaa555163fe53c894a3f7ef8528f7229e29b652205b27dceb/python/devguide/issues/1821 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/ae4effd8800bb55aaa555163fe53c894a3f7ef8528f7229e29b652205b27dceb/python/devguide/issues/1821 |
| og:image:alt | Describe the enhancement or feature you would like In order to smooth out stylistic debates about how docs are spelled, the style-guide page should provide guidance about how type-names should be w... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | sirosen |
| hostname | github.com |
| expected-hostname | github.com |
| None | f420f4996e6b1ff1ccd6d7683f8134f4b5f0f8a50124c210dbfe7490e5644abb |
| turbo-cache-control | no-preview |
| go-import | github.com/python/devguide git https://github.com/python/devguide.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 63972479 |
| octolytics-dimension-repository_nwo | python/devguide |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 63972479 |
| octolytics-dimension-repository_network_root_nwo | python/devguide |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 26e00df917aba0f128135dc073ea0c5e33a70d40 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width