Hatchling plugin to create optional-dependencies pinned to minimum versions
Project description
hatch-min-requirements
Hatchling plugin to create optional-dependencies pinned to minimum versions
Rationale
When creating a library, it is often useful to specify the minimum version of a dependency that is required. However, pip's default behavior is to install the latest version of a package that satisfies your requirement. As a result, if aren't carefully testing your minimum dependencies, you may inadvertently introduce changes to your package that are not compatible with the minimum version you specified.
This plugin will inspect your packages dependencies and dynamically add an extra
(named min-reqs
by default) to the project.optional-dependencies
table of
your pyproject.toml
file. This extra will contain all of your dependendencies
pinned to their minimum version.
This makes it easy to test your package against your minimum stated dependencies on CI, or to install your package with the minimum dependencies for local development.
Usage
In your pyproject.toml
make the following changes:
- Append
hatch-min-requirements
to[build-system.requires]
. - Add a
[tool.hatch.metadata.hooks.min_requirements]
table.
[build-system]
requires = ["hatchling", "hatch-min-requirements"]
build-backend = "hatchling.build"
[tool.hatch.metadata.hooks.min_requirements]
Then, you can install your package using the min-reqs
extra and it will
dynamically use the minimum compatible versions of your dependencies.
pip install -e .[min-reqs]
Environment variables
Environment variables can be used to configure the behavior. Described in detail below:
Variable | Default | Description |
---|---|---|
MIN_REQS_EXTRA_NAME |
min-reqs |
The name of the extra to add to pyproject.toml |
MIN_REQS_PIN_UNCONSTRAINED |
True |
Pin unconstrained dependencies to minimum available version on PyPI. (e.g. numpy -> numpy==1.3.0 ) |
MIN_REQS_OFFLINE |
False |
Do not connect to PyPI to fetch available versions |
MIN_REQS_TRY_PIP |
True |
Use pip to fetch available versions in online mode. Set to 0 to use stdlib tools only |
Utilities
This package provides two convenience functions that can be used directly (without being a hatch plugin).
-
hatch_min_requirements.sub_min_compatible_version
Takes a pip requirement string and returns a new requirement string with the minimum compatible version substituted in.
>>> sub_min_compatible_version("numpy") 'numpy==1.3.0' >>> sub_min_compatible_version("numpy>=1.4.1") 'numpy==1.4.1' >>> sub_min_compatible_version("numpy>1.3") 'numpy==1.4.1' >>> sub_min_compatible_version("numpy[extra1,extra2]>=1.20,<2.0") 'numpy[extra1,extra2]==1.20.0' >>> sub_min_compatible_version("numpy[extra]<2; python_version == '3.6'") "numpy[extra]==1.3.0 ; python_version == '3.6'"
-
hatch_min_requirements.patch_pyproject
Takes a path to a
pyproject.toml
file and patches it to include themin-reqs
extra. The original file is backed up with a.BAK
extension.>>> patch_pyproject("path/to/pyproject.toml")
Considerations
Dependencies with no constraints
In cases of dependencies declared without constraints (e.g. foo
), the plugin
will search for the minimum available version of the package from PyPI. The
goal here is to encourage accurate requirement pinning. If you want to disable
this behavior and leave unconstrained specifiers as is, you can either set the
MIN_REQS_PIN_UNCONSTRAINED
environment variable to 0
or False
, or use
offline mode with MIN_REQS_OFFLINE=1
(see below).
Offline Mode
In cases such as upper-bounds (<X.Y
), non-inclusive lower bounds (>X.Y
), and
exclusions (!=X.Y
), it's not possible to declare a minimum version without
fetching available versions from PyPI. By default, this plugin will attempt
to connect to PyPI in order to determine compatible minimum version strings. If
you want to disable this behavior, you can set the MIN_REQS_OFFLINE
environment variable to 1
or True
.
MIN_REQS_OFFLINE=1 pip install -e .[min-reqs]
In offline mode, no attempt is made to guess the next compatible version of a package after a non-inclusive lower bound. Instead, the plugin will simply use your dependency as stated (meaning you won't be testing lower bounds). If you want to test lower bounds without connecting to PyPI, you should pin your dependencies with inclusive lower bounds:
[project]
dependencies = [
"foo>=1.2.3" # will be pinned to "foo==1.2.3"
"baz~=1.2" # will be pinned to "baz==1.2"
"bar>1.2.3" # will be unchanged
]
Usage of pip vs standard-lib tools
Fetching the available versions of a package is not trivial, and pip
is the
de facto tool for doing so. If pip
is available in the build environment,
this plugin will use it to fetch the available versions of a package. But, you
must opt in to this behavior by adding pip
to your build-system.requires
in pyproject.toml
:
[build-system]
requires = ["hatchling", "hatch-min-requirements", "pip"]
To explicitly opt out of using pip (even if it's available) and use standard library tools only, you can
set the MIN_REQS_TRY_PIP
environment variable to 0
or False
.
TODO
- add
offline
andno-pip
options to themin_requirements
table in pyproject
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file hatch_min_requirements-0.1.0.tar.gz
.
File metadata
- Download URL: hatch_min_requirements-0.1.0.tar.gz
- Upload date:
- Size: 15.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/4.0.2 CPython/3.11.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 45875bb8fe662b30f29b8bb1d98e2ef33de2c40e42c79a80c9ab0ef5160f6b27 |
|
MD5 | 20c5a342d59e042a3da767f7e644d130 |
|
BLAKE2b-256 | 96d8937025ab8b88ca3f906cf879bd8fc6bfe5a9b86d7f8d356868aa1d2f1775 |
Provenance
File details
Details for the file hatch_min_requirements-0.1.0-py3-none-any.whl
.
File metadata
- Download URL: hatch_min_requirements-0.1.0-py3-none-any.whl
- Upload date:
- Size: 13.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/4.0.2 CPython/3.11.8
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9ecd2365b1a1390473460d32c006561842cdde345cf7be54a782a91e4bdc897 |
|
MD5 | d6636f15d85d4980096b403d416d7c69 |
|
BLAKE2b-256 | 91e033477f20467214307646ff0e5e74d40e0fa2c97d1a5371b30f73dcbb437e |