dependence 1.0.4__tar.gz → 1.1.0__tar.gz

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

@@ -1,18 +1,18 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: dependence
-Version: 1.0.4
+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
 Author-email: david@belais.me
-License: MIT
+License-Expression: MIT
 Keywords: dependencies,requirements
-Requires-Python: ~=3.8
+Requires-Python: ~=3.9
 Requires-Dist: jsonpointer
 Requires-Dist: packaging
 Requires-Dist: pip
 Requires-Dist: setuptools>63
-Requires-Dist: tomli-w~=1.0
+Requires-Dist: tomli-w~=1.2
 Requires-Dist: tomli~=2.2
 Description-Content-Type: text/markdown
 
@@ -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.4 → 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.4 → dependence-1.1.0}/dependence/__main__.py

@@ -1,13 +1,16 @@
 import sys
 from importlib import import_module
-from types import ModuleType
+from typing import TYPE_CHECKING
 
-from . import __name__ as _module_name
-from ._utilities import get_exception_text
+if TYPE_CHECKING:
+    from types import ModuleType
+
+from dependence import __name__ as _module_name
+from dependence._utilities import get_exception_text
 
 
 def _print_help() -> None:
-    print(
+    print(  # noqa: T201
         "Usage:\n"
         "  dependence <command> [options]\n\n"
         "Commands:\n"
@@ -20,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."
     )
 
 
@@ -47,7 +53,7 @@ def main() -> None:
             module = import_module(f"{_module_name}.{command}")
         module.main()  # type: ignore
     except ImportError:
-        print(get_exception_text())
+        print(get_exception_text())  # noqa: T201
         _print_help()