From dbaaef14f2f1629f7d9329b4f9b4e5a69c642e10 Mon Sep 17 00:00:00 2001 From: chrysle <96722107+chrysle@users.noreply.github.com> Date: Sun, 12 May 2024 09:00:14 +0200 Subject: [PATCH] Use reST docstring formatting where appropriate --- docs/conf.py | 1 + piptools/_compat/pip_compat.py | 11 ++++++-- piptools/resolver.py | 51 +++++++++++++++++++++++----------- piptools/sync.py | 7 +++-- piptools/utils.py | 2 +- tox.ini | 3 +- 6 files changed, 51 insertions(+), 24 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index cb0a99179..0aa707bfd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -81,6 +81,7 @@ ("py:class", "_ImportLibDist"), ("py:class", "PackageMetadata"), ("py:class", "importlib.*"), + ("py:class", "IndexContent"), ("py:exc", "click.*"), ] diff --git a/piptools/_compat/pip_compat.py b/piptools/_compat/pip_compat.py index d956ab245..31c45f9a1 100644 --- a/piptools/_compat/pip_compat.py +++ b/piptools/_compat/pip_compat.py @@ -50,9 +50,12 @@ def _from_pkg_resources(cls, dist: _PkgResourcesDist) -> Distribution: @classmethod def _from_importlib(cls, dist: _ImportLibDist) -> Distribution: - """Mimics pkg_resources.Distribution.requires for the case of no - extras. This doesn't fulfill that API's `extras` parameter but - satisfies the needs of pip-tools.""" + """Mimic pkg_resources.Distribution.requires for the case of no + extras. + + This doesn't fulfill that API's ``extras`` parameter but + satisfies the needs of pip-tools. + """ reqs = (Requirement.parse(req) for req in (dist._dist.requires or ())) requires = [ req @@ -63,6 +66,8 @@ def _from_importlib(cls, dist: _ImportLibDist) -> Distribution: class FileLink(Link): # type: ignore[misc] + """Wrapper for ``pip``'s ``Link`` class.""" + _url: str @property diff --git a/piptools/resolver.py b/piptools/resolver.py index 5ef339057..f784ffe13 100644 --- a/piptools/resolver.py +++ b/piptools/resolver.py @@ -152,10 +152,10 @@ class BaseResolver(metaclass=ABCMeta): @abstractmethod def resolve(self, max_rounds: int) -> set[InstallRequirement]: - """ + r""" Find concrete package versions for all the given InstallRequirements - and their recursive dependencies and return a set of pinned - ``InstallRequirement``'s. + and their recursive dependencies. + :returns: a set of pinned ``InstallRequirement``\ s. """ def resolve_hashes( @@ -199,9 +199,24 @@ def __init__( allow_unsafe: bool = False, unsafe_packages: set[str] | None = None, ) -> None: - """ - Make sure the legacy resolver is enabled and no backtracking resolver - is present. + """Initialize LegacyResolver. + + :param constraints: the constraints given + :type constraints: Iterable[InstallRequirement] + :param existing_constraints: constraints already present + :param repository: the repository to get the constraints from + :type repository: BaseRepository + :param cache: the cache to be used + :param prereleases: whether prereleases should be taken into account when resolving + (default is :py:data:`False`) + :param clear_caches: whether to clear repository and dependency caches before resolving + (default is :py:data:`False`) + :param allow_unsafe: whether unsafe packages should be allowed in the resulting requirements + (default is :py:data:`False`) + :param unsafe_packages: packages to be considered as unsafe + (default is :py:data:`None`) + :type unsafe_packages: set[str] + :raises: ``PipToolsError`` if the legacy resolver is not enabled """ self.our_constraints = set(constraints) self.their_constraints: set[InstallRequirement] = set() @@ -230,13 +245,15 @@ def constraints(self) -> set[InstallRequirement]: def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]: r""" - Find concrete package versions for all the given InstallRequirements + Find concrete package versions for all the given ``InstallRequirement``\ s and their recursive dependencies and return a set of pinned ``InstallRequirement``\ s. Resolves constraints one round at a time, until they don't change - anymore. Protects against infinite loops by breaking out after a max - number rounds. + anymore. + + :param max_rounds: break out of resolution process after the given number of rounds + to prevent infinite loops (default is 10) """ if self.clear_caches: self.dependency_cache.clear() @@ -324,9 +341,9 @@ def _resolve_one_round(self) -> tuple[bool, set[InstallRequirement]]: package versions. Some of these constraints may be new or updated. - Returns whether new constraints appeared in this round. If no - constraints were added or changed, this indicates a stable - configuration. + :returns: whether new constraints appeared in this round. If no + constraints were added or changed, this indicates a stable + configuration. """ # Sort this list for readability of terminal output constraints = sorted(self.constraints, key=key_from_ireq) @@ -536,8 +553,9 @@ def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]: Resolve given ireqs. Find concrete package versions for all the given InstallRequirements - and their recursive dependencies and return a set of pinned - ``InstallRequirement``\ s. + and their recursive dependencies. + + :returns: A set of pinned ``InstallRequirement``\ s. """ with update_env_context_manager( PIP_EXISTS_ACTION="i" @@ -644,8 +662,9 @@ def _do_resolve( """ Resolve dependencies based on resolvelib ``Resolver``. - Return :py:data:`True` on successful resolution, otherwise remove problematic - requirements from existing constraints and return false. + :returns: :py:data:`True` on successful resolution, otherwise removes + problematic requirements from existing constraints and + returns :py:data:`False`. """ try: resolver.resolve( diff --git a/piptools/sync.py b/piptools/sync.py index cb50618e7..5408fd858 100644 --- a/piptools/sync.py +++ b/piptools/sync.py @@ -43,14 +43,15 @@ def dependency_tree( installed_keys: Mapping[str, Distribution], root_key: str ) -> set[str]: - """Calculate the dependency tree for a package + """Calculate the dependency tree for a package. Return a collection of all of the package's dependencies. Uses a DFS traversal algorithm. ``installed_keys`` should be a {key: requirement} mapping, e.g. {'django': from_line('django==1.8')} - ``root_key`` should be the key to return the dependency tree for. + :param root_key: the key to return the dependency tree for + :type root_key: str """ dependencies = set() queue: Deque[Distribution] = collections.deque() @@ -127,7 +128,7 @@ def diff_key_from_ireq(ireq: InstallRequirement) -> str: For URL requirements, only provide a useful key if the url includes a hash, e.g. #sha1=..., in any of the supported hash algorithms. - Otherwise return ireq.link so the key will not match and the package will + Otherwise return ``ireq.link`` so the key will not match and the package will reinstall. Reinstall is necessary to ensure that packages will reinstall if the contents at the URL have changed but the version has not. """ diff --git a/piptools/utils.py b/piptools/utils.py index 978551e40..8073f5d76 100644 --- a/piptools/utils.py +++ b/piptools/utils.py @@ -544,7 +544,7 @@ def override_defaults_from_config_file( file, returning the ``pathlib.Path`` of that config file if specified or discovered. - Return :py:data:`None` if no such file is found. + :returns: :py:data:`None` if no such file is found. ``pip-tools`` will use the first config file found, searching in this order: an explicitly given config file, a ``.pip-tools.toml``, a ``pyproject.toml`` diff --git a/tox.ini b/tox.ini index 5ded61bbe..bb740ee35 100644 --- a/tox.ini +++ b/tox.ini @@ -52,8 +52,9 @@ skip_install = true [testenv:pip-compile-docs] description = compile requirements for the documentation +changedir = {[testenv:build-docs]changedir} commands_pre = -commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs} +commands = python -m piptools compile --strip-extras --allow-unsafe --quiet requirements.in {posargs} [testenv:build-docs] description = build the documentation