From 290ad202514ab34e7455e75171ef4c7424436cb8 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 --- piptools/resolver.py | 42 +++++++++++++++++++++++++++++------------- piptools/sync.py | 7 ++++--- piptools/utils.py | 2 +- tox.ini | 3 ++- 4 files changed, 36 insertions(+), 18 deletions(-) diff --git a/piptools/resolver.py b/piptools/resolver.py index 5359a95fa..91b77032f 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,14 @@ 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,7 +340,7 @@ 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 + :returns: whether new constraints appeared in this round. If no constraints were added or changed, this indicates a stable configuration. """ @@ -536,8 +552,8 @@ 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,7 +660,7 @@ def _do_resolve( """ Resolve dependencies based on resolvelib ``Resolver``. - Return :py:data:`True` on successful resolution, otherwise remove problematic + :returns: :py:data:`True` on successful resolution, otherwise remove problematic requirements from existing constraints and return false. """ try: 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 b94ae34f8..c80142ebb 100644 --- a/piptools/utils.py +++ b/piptools/utils.py @@ -531,7 +531,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