hatch plugin to use pip-compile to manage project dependencies
Project description
hatch-pip-compile
hatch plugin to use pip-compile to manage project dependencies and lockfiles.
Installation
Declare hatch-pip-compile
as a dependency in your pyproject.toml
file under the
[tool.hatch.env]
table and hatch will automatically install it. You must also have
your environment type set to pip-compile
(see Configuration).
-
pyproject.toml
[tool.hatch.env] requires = [ "hatch-pip-compile" ] [tool.hatch.envs.default] type = "pip-compile"
-
hatch.toml
[env] requires = [ "hatch-pip-compile" ] [envs.default] type = "pip-compile"
Usage
The hatch-pip-compile
plugin will automatically run pip-compile
whenever your
environment needs to be updated. Behind the scenes, this plugin creates a lockfile
at requirements.txt
(non-default lockfiles are located at
requirements/requirements-{env_name}.txt
). Alongside pip-compile
, this plugin also
uses pip-sync to install the dependencies from the lockfile into your environment.
- lock-filename - changing the default lockfile path
- pip-compile-constraint - syncing dependency versions across environments
- Upgrading Dependencies - how to upgrade dependencies
Configuration
The environment plugin name is pip-compile
. Set your environment
type to pip-compile
to use this plugin for the respective environment.
-
pyproject.toml
[tool.hatch.envs.default] type = "pip-compile"
-
hatch.toml
[envs.default] type = "pip-compile"
Configuration Options
name | type | description |
---|---|---|
lock-filename | str |
The filename of the ultimate lockfile. default env is requirements.txt , non-default is requirements/requirements-{env_name}.txt |
pip-compile-constraint | str |
An environment to use as a constraint file, ensuring that all shared dependencies are pinned to the same versions. |
pip-compile-hashes | bool |
Whether to generate hashes in the lockfile. Defaults to false . |
pip-compile-verbose | bool |
Set to true to run pip-compile in verbose mode instead of quiet mode, set to false to silence warnings |
pip-compile-args | list[str] |
Additional command-line arguments to pass to pip-compile |
Examples
lock-filename
The path (including the directory) to the ultimate lockfile. Defaults to requirements.txt
in the project root
for the default
environment, and requirements/requirements-{env_name}.txt
for non-default environments.
Changing the lock file path:
-
pyproject.toml
[tool.hatch.envs.<envName>] type = "pip-compile" lock-filename = "locks/{env_name}.lock"
-
hatch.toml
[envs.<envName>] type = "pip-compile" lock-filename = "locks/{env_name}.lock"
Changing the lock filename to a path in the project root:
-
pyproject.toml
[tool.hatch.envs.lint] type = "pip-compile" lock-filename = "linting-requirements.txt"
-
hatch.toml
[envs.lint] type = "pip-compile" lock-filename = "linting-requirements.txt"
pip-compile-constraint
An environment to use as a constraint, ensuring that all shared dependencies are
pinned to the same versions. For example, if you have a default
environment and
a test
environment, you can set the pip-compile-constraint
option to default
on the test
environment to ensure that all shared dependencies are pinned to the
same versions.
-
pyproject.toml
[tool.hatch.envs.default] type = "pip-compile" [tool.hatch.envs.test] dependencies = [ "pytest" ] type = "pip-compile" pip-compile-constraint = "default"
-
hatch.toml
[envs.default] type = "pip-compile" [envs.test] dependencies = [ "pytest" ] type = "pip-compile" pip-compile-constraint = "default"
By default, all environments inherit from the default
environment via
inheritance. A common use case is to set the pip-compile-constraint
and type
options on the default
environment and inherit them on
all other environments. It's important to note that when detached = true
,
inheritance is disabled and the type
and pip-compile-constraint
options
must be set explicitly.
-
pyproject.toml
[tool.hatch.envs.default] type = "pip-compile" pip-compile-constraint = "default" [tool.hatch.envs.test] dependencies = [ "pytest" ]
-
hatch.toml
[envs.default] type = "pip-compile" pip-compile-constraint = "default" [envs.test] dependencies = [ "pytest" ]
pip-compile-hashes
Whether to generate hashes in the lockfile. Defaults to false
.
-
pyproject.toml
[tool.hatch.envs.<envName>] type = "pip-compile" pip-compile-hashes = true
-
hatch.toml
[envs.<envName>] type = "pip-compile" pip-compile-hashes = true
pip-compile-args
Extra arguments to pass to pip-compile
. Custom PyPI indexes can be specified here.
-
pyproject.toml
[tool.hatch.envs.<envName>] type = "pip-compile" pip-compile-args = [ "--index-url", "https://pypi.org/simple", ]
-
hatch.toml
[envs.<envName>] type = "pip-compile" pip-compile-args = [ "--index-url", "https://pypi.org/simple", ]
pip-compile-verbose
Set to true
to run pip-compile
in verbose mode instead of quiet mode.
Optionally, if you would like to silence any warnings set the pip-compile-verbose
option to false
.
-
pyproject.toml
[tool.hatch.envs.<envName>] type = "pip-compile" pip-compile-verbose = true
-
hatch.toml
[envs.<envName>] type = "pip-compile" pip-compile-verbose = true
Upgrading Dependencies
Upgrading all dependencies can be as simple as deleting your lockfile and recreating it by reactivating the environment:
rm requirements.txt
hatch env run --env default -- python --version
If you're a user of the --upgrade
/ --upgrade-package
options on pip-compile
,
these features can be enabled on this plugin using the environment variables
PIP_COMPILE_UPGRADE
and PIP_COMPILE_UPGRADE_PACKAGE
. When either of these
environment variables are set hatch
will force the lockfile to be regenerated
whenever the environment is activated.
To run with upgrade
functionality on the default
environment:
PIP_COMPILE_UPGRADE=1 hatch env run --env default -- python --version
To run with upgrade-package
functionality on the docs
environment:
PIP_COMPILE_UPGRADE_PACKAGE="mkdocs,mkdocs-material" hatch env run --env docs -- python --version
The above commands call python --version
on a particular environment,
but the same behavior applies to any script that activates the environment.
Notes
Dev Dependencies
Using the default hatch configuration, dev dependencies listed in your
default
environment (like pytest
) will be included on the default lockfile
(requirements.txt
). If you want to remove your dev dependencies
from the lockfile you must remove them from the default
environment
on your pyproject.toml
/ hatch.toml
file.
Disabling Changes to the Lockfile
In some scenarios, like in CI/CD, you may want to prevent the plugin from
making changes to the lockfile. If you set the PIP_COMPILE_DISABLE
environment variable to any non-empty value, the plugin will raise an error
if it detects that the lockfile needs to be updated.
PIP_COMPILE_DISABLE=1 hatch env run python --version
Manual Installation
If you want to manually install this plugin instead of adding it to the
[tool.hatch.env]
table, you can do so with pipx:
pipx install hatch
pipx inject hatch hatch-pip-compile
Alternatively, you can install it with pip:
pip install hatch hatch-pip-compile
Check Out the Docs
Looking to contribute? See the Contributing Guide
See the Changelog
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
Hashes for hatch_pip_compile-1.6.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ff35e850a149209fb7052fc56c874c2a43a86895dcb3526734ac0a6e32d080c2 |
|
MD5 | b3f71450ce5234f7c78e7cc35a66c84f |
|
BLAKE2b-256 | 9bc039f0454f9fe6f23f8c8096e60e8efe1839fcff74d2d6217e8ec087f3b8cc |