René's URL Explorer Experiment


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

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@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-profiling0
react-import-mapreact,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-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:d8c0abba-7419-2ec2-1b9f-847af6c68dc1
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-id825E:1F52F6:C7F25D:10C7B59:6B005191
html-safe-nonce620c1de91ec0e24e7cfdf51df02270dc5ffd614b5355e5fa40bfa67e5f65b511
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4MjVFOjFGNTJGNjpDN0YyNUQ6MTBDN0I1OTo2QjAwNTE5MSIsInZpc2l0b3JfaWQiOiIyMTM0NDg0NjM0OTIxMDk1NTY5IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0=
visitor-hmac75ae974d60ab8e624ff5ff3d45af41e9352b0e910a2bec5ee823a8feebd73ac7
hovercard-subject-tagissue:4582071676
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/devguide/1821/issue_layout
twitter:imagehttps://opengraph.githubassets.com/ae4effd8800bb55aaa555163fe53c894a3f7ef8528f7229e29b652205b27dceb/python/devguide/issues/1821
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/ae4effd8800bb55aaa555163fe53c894a3f7ef8528f7229e29b652205b27dceb/python/devguide/issues/1821
og:image:altDescribe 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:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamesirosen
hostnamegithub.com
expected-hostnamegithub.com
Nonef420f4996e6b1ff1ccd6d7683f8134f4b5f0f8a50124c210dbfe7490e5644abb
turbo-cache-controlno-preview
go-importgithub.com/python/devguide git https://github.com/python/devguide.git
octolytics-dimension-user_id1525981
octolytics-dimension-user_loginpython
octolytics-dimension-repository_id63972479
octolytics-dimension-repository_nwopython/devguide
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id63972479
octolytics-dimension-repository_network_root_nwopython/devguide
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release26e00df917aba0f128135dc073ea0c5e33a70d40
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/python/devguide/issues/1821#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython%2Fdevguide%2Fissues%2F1821
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fpython%2Fdevguide%2Fissues%2F1821
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=python%2Fdevguide
Reloadhttps://github.com/python/devguide/issues/1821
Reloadhttps://github.com/python/devguide/issues/1821
Reloadhttps://github.com/python/devguide/issues/1821
pythonhttps://github.com/python
devguidehttps://github.com/python/devguide
Codehttps://github.com/python/devguide
Issues83 (83)https://github.com/python/devguide/issues
Pull requests41 (41)https://github.com/python/devguide/pulls
Actionshttps://github.com/python/devguide/actions
Projectshttps://github.com/python/devguide/projects
Security and qualityhttps://github.com/python/devguide/security
Insightshttps://github.com/python/devguide/insights
https://github.com/python/devguide
New issuehttps://github.com/login?return_to=https://github.com/python/devguide/issues/1821
New issuehttps://github.com/login?return_to=https://github.com/python/devguide/issues/1821
#1828https://github.com/python/devguide/pull/1828
Feature: Expand the style-guide to cover how type names should be written in prosehttps://github.com/python/devguide/issues/1821#top
#1828https://github.com/python/devguide/pull/1828
type-featureAdditions; New content or section neededhttps://github.com/python/devguide/issues?q=state%3Aopen%20label%3A%22type-feature%22
https://github.com/sirosen
sirosenhttps://github.com/sirosen
on Jun 3, 2026https://github.com/python/devguide/issues/1821#issue-4582071676
specific words sectionhttps://devguide.python.org/documentation/style-guide/#specific-words
a recent CPython docs PRhttps://github.com/python/cpython/pull/150325
deque docshttps://docs.python.org/3/library/collections.html#collections.deque
sirosenhttps://github.com/sirosen
type-featureAdditions; New content or section neededhttps://github.com/python/devguide/issues?q=state%3Aopen%20label%3A%22type-feature%22
on Jun 3, 2026https://github.com/python/devguide/issues/1821#event-26298276269
https://github.com/sirosen
sirosenhttps://github.com/sirosen
on Jun 3, 2026https://github.com/python/devguide/issues/1821#issuecomment-4615091402
@picnixzhttps://github.com/picnixz
python/cpython#150325https://github.com/python/cpython/pull/150325
https://github.com/nedbat
nedbathttps://github.com/nedbat
on Jun 27, 2026https://github.com/python/devguide/issues/1821#issuecomment-4822446152
https://github.com/sirosen
sirosenhttps://github.com/sirosen
on Jun 28, 2026https://github.com/python/devguide/issues/1821#issuecomment-4824286385
hugovkhttps://github.com/hugovk
completedhttps://github.com/python/devguide/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
#1828https://github.com/python/devguide/pull/1828
on Jul 5, 2026https://github.com/python/devguide/issues/1821#event-27575417957
Sign up for freehttps://github.com/signup?return_to=https://github.com/python/devguide/issues/1821
Sign in to commenthttps://github.com/login?return_to=https://github.com/python/devguide/issues/1821
type-featureAdditions; New content or section neededhttps://github.com/python/devguide/issues?q=state%3Aopen%20label%3A%22type-feature%22
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.