gh-136145: Define 'standard library' and 'stdlib' in the glossary #136146
Conversation
bedevere-app
bot
added
awaiting core review
docs
zware
added
needs backport to 3.13
There was a problem hiding this comment.
I think of the x.y.z standard library as defined by the x.y.z docs, which may have OS availability notes. A particular distribution may include non-standard-library code, such a Tools and Scripts, or, once, Demo, which are not part of the stdlib. I believe non-CPython sometimes omit modules. Besides the variations mentioned, ctypes may not exist for non-C based implementatons, and others things may just not be implemented.
Doc/glossary.rst
Outdated
| The collection of :term:`packages <package>`, :term:`modules <module>` | ||
| and :term:`extension modules <extension module>` distributed as a part | ||
| of the official Python interpreter package, or an individual member of | ||
| that collection. The exact membership of the collection may vary based |
There was a problem hiding this comment.
As a noun, 'standard library' refers to the entire collecton. As an adjective, it can be applied to any member. Giving both definitions in one sentence is confusing.
| The collection of :term:`packages <package>`, :term:`modules <module>` | |
| and :term:`extension modules <extension module>` distributed as a part | |
| of the official Python interpreter package, or an individual member of | |
| that collection. The exact membership of the collection may vary based | |
| The collection of :term:`packages <package>`, :term:`modules <module>` | |
| and :term:`extension modules <extension module>` distributed as a part | |
| of the official Python interpreter package. As an adjective, "a member of" | |
| that collection. The exact membership of the collection may vary based |
There was a problem hiding this comment.
I think I'd prefer to just leave out that sentence.
My intention was to cover the (admittedly rare) use of "standard library" to refer to an individual library, such as "... the json standard library." But, I suppose that's still the adjective case, where "module" is implicit after "library" and really it's just superfluous.
|
When you're done making the requested changes, leave the comment: |
| @@ -1290,6 +1297,9 @@ Glossary | |||
| issues such as incorrect types. See also :term:`type hints <type hint>` | |||
| and the :mod:`typing` module. | |||
|
|
|||
| stdlib | |||
| An abbreviation of :term:`standard library`. | |||
There was a problem hiding this comment.
Should we hint that this isn't the appropriate term to use in CPython docs?
| An abbreviation of :term:`standard library`. | |
| An informal abbreviation of :term:`standard library`. |
There was a problem hiding this comment.
Should we hint that this isn't the appropriate term to use in CPython docs?
Seems reasonable ... could use "unofficial" as an alternative to "informal". (seems like this small change has gotten a little nitpicky, so I won't go on)
There was a problem hiding this comment.
Both "informal" and "unofficial" works for me. But I agree that it's better with adjective.
There was a problem hiding this comment.
Given that we use the term in places like sys.stdlib_module_names, is it "informal" or "unofficial"? There could be a case for the former, but I don't think we can say its "unofficial".
|
In the "standard library" entry, maybe also reference the The Python Standard Library page? |
Doc/glossary.rst
Outdated
| and :term:`extension modules <extension module>` distributed as a part | ||
| of the official Python interpreter package, or an individual member of | ||
| that collection. The exact membership of the collection may vary based | ||
| on platform, available system packages, or other criteria. |
There was a problem hiding this comment.
I suggest adding:
See also :data:`sys.stdlib_module_names`.
📚 Documentation preview 📚: https://cpython-previews--136146.org.readthedocs.build/