|
3 | 3 |
|
4 | 4 | Here you'll find answers to some frequently asked questions. |
5 | 5 |
|
| 6 | +Breaking changes in tox 4 |
| 7 | +------------------------- |
| 8 | +Version 4 of tox should be mostly backwards compatible with version 3, with the following exceptions: |
| 9 | + |
| 10 | +tox 4 - Python support |
| 11 | +++++++++++++++++++++++ |
| 12 | +- tox now requires Python ``3.7`` or later and is tested only against CPython. You can still create test environments |
| 13 | + for earlier Python versions or different Python interpreters. PyPy support is best effort, meaning we do not test it |
| 14 | + as part of our CI runs, however if you discover issues under PyPy we will accept PRs addressing it. |
| 15 | + |
| 16 | +tox 4 - known regressions |
| 17 | ++++++++++++++++++++++++++ |
| 18 | + |
| 19 | +- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is |
| 20 | + that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the |
| 21 | + ``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy |
| 22 | + `here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_. |
| 23 | + |
| 24 | +tox 4 - new plugin system |
| 25 | ++++++++++++++++++++++++++ |
| 26 | + |
| 27 | +tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort |
| 28 | +has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code |
| 29 | +base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for |
| 30 | +more information. |
| 31 | + |
| 32 | +tox 4 - removed tox.ini keys |
| 33 | +++++++++++++++++++++++++++++ |
| 34 | + |
| 35 | ++--------------------------+---------------------------------------------+ |
| 36 | +| Configuration key | Migration path | |
| 37 | ++==========================+=============================================+ |
| 38 | +| ``indexserver`` | See `Using a custom PyPI server`_. | |
| 39 | ++--------------------------+---------------------------------------------+ |
| 40 | +| ``whitelist_externals`` | Use :ref:`allowlist_externals` key instead. | |
| 41 | ++--------------------------+---------------------------------------------+ |
| 42 | +| ``isolated_build`` | Isolated builds are now always used. | |
| 43 | ++--------------------------+---------------------------------------------+ |
| 44 | + |
| 45 | +tox 4 - substitutions removed |
| 46 | ++++++++++++++++++++++++++++++ |
| 47 | +- The ``distshare`` substitution has been removed. |
| 48 | + |
| 49 | +tox 4 - disallowed env names |
| 50 | +++++++++++++++++++++++++++++ |
| 51 | +- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise |
| 52 | + an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we |
| 53 | + recommend changing the name to avoid this name that can be confusing. |
| 54 | + |
| 55 | +tox 4 - CLI arguments changed |
| 56 | ++++++++++++++++++++++++++++++ |
| 57 | +- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed. |
| 58 | +- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this |
| 59 | + worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is |
| 60 | + no longer the case. |
| 61 | + |
| 62 | +tox 4 - packaging changes |
| 63 | ++++++++++++++++++++++++++ |
| 64 | +- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend. |
| 65 | +- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660` |
| 66 | + mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting |
| 67 | + the :ref:`package` setting for the run environment to ``editable-legacy``. |
| 68 | + |
| 69 | +tox 4 -- output changes |
| 70 | ++++++++++++++++++++++++ |
| 71 | +- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the |
| 72 | + ``TERM=dumb`` or ``NO_COLORS=0`` environment variables, or the ``--colored no`` CLI argument. |
| 73 | + |
| 74 | +New features in tox 4 |
| 75 | +--------------------- |
| 76 | +Here is a non-exhaustive list of these. |
| 77 | + |
| 78 | +- You can now build wheel(s) instead of a source distribution during the packaging phase by using the ``wheel`` setting |
| 79 | + for the :ref:`package` setting. If your package is a universal wheel you'll likely want to set the |
| 80 | + :ref:`wheel_build_env` to ``.pkg`` to avoid building a wheel for every Python version you target. |
| 81 | +- Editable wheel support was added as defined by :pep:`660` via the :ref:`package` setting to ``editable``. |
| 82 | +- We redesigned our CLI interface, we no longer try to squeeze everything under single command, instead now we have |
| 83 | + multiple sub-commands. For backwards compatibility if you do not specify a subcommand we'll assume you want the tox 3 |
| 84 | + legacy interface (available under the legacy subcommand), for now the list of available commands are: |
| 85 | + |
| 86 | + .. code-block:: bash |
| 87 | +
|
| 88 | + subcommands: |
| 89 | + tox command to execute (by default legacy) |
| 90 | +
|
| 91 | + {run,r,run-parallel,p,depends,de,list,l,devenv,d,config,c,quickstart,q,exec,e,legacy,le} |
| 92 | + run (r) run environments |
| 93 | + run-parallel (p) run environments in parallel |
| 94 | + depends (de) visualize tox environment dependencies |
| 95 | + list (l) list environments |
| 96 | + devenv (d) sets up a development environment at ENVDIR based on the tox configuration specified |
| 97 | + config (c) show tox configuration |
| 98 | + quickstart (q) Command line script to quickly create a tox config file for a Python project |
| 99 | + exec (e) execute an arbitrary command within a tox environment |
| 100 | + legacy (le) legacy entry-point command |
| 101 | +
|
| 102 | + The ``exec`` and ``depends`` are brand new features. Other subcommands are a more powerful versions of previously |
| 103 | + existing single flags (e.g. ``-av`` is now succeeded by the ``list`` subcommand). All subcommands have a one or two |
| 104 | + character shortcuts for less typing on the CLI (e.g. ``tox run`` can be abbreviated to ``tox r``). For more details |
| 105 | + see :ref:`cli`. |
| 106 | +- Startup times should be improved because now we no longer eagerly load all configurations for all environments, but |
| 107 | + instead these are performed lazily when needed. Side-effect of this is that if you have an invalid configuration will |
| 108 | + not be picked up until you try to use it. |
| 109 | +- We now discover your package dependency changes (either via :pep:`621` or otherwise via :pep:`517` |
| 110 | + ``prepare_metadata_for_build_wheel``/``build_wheel`` metadata). If new dependencies are added these will be installed |
| 111 | + on the next run. If a dependency is removed we'll recreate the entire environment. This works for ``requirements`` |
| 112 | + files within the :ref:`deps`. This means that you should never need to use ``--recreate`` flag, tox should be smart |
| 113 | + enough to figure out when things change and automatically apply it. |
| 114 | +- All tox defaults can now be changed via the user level config-file (see help message output for its location, can be |
| 115 | + changed via ``TOX_CONFIG_FILE`` environment variable). |
| 116 | +- All tox defaults can now be changed via an environment variable: ``TOX_`` prefix followed by the settings key, |
| 117 | + e.g. ``TOX_PACKAGE=wheel``. |
| 118 | +- Any configuration can be overwritten via the CLI ``-x`` or ``--override`` flag, e.g. |
| 119 | + ``tox run -e py311 -x testenv:py310.package=editable`` would force the packaging of environment ``py311`` to be an |
| 120 | + editable install independent what's in the configuration file. |
| 121 | +- :ref:`basepython` is now a list, the first successfully detected python will be used to generate python environment. |
| 122 | +- We now have support for inline tox plugins via the ``toxfile.py`` at the root of your project. At a later time this |
| 123 | + will allow using Python only configuration, as seen with nox. |
| 124 | +- You can now group tox environments via :ref:`labels` configuration, and you can invoke all tox environments within a |
| 125 | + label by using the ``-m label`` CLI flag (instead of the ``-e list_of_envs``). |
| 126 | +- You can now invoke all tox environments within a given factor via the ``-f factor`` CLI flag. |
| 127 | + |
6 | 128 | Using a custom PyPI server |
7 | 129 | -------------------------- |
8 | | - |
9 | 130 | By default tox uses pip to install Python dependencies. Therefore to change the index server you should configure pip |
10 | 131 | directly. pip accepts environment variables as configuration flags, therefore the easiest way to do this is to set the |
11 | 132 | ``PIP_INDEX_URL`` environment variable: |
|
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
0 commit comments