dependence 1.0.2__py3-none-any.whl → 1.2.5__py3-none-any.whl

dependence/freeze.py

@@ -1,23 +1,28 @@
+from __future__ import annotations
+
 import argparse
+import os
 from fnmatch import fnmatch
 from functools import partial
-from importlib.metadata import Distribution
-from importlib.metadata import distribution as _get_distribution
 from itertools import chain
-from typing import Dict, Iterable, MutableSet, Optional, Tuple, cast
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
 
-from ._utilities import (
+from dependence._utilities import (
     get_distribution,
     get_required_distribution_names,
     get_requirement_string_distribution_name,
-    install_requirement,
-    is_configuration_file,
     iter_configuration_file_requirement_strings,
+    iter_configuration_files,
     iter_distinct,
     iter_parse_delimited_values,
     normalize_name,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable, MutableSet
+    from importlib.metadata import Distribution
+
 _DO_NOT_PIN_DISTRIBUTION_NAMES: MutableSet[str] = {
     "importlib-metadata",
     "importlib-resources",
@@ -30,18 +35,18 @@ def _iter_sort_dependents_last(requirements: Iterable[str]) -> Iterable[str]:
     """
     requirements = list(requirements)
     distribution_name: str
-    distribution_requirement: Dict[str, str] = {
+    distribution_requirement: dict[str, str] = {
         get_requirement_string_distribution_name(requirement): requirement
         for requirement in requirements
     }
-    dependent_dependencies: Dict[str, MutableSet[str]] = {
+    dependent_dependencies: dict[str, MutableSet[str]] = {
         distribution_name: get_required_distribution_names(requirement)
         for distribution_name, requirement in distribution_requirement.items()
     }
     while dependent_dependencies:
         dependent: str
         dependencies: MutableSet[str]
-        item: Tuple[str, MutableSet[str]]
+        item: tuple[str, MutableSet[str]]
         for dependent, dependencies in sorted(  # noqa: C414
             tuple(dependent_dependencies.items()),
             key=lambda item: item[0].lower(),
@@ -71,17 +76,19 @@ def _iter_sort_dependents_last(requirements: Iterable[str]) -> Iterable[str]:
                 del dependent_dependencies[dependent]
 
 
-def get_frozen_requirements(
-    requirements: Iterable[str] = (),
+def get_frozen_requirements(  # noqa: C901
+    requirements: Iterable[str | Path] = (),
+    *,
     exclude: Iterable[str] = (),
     exclude_recursive: Iterable[str] = (),
+    keep_version_specifier: Iterable[str] = (),
     no_version: Iterable[str] = (),
     dependency_order: bool = False,
     reverse: bool = False,
-    depth: Optional[int] = None,
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
-) -> Tuple[str, ...]:
+    depth: int | None = None,
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
+) -> tuple[str, ...]:
     """
     Get the (frozen) requirements for one or more specified distributions or
     configuration files.
@@ -95,8 +102,14 @@ def get_frozen_requirements(
         exclude_recursive: One or more distributions to exclude/ignore.
             Note: Excluding a distribution here excludes all requirements which
             would be identified through recursion.
+        keep_version_specifier: Keep the original (non-frozen) version
+            specifier for package names matching any of these patterns. This
+            supercedes `no_version`, if both sets of patterns match a package
+            name.
         no_version: Exclude version numbers from the output
-            (only return distribution names)
+            (only return distribution names). This is superceded by
+            `keep_version_specifier`, if both sets of patterns match a package
+            name.
         dependency_order: Sort requirements so that dependents
             precede dependencies
         depth: Depth of recursive requirement discovery
@@ -105,34 +118,65 @@ def get_frozen_requirements(
         exclude_pointers: A tuple of JSON pointers indicating elements to
             exclude (defaults to no exclusions). Only applies to TOML files.
     """
-    # Separate requirement strings from requirement files
-    if isinstance(requirements, str):
-        requirements = {requirements}
+    if isinstance(requirements, (str, Path)):
+        requirements = {str(requirements)}
     else:
-        requirements = set(requirements)
+        requirements = set(map(str, requirements))
     if isinstance(no_version, str):
         no_version = (no_version,)
     elif not isinstance(no_version, tuple):
         no_version = tuple(no_version)
-    requirement_files: MutableSet[str] = set(
-        filter(is_configuration_file, requirements)
-    )
-    requirement_strings: MutableSet[str] = cast(
-        MutableSet[str], requirements - requirement_files
-    )
+    if isinstance(keep_version_specifier, str):
+        keep_version_specifier = (keep_version_specifier,)
+    elif not isinstance(keep_version_specifier, tuple):
+        keep_version_specifier = tuple(keep_version_specifier)
+    # Separate requirement strings from requirement files
+    configuration_files: dict[str, dict[str, tuple[str, ...]]] = {}
+    requirement_strings: MutableSet[str] = set()
+    requirement: str | Path
+    for requirement in requirements:
+        if TYPE_CHECKING:
+            assert isinstance(requirement, str)
+        requirement_configuration_files: set[str] = set(
+            iter_configuration_files(requirement)
+        )
+        if requirement_configuration_files:
+            is_directory: bool = os.path.isdir(requirement)
+            for (
+                requirement_configuration_file
+            ) in requirement_configuration_files:
+                configuration_files[requirement_configuration_file] = (
+                    {"include_pointers": ("/project",)}
+                    if (
+                        is_directory
+                        and os.path.basename(
+                            requirement_configuration_file
+                        ).lower()
+                        == "pyproject.toml"
+                    )
+                    else {
+                        "include_pointers": include_pointers,
+                        "exclude_pointers": exclude_pointers,
+                    }
+                )
+        else:
+            if requirement.startswith("setup.py"):
+                raise ValueError(requirement)
+            requirement_strings.add(requirement)
+    configuration_file: str
+    kwargs: dict[str, tuple[str, ...]]
     frozen_requirements: Iterable[str] = iter_distinct(
         chain(
             requirement_strings,
-            *map(
-                partial(
-                    iter_configuration_file_requirement_strings,
-                    include_pointers=include_pointers,
-                    exclude_pointers=exclude_pointers,
-                ),
-                requirement_files,
+            *(
+                iter_configuration_file_requirement_strings(
+                    configuration_file, **kwargs
+                )
+                for configuration_file, kwargs in configuration_files.items()
             ),
         )
     )
+    frozen_requirements = tuple(frozen_requirements)
     if depth is not None:
         depth -= 1
     if (depth is None) or depth >= 0:
@@ -158,6 +202,7 @@ def get_frozen_requirements(
             ),
             exclude_recursive=set(map(normalize_name, exclude_recursive)),
             no_version=no_version,
+            keep_version_specifier=keep_version_specifier,
             depth=depth,
         )
     if dependency_order:
@@ -183,34 +228,47 @@ def _iter_frozen_requirements(
     exclude: MutableSet[str],
     exclude_recursive: MutableSet[str],
     no_version: Iterable[str] = (),
-    depth: Optional[int] = None,
+    depth: int | None = None,
+    keep_version_specifier: Iterable[str] = (),
 ) -> Iterable[str]:
-    def get_requirement_string(distribution_name: str) -> str:
-        def distribution_name_matches_pattern(pattern: str) -> bool:
-            return fnmatch(distribution_name, pattern)
+    # This retains a mapping of distribution names to their original
+    # requirement strings in order to return those which match
+    # `keep_version_specifier` patterns with their original specifiers
+    distribution_names_specifiers: dict[str, str] = {}
 
+    def get_requirement_string(distribution_name: str) -> str | None:
+        if distribution_names_specifiers and (
+            distribution_name in distribution_names_specifiers
+        ):
+            return distribution_names_specifiers[distribution_name]
         if (distribution_name in _DO_NOT_PIN_DISTRIBUTION_NAMES) or any(
-            map(distribution_name_matches_pattern, no_version)
+            fnmatch(distribution_name, pattern) for pattern in no_version
         ):
             return distribution_name
         distribution: Distribution
         try:
             distribution = get_distribution(distribution_name)
         except KeyError:
+            # If the distribution is not installed, skip it
+            return None
             # If the distribution is missing, install it
-            install_requirement(distribution_name, echo=False)
-            distribution = _get_distribution(distribution_name)
+            # install_requirement(distribution_name)
+            # distribution = _get_distribution(distribution_name)
         return f"{distribution.metadata['Name']}=={distribution.version}"
 
     def get_required_distribution_names_(
         requirement_string: str,
-        depth_: Optional[int] = None,
+        depth_: int | None = None,
     ) -> MutableSet[str]:
         name: str = get_requirement_string_distribution_name(
             requirement_string
         )
         if name in exclude_recursive:
             return set()
+        if keep_version_specifier and any(
+            fnmatch(name, pattern) for pattern in keep_version_specifier
+        ):
+            distribution_names_specifiers[name] = requirement_string.rstrip()
         distribution_names: MutableSet[str] = {name}
         if (depth_ is None) or depth_:
             distribution_names |= get_required_distribution_names(
@@ -219,7 +277,7 @@ def _iter_frozen_requirements(
                 depth=None if (depth_ is None) else depth_ - 1,
             )
         return cast(
-            MutableSet[str],
+            "MutableSet[str]",
             distribution_names - exclude,
         )
 
@@ -234,20 +292,20 @@ def _iter_frozen_requirements(
             )
         ),
     )
-    requirements = map(get_requirement_string, requirements)
-    return requirements
+    return filter(None, map(get_requirement_string, requirements))
 
 
 def freeze(
-    requirements: Iterable[str] = (),
+    requirements: Iterable[str | Path] = (),
+    *,
     exclude: Iterable[str] = (),
     exclude_recursive: Iterable[str] = (),
     no_version: Iterable[str] = (),
     dependency_order: bool = False,
     reverse: bool = False,
-    depth: Optional[int] = None,
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    depth: int | None = None,
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> None:
     """
     Print the (frozen) requirements for one or more specified requirements or
@@ -258,10 +316,10 @@ def freeze(
             "requirement-name[extra-a,extra-b]" or ".[extra-a, extra-b]) and/or
             paths to a setup.py, setup.cfg, pyproject.toml, tox.ini or
             requirements.txt file
-        exclude: One or more distributions to exclude/ignore
-        exclude_recursive: One or more distributions to exclude/ignore.
-            Note: Excluding a distribution here halts recursive
-            discovery of requirements.
+        exclude: One or more distributions to exclude.
+        exclude_recursive: One or more distributions to exclude. Recursive
+            dependency discovery is also halted for these distributions,
+            unlike those passed to `exclude`.
         no_version: Exclude version numbers from the output
             (only print distribution names) for package names matching any of
             these patterns
@@ -273,7 +331,7 @@ def freeze(
         exclude_pointers: If not empty, these TOML tables will *not* be
             inspected (for pyproject.toml files)
     """
-    print(
+    print(  # noqa: T201
         "\n".join(
             get_frozen_requirements(
                 requirements=requirements,

dependence/update.py

@@ -1,23 +1,18 @@
+from __future__ import annotations
+
 import argparse
 import re
 from collections import deque
 from configparser import ConfigParser, SectionProxy
 from copy import deepcopy
 from dataclasses import dataclass
-from importlib.metadata import Distribution
 from io import StringIO
 from itertools import chain
+from pathlib import Path
 from typing import (
     IO,
+    TYPE_CHECKING,
     Any,
-    Callable,
-    Dict,
-    Iterable,
-    List,
-    Optional,
-    Set,
-    Tuple,
-    Union,
 )
 
 import tomli
@@ -27,7 +22,7 @@ from packaging.specifiers import Specifier, SpecifierSet
 from packaging.version import Version
 from packaging.version import parse as parse_version
 
-from ._utilities import (
+from dependence._utilities import (
     ConfigurationFileType,
     get_configuration_file_type,
     get_installed_distributions,
@@ -38,6 +33,10 @@ from ._utilities import (
     normalize_name,
 )
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from importlib.metadata import Distribution
+
 
 @dataclass
 class _Version:
@@ -48,7 +47,7 @@ class _Version:
     """
 
     epoch: int
-    release: Tuple[int, ...]
+    release: tuple[int, ...]
     pre: Any
     post: Any
     dev: Any
@@ -64,13 +63,14 @@ def _update_requirement_specifiers(
     """
     installed_version: Version = parse_version(installed_version_string)
     specifier: Specifier
-    updated_specifier_strings: List[str] = []
+    updated_specifier_strings: list[str] = []
     for specifier in requirement.specifier:  # type: ignore
         # Only update requirement to match our installed version
         # if the requirement is *inclusive*
         if ("=" in specifier.operator) and ("!" not in specifier.operator):
             specifier_version: Version = parse_version(specifier.version)
-            assert installed_version.release is not None
+            if installed_version.release is None:
+                raise ValueError(installed_version)
             if specifier_version.release is None:
                 updated_specifier_strings.append(f"{specifier.operator}")
             else:
@@ -117,7 +117,7 @@ def _update_requirement_specifiers(
 
 
 def _get_updated_requirement_string(
-    requirement_string: str, ignore: Set[str]
+    requirement_string: str, ignore: set[str]
 ) -> str:
     """
     This function updates version numbers in a requirement string to match
@@ -132,15 +132,23 @@ def _get_updated_requirement_string(
         return requirement_string
     try:
         distribution: Distribution = get_installed_distributions()[name]
+        if distribution.version is None:
+            return requirement_string
         _update_requirement_specifiers(requirement, distribution.version)
     except KeyError:
         # If the requirement isn't installed, we can't update the version
         pass
+    except TypeError as error:
+        message: str = (
+            f"Unable to determine installed version for {requirement_string}: "
+            f"{distribution!r}"
+        )
+        raise ValueError(message) from error
     return str(requirement)
 
 
-def _normalize_ignore_argument(ignore: Iterable[str]) -> Set[str]:
-    ignore_set: Set[str]
+def _normalize_ignore_argument(ignore: Iterable[str]) -> set[str]:
+    ignore_set: set[str]
     # Normalize/harmonize excluded project names
     if isinstance(ignore, str):
         ignore = (ignore,)
@@ -161,7 +169,7 @@ def _get_updated_requirements_txt(
     - data (str): The contents of a *requirements.txt* file
     - ignore ([str]): One or more project names to leave as-is
     """
-    ignore_set: Set[str] = _normalize_ignore_argument(ignore)
+    ignore_set: set[str] = _normalize_ignore_argument(ignore)
 
     def get_updated_requirement_string(requirement: str) -> str:
         return _get_updated_requirement_string(requirement, ignore=ignore_set)
@@ -184,7 +192,7 @@ def _get_updated_setup_cfg(
     - all_extra_name (str): An (optional) extra name which will
       consolidate requirements from all other extras
     """
-    ignore_set: Set[str] = _normalize_ignore_argument(ignore)
+    ignore_set: set[str] = _normalize_ignore_argument(ignore)
 
     def get_updated_requirement_string(requirement: str) -> str:
         return _get_updated_requirement_string(requirement, ignore=ignore_set)
@@ -202,10 +210,10 @@ def _get_updated_setup_cfg(
         )
     if "options.extras_require" in parser:
         extras_require: SectionProxy = parser["options.extras_require"]
-        all_extra_requirements: List[str] = []
+        all_extra_requirements: list[str] = []
         extra_name: str
         extra_requirements_string: str
-        extra_requirements: List[str]
+        extra_requirements: list[str]
         for extra_name, extra_requirements_string in extras_require.items():
             if extra_name != all_extra_name:
                 extra_requirements = list(
@@ -223,7 +231,7 @@ def _get_updated_setup_cfg(
             # We pre-pend an empty requirement string in order to]
             # force new-line creation at the beginning of the extra
             extras_require[all_extra_name] = "\n".join(
-                iter_distinct([""] + all_extra_requirements)
+                iter_distinct(["", *all_extra_requirements])
             )
     # Return as a string
     setup_cfg: str
@@ -246,10 +254,10 @@ def _get_updated_tox_ini(data: str, ignore: Iterable[str] = ()) -> str:
     - data (str): The contents of a **tox.ini** file
     - ignore ([str]): One or more project names to leave as-is
     """
-    ignore_set: Set[str] = _normalize_ignore_argument(ignore)
+    ignore_set: set[str] = _normalize_ignore_argument(ignore)
 
     def get_updated_requirement_string(requirement: str) -> str:
-        prefix: Optional[str] = None
+        prefix: str | None = None
         if ":" in requirement:
             prefix, requirement = requirement.split(":", maxsplit=1)
         requirement = _get_updated_requirement_string(
@@ -294,18 +302,18 @@ def _get_updated_tox_ini(data: str, ignore: Iterable[str] = ()) -> str:
 
 
 def _update_document_requirements(
-    document: Dict[str, Any],
+    document: dict[str, Any],
     ignore: Iterable[str] = (),
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> None:
-    ignore_set: Set[str] = _normalize_ignore_argument(ignore)
+    ignore_set: set[str] = _normalize_ignore_argument(ignore)
 
     def get_updated_requirement_string(requirement: str) -> str:
         return _get_updated_requirement_string(requirement, ignore=ignore_set)
 
     # Find and update requirements
-    requirements_list: List[str]
+    requirements_list: list[str]
     for requirements_list in iter_find_requirements_lists(
         document,
         include_pointers=include_pointers,
@@ -323,8 +331,8 @@ def _get_updated_pyproject_toml(
     data: str,
     ignore: Iterable[str] = (),
     all_extra_name: str = "",
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> str:
     """
     Return the contents of a *pyproject.toml* file, updated to reflect the
@@ -345,8 +353,8 @@ def _get_updated_pyproject_toml(
         The contents of the updated pyproject.toml file.
     """
     # Parse pyproject.toml
-    original_pyproject: Dict[str, Any] = tomli.loads(data)
-    updated_pyproject: Dict[str, Any] = deepcopy(original_pyproject)
+    original_pyproject: dict[str, Any] = tomli.loads(data)
+    updated_pyproject: dict[str, Any] = deepcopy(original_pyproject)
     # Find and update requirements
     _update_document_requirements(
         updated_pyproject,
@@ -355,13 +363,13 @@ def _get_updated_pyproject_toml(
         exclude_pointers=exclude_pointers,
     )
     # Update consolidated optional requirements
-    project_optional_dependencies: Dict[str, List[str]] = (
+    project_optional_dependencies: dict[str, list[str]] = (
         updated_pyproject.get("project", {}).get("optional-dependencies", {})
     )
     # Update an extra indicated to encompass all other extras
     if project_optional_dependencies and all_extra_name:
         key: str
-        dependencies: List[str]
+        dependencies: list[str]
         project_optional_dependencies[all_extra_name] = list(
             iter_distinct(
                 chain(
@@ -384,8 +392,8 @@ def _get_updated_pyproject_toml(
 def _get_updated_toml(
     data: str,
     ignore: Iterable[str] = (),
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> str:
     """
     Return the contents of a TOML file, updated to reflect the
@@ -407,8 +415,8 @@ def _get_updated_toml(
         The contents of the updated TOML file.
     """
     # Parse pyproject.toml
-    original_pyproject: Dict[str, Any] = tomli.loads(data)
-    updated_pyproject: Dict[str, Any] = deepcopy(original_pyproject)
+    original_pyproject: dict[str, Any] = tomli.loads(data)
+    updated_pyproject: dict[str, Any] = deepcopy(original_pyproject)
     # Find and update requirements
     _update_document_requirements(
         updated_pyproject,
@@ -423,15 +431,16 @@ def _get_updated_toml(
 
 
 def _update(
-    path: str,
+    path: str | Path,
     ignore: Iterable[str] = (),
     all_extra_name: str = "",
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> None:
+    message: str
     data: str
     update_function: Callable[[str], str]
-    kwargs: Dict[str, Union[str, Iterable[str]]] = {}
+    kwargs: dict[str, str | Iterable[str]] = {}
     configuration_file_type: ConfigurationFileType = (
         get_configuration_file_type(path)
     )
@@ -457,49 +466,58 @@ def _update(
     elif configuration_file_type == ConfigurationFileType.REQUIREMENTS_TXT:
         update_function = _get_updated_requirements_txt
     else:
-        raise NotImplementedError(
-            f"Updating requirements for {path} is not supported"
-        )
+        message = f"Updating requirements for {path!s} is not supported"
+        raise NotImplementedError(message)
     kwargs["ignore"] = ignore
     file_io: IO[str]
     with open(path) as file_io:
         data = file_io.read()
     updated_data: str = update_function(data, **kwargs)
     if updated_data == data:
-        print(f"All requirements were already up-to-date in {path}")
+        print(  # noqa: T201
+            f"All requirements were already up-to-date in {path!s}"
+        )
     else:
-        print(f"Updating requirements in {path}")
+        print(  # noqa: T201
+            f"Updating requirements in {path!s}"
+        )
         with open(path, "w") as file_io:
             file_io.write(updated_data)
 
 
 def update(
-    paths: Iterable[str],
+    paths: Iterable[str | Path],
+    *,
     ignore: Iterable[str] = (),
     all_extra_name: str = "",
-    include_pointers: Tuple[str, ...] = (),
-    exclude_pointers: Tuple[str, ...] = (),
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
 ) -> None:
     """
     Update requirement versions in the specified files.
 
     Parameters:
-        path: One or more local paths to a setup.cfg,
+        paths: One or more local paths to a pyproject.toml,
             setup.cfg, and/or requirements.txt files
-        ignore: One or more project names to ignore (leave as-is)
+        ignore: One or more project/package names to ignore (leave
+            as-is) when updating dependency requirement specifiers.
         all_extra_name: If provided, an extra which consolidates
             the requirements for all other extras will be added/updated to
-            setup.cfg or setup.cfg (this argument is ignored for
+            pyproject.toml or setup.cfg (this argument is ignored for
             requirements.txt files)
         include_pointers: A tuple of JSON pointers indicating elements to
-            include (defaults to all elements).
+            include (defaults to all elements). This applies only to TOML
+            files (including pyproject.toml), and is ignored for all other
+            file types.
         exclude_pointers: A tuple of JSON pointers indicating elements to
-            exclude (defaults to no exclusions).
+            exclude (defaults to no exclusions). This applies only to TOML
+            files (including pyproject.toml), and is ignored for all other
+            file types.
     """
-    if isinstance(paths, str):
+    if isinstance(paths, (str, Path)):
         paths = (paths,)
 
-    def update_(path: str) -> None:
+    def update_(path: str | Path) -> None:
         _update(
             path,
             ignore=ignore,