diff --git a/README.md b/README.md index a7bdec4..5950c44 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

-hatch plugin to use pip-compile to manage project dependencies and lockfiles. +hatch plugin to use pip-compile (or uv) to manage project dependencies and lockfiles.

@@ -19,6 +19,7 @@ Hatch project Pip Tools project + uv Ruff pre-commit semantic-release @@ -88,6 +89,7 @@ Set your environment type to `pip-compile` to use this plugin for the respective - [pip-compile-constraint](docs/examples.md#pip-compile-constraint) - syncing dependency versions across environments - [Upgrading Dependencies](docs/examples.md#upgrading-dependencies) - how to upgrade dependencies - [Using Hashes](docs/examples.md#pip-compile-hashes) - how to include hashes in your lockfile +- [Using uv instead of pip-compile](docs/examples.md#pip-compile-resolver) - how to use `uv` instead of `pip-compile` ### Configuration Options @@ -110,15 +112,16 @@ pip-compile-hashes = true | [lock-filename](docs/examples.md#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](docs/examples.md#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](docs/examples.md#pip-compile-hashes) | `bool` | Whether to generate hashes in the lockfile. Defaults to `false`. | +| [pip-compile-resolver](docs/examples.md#pip-compile-resolver) | `str` | Whether to use `pip-compile` or `uv` to resolve dependencies into the project. Defaults to `pip-compile` | +| [pip-compile-args](docs/examples.md#pip-compile-args) | `list[str]` | Additional command-line arguments to pass to `pip-compile-resolver` | | [pip-compile-verbose](docs/examples.md#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](docs/examples.md#pip-compile-args) | `list[str]` | Additional command-line arguments to pass to `pip-compile` | #### Installing Lockfiles -| name | type | description | -| --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- | -| [pip-compile-installer](docs/examples.md#pip-compile-installer) | `str` | Whether to use `pip` or `pip-sync` to install dependencies into the project. Defaults to `pip` | -| [pip-compile-install-args](docs/examples.md#pip-compile-install-args) | `list[str]` | Additional command-line arguments to pass to `pip-compile-installer` | +| name | type | description | +| --------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- | +| [pip-compile-installer](docs/examples.md#pip-compile-installer) | `str` | Whether to use `pip`, `pip-sync`, or `uv` to install dependencies into the project. Defaults to `pip` | +| [pip-compile-install-args](docs/examples.md#pip-compile-install-args) | `list[str]` | Additional command-line arguments to pass to `pip-compile-installer` | diff --git a/docs/examples.md b/docs/examples.md index 674b758..09c8f92 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -131,9 +131,46 @@ Whether to generate hashes in the lockfile. Defaults to `false`. pip-compile-hashes = true ``` +## pip-compile-resolver + +Which resolver to use to generate the lockfile. Defaults to `pip-compile`. + +[uv] is a drop in replacement for `pip-compile` with a much faster resolver written in rust. +If you'd like to use `uv` instead of `pip-compile` you can set the `pip-compile-resolver` option. + +> NOTE: **pip-compile-installer** +> +> [uv] can also be used as the default installer instead of `pip`. See +> the [pip-compile-installer](#pip-compile-installer) option for more +> information. + +> WARNING: **uv** +> +> As of writing this the [uv] project +> is brand new and still very actively being developed and may not be suitable for all +> use cases. Known issues are currently options like `--exclude-unsafe` and how it handles +> installing packages with hashes. The latest version of `uv` will be installed into your +> environment when it's created. + +- **_pyproject.toml_** + + ```toml + [tool.hatch.envs.] + type = "pip-compile" + pip-compile-resolver = "uv" + ``` + +- **_hatch.toml_** + + ```toml + [envs.] + type = "pip-compile" + pip-compile-resolver = "uv" + ``` + ## pip-compile-args -Extra arguments to pass to `pip-compile`. Custom PyPI indexes can be specified here. +Extra arguments to pass to `pip-compile-resolver`. Custom PyPI indexes can be specified here. - **_pyproject.toml_** @@ -161,7 +198,8 @@ Extra arguments to pass to `pip-compile`. Custom PyPI indexes can be specified h 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`. +Optionally, if you would like to silence any warnings set the `pip-compile-verbose` option +to `false`. - **_pyproject.toml_** @@ -181,15 +219,16 @@ Optionally, if you would like to silence any warnings set the `pip-compile-verbo ## 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. +Whether to use [pip], [pip-sync], or [uv] 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. [uv] is a drop in replacement for +`pip`, it has the same behavior as `pip` installer, `uv pip install -r {lockfile}`. 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. +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_** @@ -237,3 +276,4 @@ installer but want to pass the `--no-deps` flag to `pip install` you can do so w [pip-sync]: https://github.com/jazzband/pip-tools [pip]: https://pip.pypa.io [inheritance]: hhttps://hatch.pypa.io/latest/config/environment/overview/#inheritance +[uv]: https://github.com/astral-sh/uv diff --git a/mkdocs.yaml b/mkdocs.yaml index 6f86dcc..1417e08 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -36,7 +36,6 @@ repo_name: hatch-pip-compile edit_uri: blob/main/docs/ site_author: juftin remote_branch: gh-pages -copyright: Copyright © 2023 Justin Flannery extra: generator: false exclude_docs: |