From 29b529554dafce23879dde7394d69d49a3e74365 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 27 Jun 2025 12:07:51 +0100 Subject: [PATCH 1/3] docs: Allow version_deprecated option We also remove the unused 'version_changed' option. Signed-off-by: Stephen Finucane --- docs/tox_conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/tox_conf.py b/docs/tox_conf.py index d1f2c0c14..dfcace07b 100644 --- a/docs/tox_conf.py +++ b/docs/tox_conf.py @@ -24,7 +24,7 @@ class ToxConfig(SphinxDirective): option_spec: Final[ClassVar[dict[str, Any]]] = { "keys": unchanged_required, "version_added": unchanged, - "version_changed": unchanged, + "version_deprecated": unchanged, "default": unchanged, "constant": flag, "ref_suffix": unchanged, @@ -71,6 +71,10 @@ def run(self) -> list[Node]: line += Text(" 📢 added in ") ver = self.options["version_added"] line += literal(ver, ver) + if "version_deprecated" in self.options: + line += Text(" ⚠️ deprecated in ") + ver = self.options["version_deprecated"] + line += literal(ver, ver) p = container("") self.state.nested_parse(StringList(string2lines("\n".join(f" {i}" for i in self.content))), 0, p) From a41f77f3ac87716ffafde077e7cc9b20a184593c Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 27 Jun 2025 12:12:26 +0100 Subject: [PATCH 2/3] tox: Soft-deprecate '[tox] min_version' We don't raise a warning or similar: this is purely to encourage new users (and existing users reworking their tox.ini files) to prefer '[tox] requires'. Signed-off-by: Stephen Finucane --- docs/changelog/3553.doc.rst | 1 + docs/config.rst | 12 +++++++++--- docs/upgrading.rst | 2 +- docs/user_guide.rst | 12 ++++++------ 4 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 docs/changelog/3553.doc.rst diff --git a/docs/changelog/3553.doc.rst b/docs/changelog/3553.doc.rst new file mode 100644 index 000000000..66cb8f3ec --- /dev/null +++ b/docs/changelog/3553.doc.rst @@ -0,0 +1 @@ +The ``min_version``/``minversion`` config option is deprecated in favor of the ``requires`` option. diff --git a/docs/config.rst b/docs/config.rst index 122627ee4..d9127b7ca 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -46,7 +46,8 @@ For example: .. code-block:: ini [tox] - min_version = 4.20 + requires = + tox >= 4.20 env_list = 3.13 3.12 @@ -74,7 +75,8 @@ This configuration file uses: .. code-block:: ini [tox:tox] - min_version = 4.0 + requires = + tox >= 4.0 env_list = 3.13 3.12 @@ -98,7 +100,8 @@ instead inside the ``pyproject.toml`` file under the ``tool.tox`` table and ``le [tool.tox] legacy_tox_ini = """ [tox] - min_version = 4.0 + requires = + tox >= 4.0 env_list = py310 py39 @@ -203,6 +206,9 @@ The following options are set in the ``[tox]`` section of ``tox.ini`` or the ``[ .. conf:: :keys: min_version, minversion :default: + :version_deprecated: 4.28.0 + + **DEPRECATED** Prefer requiring a minimum tox version via :ref:`requires`. A string to define the minimal tox version required to run. If the host's tox version is less than this, it will automatically create a provisioned tox environment that satisfies this requirement. See :ref:`provision_tox_env` diff --git a/docs/upgrading.rst b/docs/upgrading.rst index cf1aa46cd..a6de73e0c 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -321,6 +321,6 @@ version is above the version this feature was added to it, for example for setup Provisioning environment ------------------------ -The provisioning environment is triggered when ``minversion`` or ``requires`` are specified and the current environment +The provisioning environment is triggered when ``min_version`` or ``requires`` are specified and the current environment does not satisfy the requirement. In tox 4, the provisioning environment (``.tox`` by default) must be explicitly configured and will not inherit values from ``[testenv]`` section. diff --git a/docs/user_guide.rst b/docs/user_guide.rst index f262541a1..9afe702e7 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -385,7 +385,8 @@ you want to do more research, we recommend taking a look at these projects: Auto-provisioning ----------------- -In case the installed tox version does not satisfy either the :ref:`min_version` or the :ref:`requires`, tox will automatically + +In case the installed tox version does not satisfy either the :ref:`requires` or the :ref:`min_version`, tox will automatically create a virtual environment under :ref:`provision_tox_env` name that satisfies those constraints and delegate all calls to this meta environment. This should allow satisfying constraints on your tox environment automatically, given you have at least version ``3.8.0`` of tox. @@ -396,17 +397,16 @@ For example given: .. code-block:: toml - min_version = "4" - requires = ["tox-uv>=1"] + requires = ["tox>=4", "tox-uv>=1"] .. tab:: INI .. code-block:: ini [tox] - min_version = 4 - requires = tox-uv>=1 - + requires = + tox>=4 + tox-uv>=1 if the user runs it with tox ``3.8`` or later the installed tox application will automatically ensure that both the minimum version and requires constraints are satisfied, by creating a virtual environment under ``.tox`` folder, and then installing into it From 5134f5d5202c0e65b18e69fe22ac355f5c817e36 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 27 Jun 2025 12:21:29 +0100 Subject: [PATCH 3/3] docs: Explain use of auto-provisioning for required plugins Signed-off-by: Stephen Finucane --- docs/installation.rst | 9 ++++++--- docs/plugins.rst | 46 ++++++++++++++++++++++++++++++++++++++----- docs/user_guide.rst | 1 + 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 728652c79..51b1bcad7 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,10 +2,10 @@ Installation ============ As tool --------- +------- :pypi:`tox` is a CLI tool that needs a Python interpreter (version 3.9 or higher) to run. We recommend either -:pypi:`pipx` or :pypi:`uv` to install tox into an isolated environment. This has the added benefit that later you'll +:pypi:`pipx` or :pypi:`uv` to install tox into an isolated environment. This has the added benefit that later you'll be able to upgrade tox without affecting other parts of the system. We provide method for ``pip`` too here but we discourage that path if you can: @@ -17,7 +17,6 @@ discourage that path if you can: uv tool install tox tox --help - .. tab:: pipx .. code-block:: bash @@ -40,6 +39,7 @@ discourage that path if you can: wheel ~~~~~ + Installing tox via a wheel (default with pip) requires an installer that can understand the ``python-requires`` tag (see :pep:`503`), with pip this is version ``9.0.0`` (released in November 2016). Furthermore, in case you're not installing it via PyPI you need to use a mirror that correctly forwards the ``python-requires`` tag (notably the OpenStack mirrors @@ -49,6 +49,7 @@ don't do this, or older :gh_repo:`devpi/devpi` versions - added with version ``4 sdist ~~~~~ + When installing via a source distribution you need an installer that handles the :pep:`517` specification. In case of ``pip`` this is version ``18.0.0`` or later (released in July 2018). If you cannot upgrade your pip to support this you need to ensure that the build requirements from :gh:`pyproject.toml ` are @@ -56,12 +57,14 @@ satisfied before triggering the installation. via ``setup.py`` ---------------- + We don't recommend and officially support this method. You should prefer using an installer that supports :pep:`517` interface, such as pip ``19.0.0`` or later. That being said you might be able to still install a package via this method if you satisfy build dependencies before calling the installation command (as described under :ref:`sdist`). latest unreleased ----------------- + Installing an unreleased version is discouraged and should be only done for testing purposes. If you do so you'll need a pip version of at least ``18.0.0`` and use the following command: diff --git a/docs/plugins.rst b/docs/plugins.rst index 6dae6febc..94ddfab8a 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -1,5 +1,37 @@ -Extending tox -============= +Plugins +======= + +Many plugins are available for tox. These include, but are not limited to, the extensions found on the ``tox-dev`` org +on ':gh:`GitHub `. + +Plugins are automatically discovered once from the Python environment that tox itself is installed in. This means that +if tox is installed in an isolated environment (e.g. when installed using :pypi:`pipx` or :pypi:`uv`), the plugin(s) +must be installed in the same environment. To ensure a plugin is always available, you can include the plugin is listed +in :ref:`requires`, which will cause tox to auto-provision a new isolated environment with both tox and the plugin(s) +installed. For example: + +.. tab:: TOML + + .. code-block:: toml + + requires = ["tox>=4", "tox-uv>=1"] + +.. tab:: INI + + .. code-block:: ini + + [tox] + requires = + tox>=4 + tox-uv>=1 + +For more information, refer to :ref:`the user guide `. + +Developing your own plugin +-------------------------- + +The below provides some guidance on how to develop your own plugin for tox. A reference guide to the plugin API can be +found in :doc:`plugins_api`. Extensions points ~~~~~~~~~~~~~~~~~ @@ -50,20 +82,24 @@ How to apply: Migration from tox 3 ~~~~~~~~~~~~~~~~~~~~ + This section explains how the plugin interface changed between tox 3 and 4, and provides guidance for plugin developers on how to migrate. ``tox_get_python_executable`` ------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + With tox 4 the Python discovery is performed ``tox.tox_env.python.virtual_env.api._get_python`` that delegates the job to ``virtualenv``. Therefore first `define a new virtualenv discovery mechanism `_ and then set that by setting the ``VIRTUALENV_DISCOVERY`` environment variable. ``tox_package`` ---------------- +^^^^^^^^^^^^^^^ + Register new packager types via :func:`tox_register_tox_env `. ``tox_addoption`` ------------------ +^^^^^^^^^^^^^^^^^ + Renamed to :func:`tox_add_option `. diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 9afe702e7..beb0322b0 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -382,6 +382,7 @@ you want to do more research, we recommend taking a look at these projects: - `Invoke `__ is a general-purpose task execution library, similar to Make. Invoke is far more general-purpose than tox but it does not contain the Python testing-specific features that tox specializes in. +.. _auto-provisioning: Auto-provisioning -----------------