Format docstrings according to PEP 257

piptools/cache.py

@@ -21,6 +21,8 @@
 
 def _implementation_name() -> str:
     """
+    Get Python implementation and version.
+
     Similar to PEP 425, however the minor version is separated from the major to
     differentiate "3.10" and "31.0".
     """
@@ -57,7 +59,8 @@ def read_cache_file(cache_file_path: str) -> CacheDict:
 
 class DependencyCache:
     """
-    Creates a new persistent dependency cache for the current Python version.
+    Create new persistent dependency cache for the current Python version.
+
     The cache file is written to the appropriate user cache dir for the
     current platform, i.e.
 
@@ -89,7 +92,9 @@ def cache(self) -> CacheDict:
 
     def as_cache_key(self, ireq: InstallRequirement) -> CacheKey:
         """
-        Given a requirement, return its cache key. This behavior is a little weird
+        Given a requirement, return its cache key.
+
+        This behavior is a little weird
         in order to allow backwards compatibility with cache files. For a requirement
         without extras, this will return, for example:
 
@@ -108,7 +113,7 @@ def as_cache_key(self, ireq: InstallRequirement) -> CacheKey:
         return name, f"{version}{extras_string}"
 
     def write_cache(self) -> None:
-        """Writes the cache to disk as JSON."""
+        """Write the cache to disk as JSON."""
         doc = {"__format__": 1, "dependencies": self._cache}
         with open(self._cache_file, "w", encoding="utf-8") as f:
             json.dump(doc, f, sort_keys=True)
@@ -135,7 +140,7 @@ def reverse_dependencies(
         self, ireqs: Iterable[InstallRequirement]
     ) -> dict[str, set[str]]:
         """
-        Returns a lookup table of reverse dependencies for all the given ireqs.
+        Return a lookup table of reverse dependencies for all the given ireqs.
 
         Since this is all static, it only works if the dependency cache
         contains the complete data, otherwise you end up with a partial view.
@@ -149,7 +154,7 @@ def _reverse_dependencies(
         self, cache_keys: Iterable[tuple[str, str]]
     ) -> dict[str, set[str]]:
         """
-        Returns a lookup table of reverse dependencies for all the given cache keys.
+        Return a lookup table of reverse dependencies for all the given cache keys.
 
         Example input:
 

piptools/resolver.py

@@ -161,8 +161,8 @@ def resolve(self, max_rounds: int) -> set[InstallRequirement]:
     def resolve_hashes(
         self, ireqs: set[InstallRequirement]
     ) -> dict[InstallRequirement, set[str]]:
-        """
-        Find acceptable hashes for all of the given ``InstallRequirement``'s.
+        r"""
+        Find acceptable hashes for all of the given ``InstallRequirement``\ s.
         """
         log.debug("")
         log.debug("Generating hashes:")
@@ -174,8 +174,8 @@ def _filter_out_unsafe_constraints(
         ireqs: set[InstallRequirement],
         unsafe_packages: Container[str],
     ) -> None:
-        """
-        Remove from a given set of ``InstallRequirement``'s unsafe constraints.
+        r"""
+        Remove from a given set of ``InstallRequirement``\ s unsafe constraints.
         """
         for req in ireqs.copy():
             if req.name in unsafe_packages:
@@ -184,6 +184,12 @@ def _filter_out_unsafe_constraints(
 
 
 class LegacyResolver(BaseResolver):
+    """
+    Resolve a given set of constraints (a collection of
+    InstallRequirement objects) by consulting the given Repository and the
+    DependencyCache.
+    """
+
     def __init__(
         self,
         constraints: Iterable[InstallRequirement],
@@ -195,11 +201,6 @@ def __init__(
         allow_unsafe: bool = False,
         unsafe_packages: set[str] | None = None,
     ) -> None:
-        """
-        This class resolves a given set of constraints (a collection of
-        InstallRequirement objects) by consulting the given Repository and the
-        DependencyCache.
-        """
         self.our_constraints = set(constraints)
         self.their_constraints: set[InstallRequirement] = set()
         self.repository = repository
@@ -226,10 +227,10 @@ def constraints(self) -> set[InstallRequirement]:
         )
 
     def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]:
-        """
+        r"""
         Find concrete package versions for all the given InstallRequirements
         and their recursive dependencies and return a set of pinned
-        ``InstallRequirement``'s.
+        ``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
@@ -279,8 +280,9 @@ def _group_constraints(
         self, constraints: Iterable[InstallRequirement]
     ) -> Iterator[InstallRequirement]:
         """
-        Groups constraints (remember, InstallRequirements!) by their key name,
-        and combining their SpecifierSets into a single InstallRequirement per
+        Group constraints (remember, InstallRequirements!) by their key name.
+
+        Then combine their SpecifierSets into a single InstallRequirement per
         package.  For example, given the following constraints:
 
             Django<1.9,>=1.4.2
@@ -313,9 +315,11 @@ def _group_constraints(
 
     def _resolve_one_round(self) -> tuple[bool, set[InstallRequirement]]:
         """
-        Resolves one level of the current constraints, by finding the best
-        match for each package in the repository and adding all requirements
-        for those best package versions.  Some of these constraints may be new
+        Resolve one level of the current constraints.
+
+        This is achieved by finding the best match for each package
+        in the repository and adding all requirements for those best
+        package versions.  Some of these constraints may be new
         or updated.
 
         Returns whether new constraints appeared in this round.  If no
@@ -373,9 +377,10 @@ def _resolve_one_round(self) -> tuple[bool, set[InstallRequirement]]:
 
     def get_best_match(self, ireq: InstallRequirement) -> InstallRequirement:
         """
-        Returns a (pinned or editable) InstallRequirement, indicating the best
-        match to use for the given InstallRequirement (in the form of an
-        InstallRequirement).
+        Return a (pinned or editable) InstallRequirement.
+
+        This indicates the best match to use for the given
+        InstallRequirement (in the form of an InstallRequirement).
 
         Example:
         Given the constraint Flask>=0.10, may return Flask==0.10.1 at
@@ -418,6 +423,8 @@ def _iter_dependencies(
         self, ireq: InstallRequirement
     ) -> Iterator[InstallRequirement]:
         """
+        Collect all secondary dependencies for an ireq.
+
         Given a pinned, url, or editable InstallRequirement, collects all the
         secondary dependencies for them, either by looking them up in a local
         cache, or by reaching out to the repository.
@@ -481,7 +488,7 @@ def _ireqs_of_dependencies(
 
 
 class BacktrackingResolver(BaseResolver):
-    """A wrapper for backtracking resolver."""
+    """A wrapper for the backtracking (or 2020) resolver."""
 
     def __init__(
         self,
@@ -523,10 +530,12 @@ def __init__(
         )
 
     def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]:
-        """
+        r"""
+        Resolve given ireqs.
+
         Find concrete package versions for all the given InstallRequirements
         and their recursive dependencies and return a set of pinned
-        ``InstallRequirement``'s.
+        ``InstallRequirement``\ s.
         """
         with update_env_context_manager(
             PIP_EXISTS_ACTION="i"
@@ -631,7 +640,9 @@ def _do_resolve(
         compatible_existing_constraints: dict[str, InstallRequirement],
     ) -> bool:
         """
-        Return true on successful resolution, otherwise remove problematic
+        Actual resolution process.
+
+        Return True on successful resolution, otherwise remove problematic
         requirements from existing constraints and return false.
         """
         try:

piptools/scripts/compile.py

@@ -49,6 +49,7 @@ def _determine_linesep(
 ) -> str:
     """
     Determine and return linesep string for OutputWriter to use.
+
     Valid strategies: "LF", "CRLF", "native", "preserve"
     When preserving, files are checked in order for existing newlines.
     """
@@ -169,7 +170,9 @@ def cli(
     only_build_deps: bool,
 ) -> None:
     """
-    Compiles requirements.txt from requirements.in, pyproject.toml, setup.cfg,
+    Compile requirements.txt from source files.
+
+    Valid sources are requirements.in, pyproject.toml, setup.cfg,
     or setup.py specs.
     """
     if color is not None:

piptools/subprocess_utils.py

@@ -7,7 +7,7 @@
 
 def run_python_snippet(python_executable: str, code_to_run: str) -> str:
     """
-    Executes python code by calling python_executable with '-c' option.
+    Execute Python code by calling ``python_executable`` with '-c' option.
     """
     py_exec_cmd = python_executable, "-c", code_to_run
 

piptools/sync.py

@@ -43,9 +43,10 @@
 def dependency_tree(
     installed_keys: Mapping[str, Distribution], root_key: str
 ) -> set[str]:
-    """
-    Calculate the dependency tree for the package ``root_key`` and return
-    a collection of all its dependencies. Uses a DFS traversal algorithm.
+    """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')}
@@ -78,9 +79,9 @@ def dependency_tree(
 
 
 def get_dists_to_ignore(installed: Iterable[Distribution]) -> list[str]:
-    """
-    Returns a collection of package names to ignore when performing pip-sync,
-    based on the currently installed environment.  For example, when pip-tools
+    """Return a collection of package names to ignore by ``pip-sync``.
+
+    Based on the currently installed environment.  For example, when pip-tools
     is installed in the local environment, it should be ignored, including all
     of its dependencies (e.g. click).  When pip-tools is not installed
     locally, click should also be installed/uninstalled depending on the given
@@ -122,8 +123,8 @@ def merge(
 
 
 def diff_key_from_ireq(ireq: InstallRequirement) -> str:
-    """
-    Calculate a key for comparing a compiled requirement with installed modules.
+    """Calculate key for comparing a compiled requirement with installed modules.
+
     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
@@ -159,9 +160,10 @@ def diff(
     compiled_requirements: Iterable[InstallRequirement],
     installed_dists: Iterable[Distribution],
 ) -> tuple[set[InstallRequirement], set[str]]:
-    """
-    Calculate which packages should be installed or uninstalled, given a set
-    of compiled requirements and a list of currently installed modules.
+    """Calculate which packages should be installed or uninstalled.
+
+    Compared are the compiled requirements and a list of currently
+    installed modules.
     """
     requirements_lut = {diff_key_from_ireq(r): r for r in compiled_requirements}
 
@@ -195,9 +197,7 @@ def sync(
     ask: bool = False,
     python_executable: str | None = None,
 ) -> int:
-    """
-    Install and uninstalls the given sets of modules.
-    """
+    """Install and uninstall the given sets of modules."""
     exit_code = 0
 
     python_executable = python_executable or sys.executable