Metadata-Version: 2.3
Name: tox-uv
Version: 1.13.1
Summary: Integration of uv with tox.
Project-URL: Changelog, https://github.com/tox-dev/tox-uv/releases
Project-URL: Documentation, https://github.com/tox-dev/tox-uv#tox-uv
Project-URL: Homepage, https://github.com/tox-dev/tox-uv
Project-URL: Source, https://github.com/tox-dev/tox-uv
Project-URL: Tracker, https://github.com/tox-dev/tox-uv/issues
Maintainer-email: Bernát Gábor <gaborjbernat@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: environments,isolated,testing,virtual
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System
Requires-Python: >=3.8
Requires-Dist: importlib-resources>=6.4.5; python_version < '3.9'
Requires-Dist: packaging>=24.1
Requires-Dist: tox<5,>=4.20
Requires-Dist: typing-extensions>=4.12.2; python_version < '3.10'
Requires-Dist: uv<1,>=0.4.12
Provides-Extra: testing
Requires-Dist: covdefaults>=2.3; extra == 'testing'
Requires-Dist: devpi-process>=1.0.2; extra == 'testing'
Requires-Dist: diff-cover>=9.2; extra == 'testing'
Requires-Dist: pytest-cov>=5; extra == 'testing'
Requires-Dist: pytest-mock>=3.14; extra == 'testing'
Requires-Dist: pytest>=8.3.3; extra == 'testing'
Description-Content-Type: text/markdown

# tox-uv

[![PyPI version](https://badge.fury.io/py/tox-uv.svg)](https://badge.fury.io/py/tox-uv)
[![PyPI Supported Python Versions](https://img.shields.io/pypi/pyversions/tox-uv.svg)](https://pypi.python.org/pypi/tox-uv/)
[![check](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/tox-uv/actions/workflows/check.yaml)
[![Downloads](https://static.pepy.tech/badge/tox-uv/month)](https://pepy.tech/project/tox-uv)

**tox-uv** is a `tox` plugin, which replaces `virtualenv` and pip with `uv` in your `tox` environments. Note that you
will get both the benefits (performance) or downsides (bugs) of `uv`.

<!--ts-->

- [How to use](#how-to-use)
- [tox environment types provided](#tox-environment-types-provided)
- [uv.lock support](#uvlock-support)
  - [extras](#extras)
  - [with_dev](#with_dev)
  - [External package support](#external-package-support)
- [Environment creation](#environment-creation)
  - [uv_seed](#uv_seed)
  - [uv_python_preference](#uv_python_preference)
- [Package installation](#package-installation)
  - [uv_resolution](#uv_resolution)
  <!--te-->

## How to use

Install `tox-uv` into the environment of your tox, and it will replace `virtualenv` and `pip` for all runs:

```bash
uv tool install tox --with tox-uv # use uv to install
tox --version # validate you are using the installed tox
tox r -e py312 # will use uv
```

## tox environment types provided

This package will provide the following new tox environments:

- `uv-venv-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#runner) for
  environments not using a lock file.
- `uv-venv-lock-runner` is the ID for the tox environments [runner](https://tox.wiki/en/4.12.1/config.html#runner) for
  environments using `uv.lock` (note we can’t detect the presence of the `uv.lock` file to enable this because that
  would break environments not using the lock file - such as your linter).
- `uv-venv-pep-517` is the ID for the PEP-517 packaging environment.
- `uv-venv-cmd-builder` is the ID for the external cmd builder.

## uv.lock support

If you want for a tox environment to use `uv sync` with a `uv.lock` file you need to change for that tox environment the
`runner` to `uv-venv-lock-runner`. Furthermore, should in such environments you use the `extras` config to instruct `uv`
to install the specified extras, for example:

```ini

[testenv:fix]
description = run code formatter and linter (auto-fix)
skip_install = true
deps =
    pre-commit-uv>=4.1.1
commands =
    pre-commit run --all-files --show-diff-on-failure

[testenv:type]
runner = uv-venv-lock-runner
description = run type checker via mypy
commands =
    mypy {posargs:src}

[testenv:dev]
runner = uv-venv-lock-runner
description = dev environment
extras =
    dev
    test
    type
commands =
    uv pip tree
```

In this example:

- `fix` will use the `uv-venv-runner` and use `uv pip install` to install dependencies to the environment.
- `type` will use the `uv-venv-lock-runner` and use `uv sync` to install dependencies to the environment without any
  extra group.
- `dev` will use the `uv-venv-lock-runner` and use `uv sync` to install dependencies to the environment with the `dev`,
  `test` and `type` extra groups.

Note that when using `uv-venv-lock-runner`, _all_ dependencies will come from the lock file, controlled by `extras`.
Therefore, options like `deps` are ignored (and all others
[enumerated here](https://tox.wiki/en/stable/config.html#python-run) as Python run flags).

### `extras`

A list of string that selects, which extra groups you want to install with `uv sync`. By default, it is empty.

### `with_dev`

A boolean flag to toggle installation of the `uv` development dependencies. By default, it is false.

### External package support

Should tox be invoked with the [`--installpkg`](https://tox.wiki/en/stable/cli_interface.html#tox-run---installpkg) flag
(the argument **must** be either a wheel or source distribution) the sync operation will run with `--no-install-project`
and `uv pip install` will be used afterward to install the provided package.

## Environment creation

We use `uv venv` to create virtual environments. This process can be configured with the following options:

### `uv_seed`

This flag, set on a tox environment level, controls if the created virtual environment injects `pip`, `setuptools` and
`wheel` into the created virtual environment or not. By default, it is off. You will need to set this if you have a
project that uses the old legacy-editable mode, or your project doesn’t support the `pyproject.toml` powered isolated
build model.

### `uv_python_preference`

This flag, set on a tox environment level, controls how `uv` select the Python interpreter.

By default, `uv` will attempt to use Python versions found on the system and only download managed interpreters when
necessary. However, It is possible to adjust `uv`'s Python version selection preference with the
[python-preference](https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences) option.

## Package installation

We use `uv pip` to install packages into the virtual environment. The behavior of this can be configured via the
following options:

### `uv_resolution`

This flag, set on a tox environment level, informs `uv` of the desired [resolution strategy]:

- `highest` - (default) selects the highest version of a package satisfying the constraints.
- `lowest` - install the **lowest** compatible versions for all dependencies, both **direct** and **transitive**.
- `lowest-direct` - opt for the **lowest** compatible versions for all **direct** dependencies, while using the
  **latest** compatible versions for all **transitive** dependencies.

This is an `uv` specific feature that may be used as an alternative to frozen constraints for test environments if the
intention is to validate the lower bounds of your dependencies during test executions.

[resolution strategy]: https://github.com/astral-sh/uv/blob/0.1.20/README.md#resolution-strategy
