From cc7ff422333eb901a414f6cf59da7d7abc8c5886 Mon Sep 17 00:00:00 2001 From: r266-tech <233881301+r266-tech@users.noreply.github.com> Date: Mon, 24 Aug 2026 17:03:12 +0000 Subject: [PATCH 1/2] Move documentation to use sphinx.ext.autodoc --- docs/pylock.rst | 37 +++++++++++++--- docs/requirements.rst | 72 +++---------------------------- src/packaging/pylock.py | 80 ++++++++++++++++++++++++++++++++++- src/packaging/requirements.py | 20 ++++++++- 4 files changed, 133 insertions(+), 76 deletions(-) diff --git a/docs/pylock.rst b/docs/pylock.rst index e03c156d2..089998dbf 100644 --- a/docs/pylock.rst +++ b/docs/pylock.rst @@ -88,20 +88,43 @@ structure of a pylock file. The attributes correspond to the fields in the pylock file specification. .. autoclass:: Pylock - :members: from_dict, to_dict, validate, select + :members: lock_version, environments, requires_python, extras, + dependency_groups, default_groups, created_by, packages, tool, + from_dict, to_dict, validate, select + :undoc-members: :exclude-members: __init__, __new__ -.. class:: Package +.. autoclass:: Package + :members: name, version, marker, requires_python, dependencies, vcs, + directory, archive, index, sdist, wheels, attestation_identities, tool, + is_direct + :undoc-members: + :exclude-members: __init__, __new__ -.. class:: PackageWheel +.. autoclass:: PackageWheel + :members: name, upload_time, url, path, size, hashes, filename + :undoc-members: + :exclude-members: __init__, __new__ -.. class:: PackageSdist +.. autoclass:: PackageSdist + :members: name, upload_time, url, path, size, hashes, filename + :undoc-members: + :exclude-members: __init__, __new__ -.. class:: PackageArchive +.. autoclass:: PackageArchive + :members: url, path, size, upload_time, hashes, subdirectory + :undoc-members: + :exclude-members: __init__, __new__ -.. class:: PackageVcs +.. autoclass:: PackageVcs + :members: type, url, path, requested_revision, commit_id, subdirectory + :undoc-members: + :exclude-members: __init__, __new__ -.. class:: PackageDirectory +.. autoclass:: PackageDirectory + :members: path, editable, subdirectory + :undoc-members: + :exclude-members: __init__, __new__ The following exceptions may be raised by this module: diff --git a/docs/requirements.rst b/docs/requirements.rst index f314ac790..1d0c68e93 100644 --- a/docs/requirements.rst +++ b/docs/requirements.rst @@ -72,70 +72,10 @@ Usage Reference --------- -.. class:: Requirement(requirement_string) +.. autoclass:: Requirement + :members: name, url, extras, specifier, marker + :undoc-members: + :exclude-members: __init__, __new__ - This class abstracts handling the details of a requirement for a project. - Each requirement will be parsed according to the specification. - - .. versionadded:: 16.1 - - .. versionchanged:: 22.0 - Added equality (``__eq__``) and hashing (``__hash__``) so requirements - can be compared and stored in sets / dicts. - - .. versionchanged:: 23.2 - Equality and hashing began canonicalizing requirement names, so - requirements whose names differ only by normalization (e.g. - ``Requirement("Foo")`` vs ``Requirement("foo")``) now compare and hash - equal. - - Instances are safe to serialize with :mod:`pickle`. They use a stable - format so the same pickle can be loaded in future packaging releases. - - .. versionchanged:: 26.2 - - Added a stable pickle format. Pickles created with packaging 26.2+ can - be unpickled with future releases. Backward compatibility with pickles - from packaging < 26.2 is supported but may be removed in a future - release. - - .. versionchanged:: 26.3 - - The dedicated pickle support introduced in 26.2 did not preserve the - specifier's explicit :attr:`~packaging.specifiers.SpecifierSet.prereleases` - override; it is now included again. - - Equality and hashing normalize extras and equivalent specifiers. The - string representation still preserves the parsed name and extras - spelling. - - :param str requirement_string: The string representation of a requirement. - :raises InvalidRequirement: If the given ``requirement_string`` is not parseable, - then this exception will be raised. - - .. attribute:: name - - The name of the requirement. - - .. attribute:: url - - The URL, if any, where to download the requirement from. Can be None. - - .. attribute:: extras - - A set of extras that the requirement specifies. - - .. attribute:: specifier - - A :class:`~.SpecifierSet` of the version specified by the requirement. - - .. attribute:: marker - - A :class:`~.Marker` of the marker for the requirement. Can be None. - -.. exception:: InvalidRequirement - - Raised when attempting to create a :class:`Requirement` with a string that - does not conform to the specification. - - .. versionadded:: 16.1 +.. autoexception:: InvalidRequirement + :exclude-members: __init__, __new__ diff --git a/src/packaging/pylock.py b/src/packaging/pylock.py index f981df976..243e68e6a 100644 --- a/src/packaging/pylock.py +++ b/src/packaging/pylock.py @@ -323,6 +323,16 @@ class PylockSelectError(Exception): @dataclass(frozen=True, kw_only=True, slots=True) class PackageVcs: + """A package installed from a version control system. + + :ivar str type: The version control system type. + :ivar str | None url: The repository URL, if one is provided. + :ivar str | None path: The repository path, if one is provided. + :ivar str | None requested_revision: The requested revision, if any. + :ivar str commit_id: The resolved commit identifier. + :ivar str | None subdirectory: A repository subdirectory, if selected. + """ + type: str url: str | None = None path: str | None = None @@ -346,6 +356,13 @@ def _from_dict(cls, d: Mapping[str, Any]) -> Self: @dataclass(frozen=True, kw_only=True, slots=True) class PackageDirectory: + """A package installed from a local directory. + + :ivar str path: The path to the package directory. + :ivar bool | None editable: Whether the package is installed editable. + :ivar str | None subdirectory: A package subdirectory, if selected. + """ + path: str editable: bool | None = None subdirectory: str | None = None @@ -361,6 +378,16 @@ def _from_dict(cls, d: Mapping[str, Any]) -> Self: @dataclass(frozen=True, kw_only=True, slots=True) class PackageArchive: + """A package installed from an archive. + + :ivar str | None url: The archive URL, if one is provided. + :ivar str | None path: The archive path, if one is provided. + :ivar int | None size: The archive size in bytes, if known. + :ivar datetime.datetime | None upload_time: The archive upload time, if known. + :ivar Mapping[str, str] hashes: Hashes for the archive. + :ivar str | None subdirectory: A package subdirectory, if selected. + """ + url: str | None = None path: str | None = None size: int | None = None @@ -384,6 +411,16 @@ def _from_dict(cls, d: Mapping[str, Any]) -> Self: @dataclass(frozen=True, kw_only=True, slots=True) class PackageSdist: + """A source distribution for a package. + + :ivar str | None name: The distribution filename, if provided. + :ivar datetime.datetime | None upload_time: The distribution upload time, if known. + :ivar str | None url: The distribution URL, if one is provided. + :ivar str | None path: The distribution path, if one is provided. + :ivar int | None size: The distribution size in bytes, if known. + :ivar Mapping[str, str] hashes: Hashes for the distribution. + """ + name: str | None = None upload_time: datetime | None = None url: str | None = None @@ -418,6 +455,16 @@ def filename(self) -> str: @dataclass(frozen=True, kw_only=True, slots=True) class PackageWheel: + """A wheel distribution for a package. + + :ivar str | None name: The distribution filename, if provided. + :ivar datetime.datetime | None upload_time: The distribution upload time, if known. + :ivar str | None url: The distribution URL, if one is provided. + :ivar str | None path: The distribution path, if one is provided. + :ivar int | None size: The distribution size in bytes, if known. + :ivar Mapping[str, str] hashes: Hashes for the distribution. + """ + name: str | None = None upload_time: datetime | None = None url: str | None = None @@ -449,6 +496,26 @@ def filename(self) -> str: @dataclass(frozen=True, kw_only=True, slots=True) class Package: + """A package entry in a pylock file. + + A package has either distribution files or one direct source (VCS, + directory, or archive). + + :ivar NormalizedName name: The normalized package name. + :ivar Version | None version: The package version, if known. + :ivar Marker | None marker: A marker restricting this package, if any. + :ivar SpecifierSet | None requires_python: The supported Python versions. + :ivar Sequence[Mapping[str, Any]] | None dependencies: Package dependencies. + :ivar PackageVcs | None vcs: A VCS source, if selected. + :ivar PackageDirectory | None directory: A directory source, if selected. + :ivar PackageArchive | None archive: An archive source, if selected. + :ivar str | None index: The package index name, if provided. + :ivar PackageSdist | None sdist: A source distribution, if provided. + :ivar Sequence[PackageWheel] | None wheels: Available wheel distributions. + :ivar Sequence[Mapping[str, Any]] | None attestation_identities: Attestations. + :ivar Mapping[str, Any] | None tool: Tool-specific metadata. + """ + name: NormalizedName version: Version | None = None marker: Marker | None = None @@ -551,7 +618,18 @@ def is_direct(self) -> bool: @dataclass(frozen=True, kw_only=True, slots=True) class Pylock: - """A class representing a pylock file.""" + """Represent a validated pylock file. + + :ivar Version lock_version: The pylock specification version. + :ivar Sequence[Marker] | None environments: Supported environments. + :ivar SpecifierSet | None requires_python: The supported Python versions. + :ivar Sequence[NormalizedName] | None extras: Extras provided by the lock. + :ivar Sequence[str] | None dependency_groups: Defined dependency groups. + :ivar Sequence[str] | None default_groups: Groups selected by default. + :ivar str created_by: The tool that created the lock file. + :ivar Sequence[Package] packages: Packages contained in the lock file. + :ivar Mapping[str, Any] | None tool: Tool-specific metadata. + """ lock_version: Version environments: Sequence[Marker] | None = None diff --git a/src/packaging/requirements.py b/src/packaging/requirements.py index adcc8adbb..aea9afa1a 100644 --- a/src/packaging/requirements.py +++ b/src/packaging/requirements.py @@ -26,14 +26,18 @@ def __dir__() -> list[str]: class InvalidRequirement(ValueError): """ - An invalid requirement was found, users should refer to PEP 508. + Raised when attempting to create a :class:`Requirement` with a string that + does not conform to the specification. Users should refer to PEP 508. .. versionadded:: 16.1 """ class Requirement: - """Parse a requirement. + """Represent a requirement for a project. + + This class abstracts handling the details of a requirement for a project. + Each requirement will be parsed according to the specification. Parse a given requirement string into its parts, such as name, specifier, URL, and extras. Raises InvalidRequirement on a badly-formed requirement @@ -70,6 +74,18 @@ class Requirement: Equality and hashing normalize requirement names, extras, and equivalent specifiers. The string representation still preserves the parsed name and extras spelling. + + :param str requirement_string: The string representation of a requirement. + :raises InvalidRequirement: If the given ``requirement_string`` is not + parseable, then this exception will be raised. + :ivar name: The name of the requirement. + :ivar url: The URL, if any, where to download the requirement from. Can be + ``None``. + :ivar extras: A set of extras that the requirement specifies. + :ivar specifier: A :class:`~.SpecifierSet` of the version specified by the + requirement. + :ivar marker: A :class:`~.Marker` of the marker for the requirement. Can be + ``None``. """ # TODO: Can we test whether something is contained within a requirement? From bc8580ba0723f2c647a5d54f397fe7fe858d282a Mon Sep 17 00:00:00 2001 From: r266-tech <233881301+r266-tech@users.noreply.github.com> Date: Wed, 26 Aug 2026 14:00:06 +0800 Subject: [PATCH 2/2] docs: align autodoc with module pattern --- docs/pylock.rst | 57 ++--------------------------------------- docs/requirements.rst | 9 ++----- src/packaging/pylock.py | 6 +++++ 3 files changed, 10 insertions(+), 62 deletions(-) diff --git a/docs/pylock.rst b/docs/pylock.rst index 089998dbf..7d9f8f88a 100644 --- a/docs/pylock.rst +++ b/docs/pylock.rst @@ -81,58 +81,5 @@ to the caller. Reference --------- -.. autofunction:: is_valid_pylock_path - -The following frozen keyword-only dataclasses are used to represent the -structure of a pylock file. The attributes correspond to the fields in the -pylock file specification. - -.. autoclass:: Pylock - :members: lock_version, environments, requires_python, extras, - dependency_groups, default_groups, created_by, packages, tool, - from_dict, to_dict, validate, select - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: Package - :members: name, version, marker, requires_python, dependencies, vcs, - directory, archive, index, sdist, wheels, attestation_identities, tool, - is_direct - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: PackageWheel - :members: name, upload_time, url, path, size, hashes, filename - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: PackageSdist - :members: name, upload_time, url, path, size, hashes, filename - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: PackageArchive - :members: url, path, size, upload_time, hashes, subdirectory - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: PackageVcs - :members: type, url, path, requested_revision, commit_id, subdirectory - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoclass:: PackageDirectory - :members: path, editable, subdirectory - :undoc-members: - :exclude-members: __init__, __new__ - -The following exceptions may be raised by this module: - -.. autoexception:: PylockValidationError - :exclude-members: __init__, __new__ - -.. autoexception:: PylockUnsupportedVersionError - :exclude-members: __init__, __new__ - -.. autoexception:: PylockSelectError - :exclude-members: __init__, __new__ +.. automodule:: packaging.pylock + :members: diff --git a/docs/requirements.rst b/docs/requirements.rst index 1d0c68e93..c4e495e49 100644 --- a/docs/requirements.rst +++ b/docs/requirements.rst @@ -72,10 +72,5 @@ Usage Reference --------- -.. autoclass:: Requirement - :members: name, url, extras, specifier, marker - :undoc-members: - :exclude-members: __init__, __new__ - -.. autoexception:: InvalidRequirement - :exclude-members: __init__, __new__ +.. automodule:: packaging.requirements + :members: diff --git a/src/packaging/pylock.py b/src/packaging/pylock.py index 243e68e6a..6facb9dc4 100644 --- a/src/packaging/pylock.py +++ b/src/packaging/pylock.py @@ -1,3 +1,9 @@ +"""Read, validate, and select from pylock files. + +The public data model classes are frozen, keyword-only dataclasses whose +attributes correspond to fields in the pylock file specification. +""" + from __future__ import annotations import dataclasses