diff options
| author | Jürgen Gmach <juergen.gmach@googlemail.com> | 2022-12-07 17:39:05 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-12-07 08:39:05 -0800 |
| commit | fc4d93848af4717d48c4fdbcd691cb5a4b476783 (patch) | |
| tree | 24b5249ae044c971631647b76a6229da81ca933f | |
| parent | 17c5c1fa1890af35e87df73a2548fdfa75656ca5 (diff) | |
| download | tox-git-fc4d93848af4717d48c4fdbcd691cb5a4b476783.tar.gz | |
Create a FAQ entry about tox v3 - v4 compatibility (#2601)
Co-authored-by: Jürgen Gmach <juergen.gmach@googlemail.com>
Co-authored-by: Bernát Gábor <bgabor8@bloomberg.net>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>
Resolves https://github.com/tox-dev/tox/issues/2578
Resolves https://github.com/tox-dev/tox/issues/2602
Resolves https://github.com/tox-dev/tox/issues/2608
| -rw-r--r-- | README.md | 59 | ||||
| -rw-r--r-- | docs/changelog/2587.doc.rst | 1 | ||||
| -rw-r--r-- | docs/changelog/2602.doc.rst | 1 | ||||
| -rw-r--r-- | docs/changelog/2608.bugfix.rst | 1 | ||||
| -rw-r--r-- | docs/cli_interface.rst | 2 | ||||
| -rw-r--r-- | docs/config.rst | 4 | ||||
| -rw-r--r-- | docs/faq.rst | 123 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | src/new.md | 93 | ||||
| -rw-r--r-- | src/tox/config/sets.py | 2 |
10 files changed, 151 insertions, 137 deletions
@@ -1,46 +1,27 @@ -# Rewrite branch +# tox -[](https://github.com/tox-dev/tox/actions?query=workflow%3Acheck) -[](https://codecov.io/gh/tox-dev/tox/branch/rewrite) +[](https://pypi.org/project/tox/) +[](https://pypi.org/project/tox/) +[](https://tox.readthedocs.io/en/latest/?badge=latest) [](https://github.com/psf/black) +[](https://pepy.tech/project/tox/month) +[](https://github.com/tox-dev/tox/actions/workflows/check.yml) -<a href="https://tox.readthedocs.io"> - <img src="https://raw.githubusercontent.com/tox-dev/tox/master/docs/_static/img/tox.png" - alt="tox logo" - height="150px" - align="right"> -</a> +`tox` aims to automate and standardize testing in Python. It is part of a larger vision of easing the packaging, testing +and release process of Python software (alongside [pytest](https://docs.pytest.org/en/latest/) and +[devpi](https://www.devpi.net)). -You've arrived at the rewrite branch. This is a fresh start for tox in which we aim to create a better implementation -for what tox is. The broad goal is to: +tox is a generic virtual environment management and test command line tool you can use for: -- use modern Python with type annotations (`3.6+` only) -- be more flexible in from where we take our configuration (proper `pyproject.toml` support besides our canonical - `tox.ini` file) -- a better interface to plug and play your own python environment (historically tox was designed to work with the - `virtualenv` project, but we want to be able to use instead `conda`, `Docker`, OS package manager, remote machines, - etc.) -- first class support for non-sdist packages (in python land e.g. wheels) -- ability to plugin support for other languages that follow the build/install/test paradigm (e.g. node) -- make it more flexible (ability to override any value via the CLI) -- make it faster (improve interpreter discovery, lazy configuration manifestation, and many more). +- checking your package builds and installs correctly under different environments (such as different Python + implementations, versions or installation dependencies), +- running your tests in each of the environments with the test tool of choice, +- acting as a frontend to continuous integration servers, greatly reducing boilerplate and merging CI and shell-based + testing. -**Compatibility wise we aim to be (excluding some weird edge cases) configuration file compatible with tox 3. We'll not -be API compatible though (all plugins will break).** - -## Documentation - -To be done. - -## Communication and questions - -For now reach out to [Bernat Gabor](https://github.com/gaborbernat/) directly. - -## Contributing - -Contributions are welcome, though expect a lot of rough edges at this early point of development. See -[contributing](https://github.com/tox-dev/tox/blob/master/CONTRIBUTING.rst) and our -[Contributor Covenant Code of Conduct](https://github.com/tox-dev/tox/blob/master/CODE_OF_CONDUCT.md). Currently, the -[code](https://github.com/tox-dev/tox) and the [issues](https://github.com/tox-dev/tox/issues) are hosted on GitHub. The -project is licensed under [MIT](https://github.com/tox-dev/tox/blob/master/LICENSE). +Please read our [user guide](https://tox.wiki/en/latest/user_guide.html#basic-example) for an example and more detailed +introduction, or watch [this YouTube video](https://www.youtube.com/watch?v=SFqna5ilqig) that presents the problem space +and how tox solves it. diff --git a/docs/changelog/2587.doc.rst b/docs/changelog/2587.doc.rst new file mode 100644 index 00000000..f7ed3eca --- /dev/null +++ b/docs/changelog/2587.doc.rst @@ -0,0 +1 @@ +Enumerate breaking changes of tox 4 in the FAQ, and also list major new improvements - by :user:`gaborbernat`. diff --git a/docs/changelog/2602.doc.rst b/docs/changelog/2602.doc.rst new file mode 100644 index 00000000..c8a84109 --- /dev/null +++ b/docs/changelog/2602.doc.rst @@ -0,0 +1 @@ +Document in the FAQ that tox 4 will raise a warning when finding conflicting environment names - by :user:`gaborbernat`. diff --git a/docs/changelog/2608.bugfix.rst b/docs/changelog/2608.bugfix.rst new file mode 100644 index 00000000..55316c3e --- /dev/null +++ b/docs/changelog/2608.bugfix.rst @@ -0,0 +1 @@ +The temporary folder within the tox environment was named ``.temp`` instead of ``.tmp`` - by :user:`gaborbernat`. diff --git a/docs/cli_interface.rst b/docs/cli_interface.rst index 7bbc50fc..f58dd8e7 100644 --- a/docs/cli_interface.rst +++ b/docs/cli_interface.rst @@ -1,3 +1,5 @@ +.. _cli: + .. sphinx_argparse_cli:: :module: tox.config.cli.parse :func: _get_parser_doc diff --git a/docs/config.rst b/docs/config.rst index 09826039..da3812c5 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -497,8 +497,8 @@ Run tox package type used to package. -Package -~~~~~~~ +Packaging +~~~~~~~~~ .. conf:: :keys: package_root, setupdir :default: {package_root} diff --git a/docs/faq.rst b/docs/faq.rst index 1f584dc4..d3881a2b 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -3,9 +3,130 @@ FAQ Here you'll find answers to some frequently asked questions. +Breaking changes in tox 4 +------------------------- +Version 4 of tox should be mostly backwards compatible with version 3, with the following exceptions: + +tox 4 - Python support +++++++++++++++++++++++ +- tox now requires Python ``3.7`` or later and is tested only against CPython. You can still create test environments + for earlier Python versions or different Python interpreters. PyPy support is best effort, meaning we do not test it + as part of our CI runs, however if you discover issues under PyPy we will accept PRs addressing it. + +tox 4 - known regressions ++++++++++++++++++++++++++ + +- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is + that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the + ``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy + `here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_. + +tox 4 - new plugin system ++++++++++++++++++++++++++ + +tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort +has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code +base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for +more information. + +tox 4 - removed tox.ini keys +++++++++++++++++++++++++++++ + ++--------------------------+---------------------------------------------+ +| Configuration key | Migration path | ++==========================+=============================================+ +| ``indexserver`` | See `Using a custom PyPI server`_. | ++--------------------------+---------------------------------------------+ +| ``whitelist_externals`` | Use :ref:`allowlist_externals` key instead. | ++--------------------------+---------------------------------------------+ +| ``isolated_build`` | Isolated builds are now always used. | ++--------------------------+---------------------------------------------+ + +tox 4 - substitutions removed ++++++++++++++++++++++++++++++ +- The ``distshare`` substitution has been removed. + +tox 4 - disallowed env names +++++++++++++++++++++++++++++ +- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise + an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we + recommend changing the name to avoid this name that can be confusing. + +tox 4 - CLI arguments changed ++++++++++++++++++++++++++++++ +- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed. +- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this + worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is + no longer the case. + +tox 4 - packaging changes ++++++++++++++++++++++++++ +- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend. +- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660` + mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting + the :ref:`package` setting for the run environment to ``editable-legacy``. + +tox 4 -- output changes ++++++++++++++++++++++++ +- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the + ``TERM=dumb`` or ``NO_COLORS=0`` environment variables, or the ``--colored no`` CLI argument. + +New features in tox 4 +--------------------- +Here is a non-exhaustive list of these. + +- You can now build wheel(s) instead of a source distribution during the packaging phase by using the ``wheel`` setting + for the :ref:`package` setting. If your package is a universal wheel you'll likely want to set the + :ref:`wheel_build_env` to ``.pkg`` to avoid building a wheel for every Python version you target. +- Editable wheel support was added as defined by :pep:`660` via the :ref:`package` setting to ``editable``. +- We redesigned our CLI interface, we no longer try to squeeze everything under single command, instead now we have + multiple sub-commands. For backwards compatibility if you do not specify a subcommand we'll assume you want the tox 3 + legacy interface (available under the legacy subcommand), for now the list of available commands are: + + .. code-block:: bash + + subcommands: + tox command to execute (by default legacy) + + {run,r,run-parallel,p,depends,de,list,l,devenv,d,config,c,quickstart,q,exec,e,legacy,le} + run (r) run environments + run-parallel (p) run environments in parallel + depends (de) visualize tox environment dependencies + list (l) list environments + devenv (d) sets up a development environment at ENVDIR based on the tox configuration specified + config (c) show tox configuration + quickstart (q) Command line script to quickly create a tox config file for a Python project + exec (e) execute an arbitrary command within a tox environment + legacy (le) legacy entry-point command + + The ``exec`` and ``depends`` are brand new features. Other subcommands are a more powerful versions of previously + existing single flags (e.g. ``-av`` is now succeeded by the ``list`` subcommand). All subcommands have a one or two + character shortcuts for less typing on the CLI (e.g. ``tox run`` can be abbreviated to ``tox r``). For more details + see :ref:`cli`. +- Startup times should be improved because now we no longer eagerly load all configurations for all environments, but + instead these are performed lazily when needed. Side-effect of this is that if you have an invalid configuration will + not be picked up until you try to use it. +- We now discover your package dependency changes (either via :pep:`621` or otherwise via :pep:`517` + ``prepare_metadata_for_build_wheel``/``build_wheel`` metadata). If new dependencies are added these will be installed + on the next run. If a dependency is removed we'll recreate the entire environment. This works for ``requirements`` + files within the :ref:`deps`. This means that you should never need to use ``--recreate`` flag, tox should be smart + enough to figure out when things change and automatically apply it. +- All tox defaults can now be changed via the user level config-file (see help message output for its location, can be + changed via ``TOX_CONFIG_FILE`` environment variable). +- All tox defaults can now be changed via an environment variable: ``TOX_`` prefix followed by the settings key, + e.g. ``TOX_PACKAGE=wheel``. +- Any configuration can be overwritten via the CLI ``-x`` or ``--override`` flag, e.g. + ``tox run -e py311 -x testenv:py310.package=editable`` would force the packaging of environment ``py311`` to be an + editable install independent what's in the configuration file. +- :ref:`basepython` is now a list, the first successfully detected python will be used to generate python environment. +- We now have support for inline tox plugins via the ``toxfile.py`` at the root of your project. At a later time this + will allow using Python only configuration, as seen with nox. +- You can now group tox environments via :ref:`labels` configuration, and you can invoke all tox environments within a + label by using the ``-m label`` CLI flag (instead of the ``-e list_of_envs``). +- You can now invoke all tox environments within a given factor via the ``-f factor`` CLI flag. + Using a custom PyPI server -------------------------- - By default tox uses pip to install Python dependencies. Therefore to change the index server you should configure pip directly. pip accepts environment variables as configuration flags, therefore the easiest way to do this is to set the ``PIP_INDEX_URL`` environment variable: diff --git a/docs/index.rst b/docs/index.rst index 8112f95e..00063816 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,7 +39,7 @@ tox is a generic virtual environment management and test command line tool you c * checking your package builds and installs correctly under different environments (such as different Python implementations, versions or installation dependencies), * running your tests in each of the environments with the test tool of choice, -* acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and +* acting as a frontend to continuous integration servers, greatly reducing boilerplate and merging CI and shell-based testing. Useful links diff --git a/src/new.md b/src/new.md deleted file mode 100644 index ea6da6ea..00000000 --- a/src/new.md +++ /dev/null @@ -1,93 +0,0 @@ -# What's new - -## External facing - -0. `Python 3.6+` only. -1. Lazy configuration - everything is materialized only when needed (don't ever generate data that will not be used - - general speed improvement) -2. built-in wheel build support - no longer generates sdist only -3. library dependency changes are now detected (no longer need to recreate tox-env when adding a new dependency to your - library) - use PEP-517 metadata generation to acquire these -4. CLI arguments rewrite - all defaults now are override-able either via global ini, or env var -5. allow overriding all configuration values from the cli -6. tox now supports sub-commands - still defaults to run sequential the envs (we plan to add additional commands later - - e.g. configuration validation): - - the list envs has migrated to the `list` sub-command from -a (`l` shortcut) - - the show config has migrated to the `config` sub-command form `--showconfig` (`c` shortcut) - - the run parallel has migrated to `run-parallel` sub-command form `-p` (`p` shortcut) - - the run sequential has migrated to `run` sub-command form other commands (`r` shortcut) -7. while executing subprocess calls the standard error no longer gets forwarded to the standard output but correctly to - the standard error (previously this was only true for non captured commands) -8. `basepython` is now a list, the first successfully detected python will be used to generate python environment - -## Internal - -0. `Python 3.6+` only with type annotated code. -1. Separate core configuration concepts from the ini system (to allow introduction of new configuration) -2. so long `py` my good old friend, use `pathlib` always -3. Introduce the executor concept - replaces action, generalize to avoid ease of replacement with -4. Generalize tox environment concept to make it python agnostic -5. Separate the packaging environments versus run environments -6. Package environments are tied directly to run environments (multiple run environments may share the same packaging - environment) -7. Use the logging framework to log - drop our custom reporter - default log level is `INFO` -8. rewrite the internal cache log (log more, structured, phased) - -```json -{ - "ToxEnv": { - "name": "py37", - "type": "VirtualEnvRunner" - }, - "Python": { - "version_info": [3, 7, 4, "final", 0], - "executable": "/Users/bgabor8/git/github/tox/.tox/dev/bin/python" - }, - "PythonRun": { - "deps": ["pip==19.2.1"], - "package_deps": [ - "packaging>=14", - "pluggy<1,>=0.12.0", - "appdirs<2,>=1.4.3", - "virtualenv", - "importlib-metadata<1,>=0.12; python_version < \"3.8\"", - "freezegun<1,>=0.3.11", - "pytest<6,>=4.0.0", - "pytest-cov<3,>=2.5.1", - "pytest-mock<2,>=1.10.0" - ] - } -} -``` - -```json -{ - "ToxEnv": { - "name": ".package", - "type": "Pep517VirtualEnvPackageWheel" - }, - "Python": { - "version_info": [3, 7, 4, "final", 0], - "executable": "/Users/bgabor8/git/github/tox/.tox/dev/bin/python" - }, - "PythonPackage": { - "requires": ["setuptools >= 40.0.4", "setuptools_scm >= 2.0.0, <4", "wheel >= 0.29.0"], - "build-requires": [] - } -} -``` - -## TODO - -- Make sure we're config compliant with tox 3 (excluding deprecated features) - CLI compliant is best effort -- support for `tox.py` - inline configuration/plugins -- Rewrite documentation (generate configuration from code) - -## Validate rewrite - -- provide a pre-commit env generator plugin -- provide a sphinx doc env generator plugin -- provide a tox environment that uses Docker images instead of virtual environments (this will validate the internal - refactor) -- migrate some popular tox plugins to the new system (`tox-travis` + `tox-pipenv` + `tox-conda` + `tox-pyenv` + - `tox-current-env`) diff --git a/src/tox/config/sets.py b/src/tox/config/sets.py index a7905b04..c87701f8 100644 --- a/src/tox/config/sets.py +++ b/src/tox/config/sets.py @@ -199,7 +199,7 @@ class CoreConfigSet(ConfigSet): self.add_config( keys=["temp_dir"], of_type=Path, - default=lambda conf, _: cast(Path, self["tox_root"]) / ".temp", # noqa: U100, U101 + default=lambda conf, _: cast(Path, self["tox_root"]) / ".tmp", # noqa: U100, U101 desc="temporary directory cleaned at start", ) |