-
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
9 changed files
with
413 additions
and
401 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
# Using the `hatch-pip-compile` CLI | ||
|
||
For convenience this package also makes a CLI available to handle the setting / | ||
unsetting of the `PIP_COMPILE_UPGRADE` / `PIP_COMPILE_UPGRADE_PACKAGE` environment variables | ||
and invoking the `hatch env run` command for you automatically. To use the CLI you'll need to | ||
install it outside your `pyproject.toml` / `hatch.toml` file. | ||
|
||
I recommend using [pipx] to | ||
install the CLI, but you can also install it directly with [pip]: | ||
|
||
```shell | ||
pipx install hatch-pip-compile | ||
``` | ||
|
||
Once installed, you can run the CLI with the `hatch-pip-compile` command. | ||
|
||
## Examples | ||
|
||
### Upgrade the `default` environment | ||
|
||
The below command will upgrade all packages in the `default` environment. | ||
|
||
```shell | ||
hatch-pip-compile --upgrade | ||
``` | ||
|
||
### Upgrade a non-default environment | ||
|
||
The below command will upgrade all packages in the `docs` environment. | ||
|
||
```shell | ||
hatch-pip-compile docs --upgrade | ||
``` | ||
|
||
### Upgrade a specific package | ||
|
||
The below command will upgrade the `requests` package in the `default` | ||
environment. | ||
|
||
```shell | ||
hatch-pip-compile --upgrade-package requests | ||
``` | ||
|
||
### Upgrade all `pip-compile` environments | ||
|
||
The below command will upgrade all packages in all `pip-compile` environments. | ||
|
||
```shell | ||
hatch-pip-compile --upgrade --all | ||
``` | ||
|
||
[pipx]: https://github.com/pypa/pipx | ||
[pip]: https://pip.pypa.io |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,239 @@ | ||
# 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_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
lock-filename = "locks/{env_name}.lock" | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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_** | ||
|
||
```toml | ||
[tool.hatch.envs.lint] | ||
type = "pip-compile" | ||
lock-filename = "linting-requirements.txt" | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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. `pip-compile-constraint` can also be set to an empty string to disable | ||
the feature. | ||
|
||
- **_pyproject.toml_** | ||
|
||
```toml | ||
[tool.hatch.envs.default] | ||
type = "pip-compile" | ||
|
||
[tool.hatch.envs.test] | ||
dependencies = [ | ||
"pytest" | ||
] | ||
type = "pip-compile" | ||
pip-compile-constraint = "default" | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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_** | ||
|
||
```toml | ||
[tool.hatch.envs.default] | ||
type = "pip-compile" | ||
pip-compile-constraint = "default" | ||
|
||
[tool.hatch.envs.test] | ||
dependencies = [ | ||
"pytest" | ||
] | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-hashes = true | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-args = [ | ||
"--index-url", | ||
"https://pypi.org/simple", | ||
] | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```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_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-verbose = true | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```toml | ||
[envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-verbose = true | ||
``` | ||
|
||
## pip-compile-installer | ||
|
||
Whether to use [pip] or [pip-sync] to install dependencies into the project. Defaults to `pip`. | ||
When you choose the `pip` option the plugin will run `pip install -r {lockfile}` under the hood | ||
to install the dependencies. When you choose the `pip-sync` option `pip-sync {lockfile}` is invoked | ||
by the plugin. | ||
|
||
The key difference between these options is that `pip-sync` will uninstall any packages that are | ||
not in the lockfile and remove them from your environment. `pip-sync` is useful if you want to ensure | ||
that your environment is exactly the same as the lockfile. If the environment should be used | ||
across different Python versions and platforms `pip` is the safer option to use. | ||
|
||
- **_pyproject.toml_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-installer = "pip-sync" | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```toml | ||
[envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-installer = "pip-sync" | ||
``` | ||
|
||
## pip-compile-install-args | ||
|
||
Extra arguments to pass to `pip-compile-installer`. For example, if you'd like to use `pip` as the | ||
installer but want to pass the `--no-deps` flag to `pip install` you can do so with this option: | ||
|
||
- **_pyproject.toml_** | ||
|
||
```toml | ||
[tool.hatch.envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-installer = "pip" | ||
pip-compile-install-args = [ | ||
"--no-deps" | ||
] | ||
``` | ||
|
||
- **_hatch.toml_** | ||
|
||
```toml | ||
[envs.<envName>] | ||
type = "pip-compile" | ||
pip-compile-installer = "pip" | ||
pip-compile-install-args = [ | ||
"--no-deps" | ||
] | ||
``` | ||
|
||
[pip-sync]: https://github.com/jazzband/pip-tools | ||
[pip]: https://pip.pypa.io | ||
[inheritance]: hhttps://hatch.pypa.io/latest/config/environment/overview/#inheritance |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
# 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. | ||
|
||
```shell | ||
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]: | ||
|
||
```bash | ||
pipx install hatch | ||
pipx inject hatch hatch-pip-compile | ||
``` | ||
|
||
`pipx` also supports upgrading the plugin when any new versions are released: | ||
|
||
```shell | ||
pipx runpip hatch install --upgrade hatch-pip-compile | ||
``` | ||
|
||
Alternatively, you can install the plugin directly with [pip]: | ||
|
||
```bash | ||
pip install hatch hatch-pip-compile | ||
``` | ||
|
||
[pipx]: https://github.com/pypa/pipx | ||
[pip]: https://pip.pypa.io |
Oops, something went wrong.