dependence 1.0.5__tar.gz → 1.1.0__tar.gz

{dependence-1.0.5 → dependence-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dependence
-Version: 1.0.5
+Version: 1.1.0
 Summary: A dependency management tool for python projects
 Project-URL: Documentation, https://dependence.enorganic.org
 Project-URL: Repository, https://github.com/enorganic/dependence
@@ -21,11 +21,11 @@ Description-Content-Type: text/markdown
 [![test](https://github.com/enorganic/dependence/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/enorganic/dependence/actions/workflows/test.yml)
 [![PyPI version](https://badge.fury.io/py/dependence.svg?icon=si%3Apython)](https://badge.fury.io/py/dependence)
 
-Dependence provides a Command Line Interface and library for aligning
-a python projects' declared dependencies with the package versions
-installed in the environment in which `dependence` is executed, and for
-"freezing" recursively resolved package dependencies (like `pip freeze`, but
-for a package, instead of the entire environment).
+Dependence provides a Command Line Interface and library for performing
+dependency upgrades on a python project, aligning declared dependencies with
+the package versions installed in the environment in which `dependence` is
+executed, and for "freezing" recursively resolved package dependencies
+(like `pip freeze`, but for a package, instead of the entire environment).
 
 - [Documentation](https://enorganic.github.io/dependence/)
 - [Contributing](https://enorganic.github.io/dependence/contributing)
@@ -38,7 +38,72 @@ You can install `dependence` with pip:
 pip3 install dependence
 ```
 
-## Example Usage
+## Usage
+
+### Upgrading Dependencies
+
+The `dependence upgrade` command, and the `dependence.upgrade.upgrade`
+function, discover and upgrade project and environment dependencies in the
+environment in which dependence is installed to their latest version
+aligned with project and dependency requirements, then selectively update
+requirement specifiers in any specified TOML files (such as pyproject.toml),
+setup.cfg file, requirements.txt files, or tox.ini files. Because
+pyproject.toml files may contain dependencies for more than one environment,
+such as when using [hatch](https://hatch.pypa.io/) environments,
+[JSON-style pointers](https://datatracker.ietf.org/doc/html/rfc6901) are used
+to include or exclude specific parts of TOML files.
+
+For example, in [this project's Makefile
+](https://github.com/enorganic/dependence/blob/main/Makefile#L27), we define a
+`make upgrade` target as follows:
+
+```Makefile
+SHELL := bash
+PYTHON_VERSION := 3.9
+
+upgrade:
+    hatch run dependence upgrade\
+     --include-pointer /tool/hatch/envs/default\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run docs:dependence upgrade\
+     --include-pointer /tool/hatch/envs/docs\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run hatch-static-analysis:dependence upgrade\
+     --include-pointer /tool/hatch/envs/docs\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run hatch-test.py$(PYTHON_VERSION):dependence upgrade\
+     --include-pointer /tool/hatch/envs/hatch-test\
+     --include-pointer /project\
+     pyproject.toml && \
+    make requirements
+```
+
+You can reference the [associated pyproject.toml file for this project
+](https://github.com/enorganic/dependence/blob/main/pyproject.toml#L21)
+for reference concerning the implications of `--include-pointer`, which
+uses identical syntax to [JSON pointers
+](https://datatracker.ietf.org/doc/html/rfc6901). The `--exclude-pointer`
+parameter works identically, but in reverse. If both `--include-pointer`
+and `--exclude-pointer` are used, only sections which match both conditions
+will be updated.
+
+You may refer to the [`dependence upgrade` CLI reference](./cli.md#dependence-upgrade)
+and/or [`dependence.upgrade` API reference](./api/upgrade.md) for details
+concerning this command/module, related options, and more complex use case
+examples.
+
+The `dependence upgrade` command, and the `dependence.upgrade.upgrade`
+function, are simply a composite of the dependency listing and update
+functionalities covered below, but which a `pip install --upgrade`
+command executed in between—so please read further for additional details.
+All parameters are directly passed, with the exception of
+`--ignore-update`/`ignore_update`, which is translated to the
+`--ignore`/`ignore` parameter for
+`dependence update`/`dependence.update.update` (renamed in this operation
+for clarity of purpose).
 
 ### Listing Dependencies
 
@@ -48,8 +113,8 @@ requirements.txt, pyproject.toml, setup.cfg, or tox.ini files. The output
 format matches that of `pip freeze`, but only lists dependencies of indicated
 packages and/or editable project locations.
 
-You may refer to the [`dependence freeze` CLI reference](https://dependence.enorganic.org/cli/#dependence-freeze)
-and/or [`dependence.freeze` API reference](https://dependence.enorganic.org/api/freeze/) for details
+You may refer to the [`dependence freeze` CLI reference](./cli.md#dependence-freeze)
+and/or [`dependence.freeze` API reference](./api/freeze.md) for details
 concerning this command/module, related options, and more complex use case
 examples.
 
@@ -157,7 +222,7 @@ $ diff pyproject_before.toml pyproject_after.toml
 ```
 
 As you can see, only the version specifier for tomli changed. We know that
-every dependency was upgraded, wo why was only the `tomli` version specifier
+every dependency was upgraded, so why was only the `tomli` version specifier
 updated? By design. Here are the rules `dependence update` adheres to:
 
 -   We only update requirements versions when they have *inclusive* specifiers.
@@ -174,7 +239,7 @@ updated? By design. Here are the rules `dependence update` adheres to:
 -   If your requirement is unversioned, we don't touch it, of course. This is
     why you didn't see any change for "pip".
 
-You may refer to the [`dependence update` CLI reference](https://dependence.enorganic.org/cli/#dependence-update)
-and/or [`dependence.update` API reference](https://dependence.enorganic.org/api/update/) for details
+You may refer to the [`dependence update` CLI reference](./cli.md#dependence-update)
+and/or [`dependence.update` API reference](./api/update.md) for details
 concerning this command/module, related options, and more complex use
 cases/examples.

{dependence-1.0.5 → dependence-1.1.0}/README.md

@@ -3,11 +3,11 @@
 [![test](https://github.com/enorganic/dependence/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/enorganic/dependence/actions/workflows/test.yml)
 [![PyPI version](https://badge.fury.io/py/dependence.svg?icon=si%3Apython)](https://badge.fury.io/py/dependence)
 
-Dependence provides a Command Line Interface and library for aligning
-a python projects' declared dependencies with the package versions
-installed in the environment in which `dependence` is executed, and for
-"freezing" recursively resolved package dependencies (like `pip freeze`, but
-for a package, instead of the entire environment).
+Dependence provides a Command Line Interface and library for performing
+dependency upgrades on a python project, aligning declared dependencies with
+the package versions installed in the environment in which `dependence` is
+executed, and for "freezing" recursively resolved package dependencies
+(like `pip freeze`, but for a package, instead of the entire environment).
 
 - [Documentation](https://enorganic.github.io/dependence/)
 - [Contributing](https://enorganic.github.io/dependence/contributing)
@@ -20,7 +20,72 @@ You can install `dependence` with pip:
 pip3 install dependence
 ```
 
-## Example Usage
+## Usage
+
+### Upgrading Dependencies
+
+The `dependence upgrade` command, and the `dependence.upgrade.upgrade`
+function, discover and upgrade project and environment dependencies in the
+environment in which dependence is installed to their latest version
+aligned with project and dependency requirements, then selectively update
+requirement specifiers in any specified TOML files (such as pyproject.toml),
+setup.cfg file, requirements.txt files, or tox.ini files. Because
+pyproject.toml files may contain dependencies for more than one environment,
+such as when using [hatch](https://hatch.pypa.io/) environments,
+[JSON-style pointers](https://datatracker.ietf.org/doc/html/rfc6901) are used
+to include or exclude specific parts of TOML files.
+
+For example, in [this project's Makefile
+](https://github.com/enorganic/dependence/blob/main/Makefile#L27), we define a
+`make upgrade` target as follows:
+
+```Makefile
+SHELL := bash
+PYTHON_VERSION := 3.9
+
+upgrade:
+    hatch run dependence upgrade\
+     --include-pointer /tool/hatch/envs/default\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run docs:dependence upgrade\
+     --include-pointer /tool/hatch/envs/docs\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run hatch-static-analysis:dependence upgrade\
+     --include-pointer /tool/hatch/envs/docs\
+     --include-pointer /project\
+     pyproject.toml && \
+    hatch run hatch-test.py$(PYTHON_VERSION):dependence upgrade\
+     --include-pointer /tool/hatch/envs/hatch-test\
+     --include-pointer /project\
+     pyproject.toml && \
+    make requirements
+```
+
+You can reference the [associated pyproject.toml file for this project
+](https://github.com/enorganic/dependence/blob/main/pyproject.toml#L21)
+for reference concerning the implications of `--include-pointer`, which
+uses identical syntax to [JSON pointers
+](https://datatracker.ietf.org/doc/html/rfc6901). The `--exclude-pointer`
+parameter works identically, but in reverse. If both `--include-pointer`
+and `--exclude-pointer` are used, only sections which match both conditions
+will be updated.
+
+You may refer to the [`dependence upgrade` CLI reference](./cli.md#dependence-upgrade)
+and/or [`dependence.upgrade` API reference](./api/upgrade.md) for details
+concerning this command/module, related options, and more complex use case
+examples.
+
+The `dependence upgrade` command, and the `dependence.upgrade.upgrade`
+function, are simply a composite of the dependency listing and update
+functionalities covered below, but which a `pip install --upgrade`
+command executed in between—so please read further for additional details.
+All parameters are directly passed, with the exception of
+`--ignore-update`/`ignore_update`, which is translated to the
+`--ignore`/`ignore` parameter for
+`dependence update`/`dependence.update.update` (renamed in this operation
+for clarity of purpose).
 
 ### Listing Dependencies
 
@@ -30,8 +95,8 @@ requirements.txt, pyproject.toml, setup.cfg, or tox.ini files. The output
 format matches that of `pip freeze`, but only lists dependencies of indicated
 packages and/or editable project locations.
 
-You may refer to the [`dependence freeze` CLI reference](https://dependence.enorganic.org/cli/#dependence-freeze)
-and/or [`dependence.freeze` API reference](https://dependence.enorganic.org/api/freeze/) for details
+You may refer to the [`dependence freeze` CLI reference](./cli.md#dependence-freeze)
+and/or [`dependence.freeze` API reference](./api/freeze.md) for details
 concerning this command/module, related options, and more complex use case
 examples.
 
@@ -139,7 +204,7 @@ $ diff pyproject_before.toml pyproject_after.toml
 ```
 
 As you can see, only the version specifier for tomli changed. We know that
-every dependency was upgraded, wo why was only the `tomli` version specifier
+every dependency was upgraded, so why was only the `tomli` version specifier
 updated? By design. Here are the rules `dependence update` adheres to:
 
 -   We only update requirements versions when they have *inclusive* specifiers.
@@ -156,7 +221,7 @@ updated? By design. Here are the rules `dependence update` adheres to:
 -   If your requirement is unversioned, we don't touch it, of course. This is
     why you didn't see any change for "pip".
 
-You may refer to the [`dependence update` CLI reference](https://dependence.enorganic.org/cli/#dependence-update)
-and/or [`dependence.update` API reference](https://dependence.enorganic.org/api/update/) for details
+You may refer to the [`dependence update` CLI reference](./cli.md#dependence-update)
+and/or [`dependence.update` API reference](./api/update.md) for details
 concerning this command/module, related options, and more complex use
 cases/examples.

{dependence-1.0.5 → dependence-1.1.0}/dependence/__main__.py

@@ -23,7 +23,10 @@ def _print_help() -> None:
         "installed\n"
         "                              distribution or project, in a similar "
         "format\n"
-        "                              to the output of `pip freeze`."
+        "                              to the output of `pip freeze`.\n"
+        "  upgrade                     Upgrade all dependencies and align "
+        "project\n"
+        "                              requirement specifiers to match."
     )
 
 

{dependence-1.0.5 → dependence-1.1.0}/dependence/_utilities.py

@@ -25,6 +25,7 @@ from typing import (
     Callable,
     TypedDict,
     cast,
+    overload,
 )
 from warnings import warn
 
@@ -37,6 +38,63 @@ _BUILTIN_DISTRIBUTION_NAMES: tuple[str] = ("distribute",)
 _UNSAFE_CHARACTERS_PATTERN: re.Pattern = re.compile("[^A-Za-z0-9.]+")
 
 
+class DefinitionExistsError(Exception):
+    """
+    This error is raised when an attempt is made to redefine
+    a singleton class instance.
+    """
+
+
+_module_locals: dict[str, Any] = locals()
+
+
+class Undefined:
+    """
+    This class is intended to indicate that a parameter has not been passed
+    to a keyword argument in situations where `None` is to be used as a
+    meaningful value.
+
+    The `Undefined` class is a singleton, so only one instance of this class
+    is permitted: `sob.UNDEFINED`.
+    """
+
+    __module__ = "sob"
+
+    def __init__(self) -> None:
+        # Only one instance of `Undefined` is permitted, so initialization
+        # checks to make sure this is the first use.
+        if "UNDEFINED" in _module_locals:
+            message: str = f"{self!r} may only be instantiated once."
+            raise DefinitionExistsError(message)
+
+    def __repr__(self) -> str:
+        # Represent instances of this class using the qualified name for the
+        # constant `UNDEFINED`.
+        return "sob.UNDEFINED"
+
+    def __bool__(self) -> bool:
+        # `UNDEFINED` cast as a boolean is `False` (as with `None`)
+        return False
+
+    def __hash__(self) -> int:
+        return 0
+
+    def __eq__(self, other: object) -> bool:
+        # Another object is only equal to this if it shares the same id, since
+        # there should only be one instance of this class defined
+        return other is self
+
+    def __reduce__(self) -> tuple[Callable[[], Undefined], tuple]:
+        return _undefined, ()
+
+
+UNDEFINED: Undefined = Undefined()
+
+
+def _undefined() -> Undefined:
+    return UNDEFINED
+
+
 def iter_distinct(items: Iterable[Hashable]) -> Iterable:
     """
     Yield distinct elements, preserving order
@@ -292,10 +350,14 @@ class ConfigurationFileType(Enum):
 
 
 @functools.lru_cache
-def get_configuration_file_type(path: str) -> ConfigurationFileType:
-    if not os.path.isfile(path):
+def get_configuration_file_type(
+    path: str | Path, default: Any = UNDEFINED
+) -> ConfigurationFileType:
+    if isinstance(path, str):
+        path = Path(path)
+    if not path.is_file():
         raise FileNotFoundError(path)
-    basename: str = os.path.basename(path).lower()
+    basename: str = path.name.lower()
     if basename == "setup.cfg":
         return ConfigurationFileType.SETUP_CFG
     if basename == "tox.ini":
@@ -306,16 +368,54 @@ def get_configuration_file_type(path: str) -> ConfigurationFileType:
         return ConfigurationFileType.REQUIREMENTS_TXT
     if basename.endswith(".toml"):
         return ConfigurationFileType.TOML
-    message: str = f"{path} is not a recognized type of configuration file."
-    raise ValueError(message)
+    if default is UNDEFINED:
+        message: str = (
+            f"{path!s} is not a recognized type of configuration file."
+        )
+        raise ValueError(message)
+    return default
 
 
 def is_configuration_file(path: str) -> bool:
-    try:
-        get_configuration_file_type(path)
-    except (FileNotFoundError, ValueError):
-        return False
-    return True
+    return get_configuration_file_type(path, default=None) is not None
+
+
+@overload
+def iter_configuration_files(path: str) -> Iterable[str]: ...
+
+
+@overload
+def iter_configuration_files(path: Path) -> Iterable[Path]: ...
+
+
+def iter_configuration_files(path: str | Path) -> Iterable[Path | str]:
+    """
+    Iterate over the project configuration files for the given path.
+    If the path is a file path—yields only that path. If the path is a
+    directory, yields all configuration files in that directory.
+    """
+    if os.path.exists(path):
+        if os.path.isdir(path):
+            child: Path
+            for child in filter(
+                Path.is_file,
+                (
+                    path.iterdir()
+                    if isinstance(path, Path)
+                    else Path(path).iterdir()
+                ),
+            ):
+                if (
+                    get_configuration_file_type(child, default=None)
+                    is not None
+                ):
+                    yield (
+                        child
+                        if isinstance(path, Path)
+                        else str(child.absolute())
+                    )
+        elif get_configuration_file_type(path, default=None) is not None:
+            yield path
 
 
 class _EditablePackageMetadata(TypedDict):

{dependence-1.0.5 → dependence-1.1.0}/dependence/freeze.py

@@ -7,15 +7,16 @@ from functools import partial
 from importlib.metadata import Distribution
 from importlib.metadata import distribution as _get_distribution
 from itertools import chain
-from typing import cast
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
 
 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,
@@ -74,8 +75,8 @@ 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] = (),
@@ -109,21 +110,30 @@ 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
-    )
+    # Separate requirement strings from requirement files
+    configuration_files: MutableSet[str] = set()
+    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:
+            configuration_files |= requirement_configuration_files
+        else:
+            if requirement.startswith("setup.py"):
+                raise ValueError(requirement)
+            requirement_strings.add(requirement)
     frozen_requirements: Iterable[str] = iter_distinct(
         chain(
             requirement_strings,
@@ -133,10 +143,11 @@ def get_frozen_requirements(
                     include_pointers=include_pointers,
                     exclude_pointers=exclude_pointers,
                 ),
-                requirement_files,
+                configuration_files,
             ),
         )
     )
+    frozen_requirements = tuple(frozen_requirements)
     if depth is not None:
         depth -= 1
     if (depth is None) or depth >= 0:
@@ -242,7 +253,7 @@ def _iter_frozen_requirements(
 
 
 def freeze(
-    requirements: Iterable[str] = (),
+    requirements: Iterable[str | Path] = (),
     *,
     exclude: Iterable[str] = (),
     exclude_recursive: Iterable[str] = (),
@@ -263,9 +274,10 @@ def freeze(
             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_recursive: 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

{dependence-1.0.5 → dependence-1.1.0}/dependence/update.py

@@ -8,6 +8,7 @@ from copy import deepcopy
 from dataclasses import dataclass
 from io import StringIO
 from itertools import chain
+from pathlib import Path
 from typing import (
     IO,
     TYPE_CHECKING,
@@ -423,12 +424,13 @@ 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, ...] = (),
 ) -> None:
+    message: str
     data: str
     update_function: Callable[[str], str]
     kwargs: dict[str, str | Iterable[str]] = {}
@@ -457,8 +459,8 @@ def _update(
     elif configuration_file_type == ConfigurationFileType.REQUIREMENTS_TXT:
         update_function = _get_updated_requirements_txt
     else:
-        msg = f"Updating requirements for {path} is not supported"
-        raise NotImplementedError(msg)
+        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:
@@ -466,18 +468,19 @@ def _update(
     updated_data: str = update_function(data, **kwargs)
     if updated_data == data:
         print(  # noqa: T201
-            f"All requirements were already up-to-date in {path}"
+            f"All requirements were already up-to-date in {path!s}"
         )
     else:
         print(  # noqa: T201
-            f"Updating requirements in {path}"
+            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, ...] = (),
@@ -487,22 +490,27 @@ def update(
     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,

dependence-1.1.0/dependence/upgrade.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from itertools import chain
+from typing import TYPE_CHECKING
+
+from dependence._utilities import (
+    check_output,
+    iter_configuration_files,
+    iter_parse_delimited_values,
+)
+from dependence.freeze import get_frozen_requirements
+from dependence.update import update
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+def upgrade(
+    requirements: Iterable[str],
+    *,
+    ignore_update: Iterable[str] = (),
+    all_extra_name: str = "",
+    include_pointers: tuple[str, ...] = (),
+    exclude_pointers: tuple[str, ...] = (),
+    exclude: Iterable[str] = (),
+    exclude_recursive: Iterable[str] = (),
+    depth: int | None = None,
+) -> None:
+    """
+    This function obtains a list of dependencies for the specified
+    `requirements` using `dependence.update.get_frozen_requirements()`,
+    upgrades all of these dependencies in the current environment,
+    then updates version specifiers for all requirements/dependencies
+    in any or the `requirements` which are project config files
+    to align with the newly installed package versions (using
+    `dependence.update.update()`).
+
+    Parameters:
+        requirements: One or more requirement specifiers (for example:
+            "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.
+        ignore_update: One or more project names to ignore (leave as-is)
+            when updating a dependency's requirement specifier in the
+            provided pyproject.toml/setup.cfg/requirements.txt/tox.ini
+            file(s). Note that this does not prevent the package from being
+            upgraded—for that you need to pass the package name in
+            `exclude` or `exclude_recursive`.
+        all_extra_name: If provided, an extra which consolidates
+            the requirements for all other extras will be added/updated to
+            pyproject.toml or setup.cfg (this argument is ignored for
+            requirements.txt and tox.ini files).
+        include_pointers: A tuple of JSON pointers indicating elements to
+            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). This applies only to TOML
+            files (including pyproject.toml), and is ignored for all other
+            file types.
+        exclude: One or more distributions to exclude when upgrading packages.
+        exclude_recursive: One or more distributions to exclude when
+            upgrading packages. Recursive dependency discovery is also
+            halted for these distributions, unlike those passed to `exclude`.
+        depth: The maximum recursion depth to traverse when discovering
+            dependencies. If `None` (the default), all dependencies are
+            discovered.
+    """
+    frozen_requirements: tuple[str, ...] = get_frozen_requirements(
+        requirements,
+        exclude=exclude,
+        exclude_recursive=exclude_recursive,
+        no_version="*",
+        depth=depth,
+        include_pointers=include_pointers,
+        exclude_pointers=exclude_pointers,
+    )
+    command: tuple[str, ...] = (
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        *frozen_requirements,
+    )
+    check_output(command)
+    configuration_files: tuple[str, ...] = tuple(
+        chain(
+            *map(iter_configuration_files, requirements)  # type: ignore
+        )
+    )
+    if configuration_files:
+        update(
+            configuration_files,
+            ignore=ignore_update,
+            all_extra_name=all_extra_name,
+            include_pointers=include_pointers,
+            exclude_pointers=exclude_pointers,
+        )
+
+
+def main() -> None:
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        prog="dependence upgrade",
+        description=(
+            "Upgrade all dependencies for specified packages/projects, "
+            "then upgrade version specifiers in the project files "
+            "to align with newly installed versions of each distribution."
+        ),
+    )
+    parser.add_argument(
+        "-iu",
+        "--ignore-update",
+        default=[],
+        type=str,
+        action="append",
+        help=(
+            "A comma-separated list of distributions to ignore (leave "
+            "any requirements pertaining to the package as-is) when "
+            "updating project files"
+        ),
+    )
+    parser.add_argument(
+        "-aen",
+        "--all-extra-name",
+        default="",
+        type=str,
+        help=(
+            "If provided, an extra which consolidates the requirements "
+            "for all other extras will be added/updated to pyproject.toml "
+            "or setup.cfg (this argument is ignored for "
+            "requirements.txt files and other TOML files)"
+        ),
+    )
+    parser.add_argument(
+        "--include-pointer",
+        default=[],
+        type=str,
+        action="append",
+        help=(
+            "One or more JSON pointers of elements to *include* "
+            "(applies to TOML files only)"
+        ),
+    )
+    parser.add_argument(
+        "--exclude-pointer",
+        default=[],
+        type=str,
+        action="append",
+        help=(
+            "One or more JSON pointers of elements to *exclude* "
+            "(applies to TOML files only)"
+        ),
+    )
+    parser.add_argument(
+        "-e",
+        "--exclude",
+        default=[],
+        type=str,
+        action="append",
+        help=(
+            "A distribution (or comma-separated list of distributions) to "
+            "exclude when performing upgrades"
+        ),
+    )
+    parser.add_argument(
+        "-er",
+        "--exclude-recursive",
+        default=[],
+        type=str,
+        action="append",
+        help=(
+            "A distribution (or comma-separated list of distributions) to "
+            "exclude when performing upgrades. Unlike -e / --exclude, "
+            "this argument also precludes recursive requirement discovery "
+            "for the specified packages, thereby excluding all of the "
+            "excluded package's requirements which are not required by "
+            "another (non-excluded) distribution from the upgrade."
+        ),
+    )
+    parser.add_argument(
+        "-d",
+        "--depth",
+        default=None,
+        type=int,
+        help="Depth of recursive requirement discovery",
+    )
+    parser.add_argument(
+        "requirement",
+        nargs="+",
+        type=str,
+        help=(
+            "One or more requirement specifiers (for example: "
+            '"requirement-name", "requirement-name[extra-a,extra-b]", '
+            '".[extra-a, extra-b]" or '
+            '"../other-editable-package-directory[extra-a, extra-b]) '
+            "and/or paths to a setup.py, setup.cfg, pyproject.toml, "
+            "tox.ini or requirements.txt file"
+        ),
+    )
+    namespace: argparse.Namespace = parser.parse_args()
+    upgrade(
+        requirements=namespace.requirement,
+        exclude=tuple(iter_parse_delimited_values(namespace.exclude)),
+        exclude_recursive=tuple(
+            iter_parse_delimited_values(namespace.exclude_recursive)
+        ),
+        ignore_update=tuple(
+            iter_parse_delimited_values(namespace.ignore_update)
+        ),
+        all_extra_name=namespace.all_extra_name,
+        include_pointers=tuple(namespace.include_pointer),
+        exclude_pointers=tuple(namespace.exclude_pointer),
+    )
+
+
+if __name__ == "__main__":
+    main()

{dependence-1.0.5 → dependence-1.1.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dependence"
-version = "1.0.5"
+version = "1.1.0"
 description = "A dependency management tool for python projects"
 readme = "README.md"
 license = "MIT"
@@ -67,7 +67,6 @@ post-install-commands = [
 [tool.hatch.envs.default.scripts]
 lint = "ruff check . && ruff format --check . && mypy"
 
-
 [tool.hatch.envs.docs]
 template = "docs"
 python = "3.13"
@@ -77,9 +76,15 @@ dependencies = [
     "black",
 ]
 
+[tool.hatch.envs.hatch-static-analysis]
+skip-install = false
+
 [tool.hatch.envs.hatch-test]
 template = "hatch-test"
 extra-dependencies = []
+extra-arguments = [
+    "--cache-clear",
+]
 
 [[tool.hatch.envs.hatch-test.matrix]]
 python = [
@@ -90,11 +95,9 @@ python = [
     "3.13",
 ]
 
-
 [tool.ruff]
 line-length = 79
 
-
 [tool.ruff.lint]
 ignore = [
     "F842",
@@ -141,14 +144,17 @@ disallow_untyped_defs = true
 disallow_incomplete_defs = true
 
 [tool.coverage.run]
+include = [
+    "src/**/*.py",
+]
 omit = [
-    "tests/test_projects",
+    "src/**/_*.py",
 ]
 
 [tool.coverage.paths]
 source = [
-    "src/",
+    "src/**",
 ]
 
 [tool.coverage.report]
-fail_under = 80
+fail_under = 70