Package: tox-current-env
Thetox-current-envplugin adds these options:tox--current-envRuns the tox testenv’scommandsin the current Python environment
(that is, the environment wheretoxis invoked from and installed in).
Unlike regulartoxinvocation, this installs no dependencies declared indeps.
An attempt to run this with a Python version that doesn’t match will fail
(iftoxis invoked from an Python 3.7 environment, any non 3.7 testenv will fail).tox--print-deps-to=FILEInstead of running anycommands, simply prints thedeclared dependenciesindepsto the specifiedFILE.
This is useful for preparing the current environment fortox--current-env.
Use-forFILEto print to standard output.tox--print-extras-to=FILEInstead of running anycommands, simply prints the names of thedeclared extrasinextrasto the specifiedFILE.
This is useful for preparing the current environment fortox--current-env.
Use-forFILEto print to standard output.It is possible to use the two printing options together, as long as theFILEis different.Invokingtoxwithout any of the above options should behave as regulartoxinvocation without this plugin.
Any deviation from this behavior is considered a bug.The plugin disablestox’s wayof providing a testing environment,
but assumes that you supply one insome other way.
Always runtoxwith this plugin in a fresh isolated environment,
such as Python virtualenv, Linux container or chroot.
See other caveats below.MotivationObviously,toxwas created to run tests in isolated Python virtual environments.
The--current-envflag totally defeats the purpose oftox.
Why would anybody do that, you might ask?Well, it turns out thattoxbecame too popular and gained another purpose.The Python ecosystem now has formalspecificationsfor many pieces of package metadata like versions or dependencies.
However, there is no standardization yet for declaringtest dependenciesorrunning tests.
The most popular de-facto standard for that today istox,
and we expect a future standard to evolve fromtox.ini.
This plugin lets us usetox’s dependency lists and testing commands for environments other than Python venvs.We hope this plugin will enable community best practices aroundtoxconfiguration
to grow to better accomodate non-virtualenv environments in general – for example,
Linux distros, Conda, or containers.Specifically, this plugin was created forFedora’s needs.
When we package Python software as RPM packages, we try to run the project’s test suite during package build.
However, we need to test if the software works integrated into Fedora,
not with packages downloaded from PyPI into a fresh environment.
By running the tests incurrent environment, we can achieve that.If you are interested in the RPM packaging part of this,
see Fedora’s%pyproject RPM macros.InstallationInstall this viapip:$python-mpipinstalltox-current-envOr install the development version by cloningthe git repositoryandpip-installing locally:$gitclonehttps://github.com/fedora-python/tox-current-env$cdtox-current-env$python-mpipinstall-e.UsageWhen the plugin is installed,
usetoxwith--current-env,--print-deps-toor--print-extras-toand all the other options as usual.
Assuming yourtoxis installed on Python 3.7:$tox-epy37--current-envpy37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
py37 installed: ...list of packages from the current environment...
py37 run-test-pre: PYTHONHASHSEED='3333333333'
py37 run-test: commands...
...runs tests in current environment's Python...
___________________________________ summary ____________________________________
  py37: commands succeeded
  congratulations :)Attempting to run thepy36environment’s test will fail:$tox-epy36--current-envpy36 create: /home/pythonista/projects/holy-grail/tests/.tox/py36
ERROR: InterpreterMismatch: tox_current_env: interpreter versions do not match:
    in current env: (3, 7, 4, 'final', 0)
    requested: (3, 6, 9, 'final', 0)
___________________________________ summary ____________________________________
ERROR:  py36: InterpreterMismatch: tox_current_env: interpreter versions do not match:
    in current env: (3, 7, 4, 'final', 0)
    requested: (3, 6, 9, 'final', 0)To get list of test dependencies, run:$tox-epy37--print-deps-to-py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
py37 installed: ...you can see almost anything here...
py37 run-test-pre: PYTHONHASHSEED='3333333333'
dep1
dep2
...
___________________________________ summary ____________________________________
  py37: commands succeeded
  congratulations :)To get a list of names of extras, run:$tox-epy37--print-extras-to-py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
py37 installed: ...you can see almost anything here...
py37 run-test-pre: PYTHONHASHSEED='3333333333'
extra1
extra2
...
___________________________________ summary ____________________________________
  py37: commands succeeded
  congratulations :)Caveats, warnings and limitationstox 4The plugin is available also for tox 4. Differences in behavior between tox 3 and 4 are these:--recreateis no longer needed when you switch from the plugin back to standard tox.
Tox detects it and handles the recreation automatically.The plugin does not check the requested Python version nor the environment name.
If you let it run for multiple environments they’ll all use the same Python.Deprecated--print-deps-onlyoption is no longer available.Use an isolated environmentRunning (especially third party software’s) tests in your system Python environment is dangerous.
Always use this plugin in an isolated environment,
such as a Linux container, virtual machine or chroot.
You have been warned.Do not rely on virtualenv detailsIn order to support thepythoncommand in thecommandssection,
the current environment invocation oftoxcreates a fake virtual environment
that just has a symbolic link to the Python executable.
The link is namedpythoneven if the real interpreter’s name is different
(such aspython3.7orpypy).
Any other commands are not linked anywhere and it is the users’ responsibility
to make sure such commands are in$PATHand use the correct Python.
This can lead to slightly different results of tests than invoking them directly,
especially if you have assumptions aboutsys.executableor other commands
in your tests.As a specific example, tests should invokepython-mpytestrather than assuming
thepytestcommand is present and uses the correct version of Python.Don’t mix current-env and regular tox runstox caches the virtualenvs it creates, and doesn’t distinguish between
regular virtualenvs and--current-env.
Don’t mixtox--current-env,tox--print-deps-toortox--print-extras-toruns and regulartoxruns (without the flags provided by this plugin).
If you ever need to do this, use tox’s--recreate/-rflag to clear the cache.The plugin should abort with a meaningful error message if this is detected,
but in some corner cases (such as runningtox--current-env,
forcefully killing it before it finished, uninstalling the plugin,
and runningtox), you will get undefined results
(such as installing packages from PyPI into your current environment).Environment variables are passed by defaultSince 0.0.9, all Shell environment variables are passed by default when using
this plugin. Thepassenvtox configuration is set to*.
Readthe documentation for more information about passing environment variables to tox.tox provisioningThe tested projects can specify theminimal tox versionand/oradditional requiresneeded in the environment wheretoxis installed.
Normally,toxusesprovisioningwhen such requirements are not met.
It creates a virtual environment,
installs (a newer version of)toxand the missing packages
into that environment and proxies alltoxinvocations trough that.
Unfortunately, this is undesired fortox-current-env.It is possible to invoketoxwith--no-provisionto prevent the provision entirely.
When requirements are missing,toxfails instead of provisioning.
If a path is passed as a value for--no-provision,
the requirements will be serialized to the file, as JSON.The requires, if specified, are included in the
results oftox--print-deps-to.
This only works when they are installed (otherwise see the first point).The minimal tox version, if specified, is included in the results oftox--print-deps-to.
This only works when the version requirement is satisfied
(otherwise see the first point).The recommend way to handle this is:Runtox--no-provisionprovision.json--print-deps-to=...or similar.If the command fails, install requirements fromprovision.jsonto the
current environment and try again.Note that the specified requirements are likely to containother tox pluginsand many of them might interfere withtox-current-envin an undesired way.
If that is the case, the recommended way is to patch/sed such undesired plugins
out of the configuration before runningtox.Other limitations and known bugsTheinstalled:line in the output oftox--print-deps-to/tox--print-extras-toshows irrelevant output
(based on the content of the real or faked virtual environment).Regardless of anyPython flagsused in the shebang oftox,
the tests are invoked withsys.executablewithout any added flags
(unless explicitly invoked with them in thecommandssection).The current environment’s Python is tested for the major and minor version only.
Different interpreters with the same Python version (such as CPython and PyPy) are treated as equal.Only Linux is supported, with special emphasis on Fedora.
This plugin might work on other Unix-like systems,
but does not work on Microsoft Windows.This is alpha quality software.
Use it at your on your own risk.
Pull requests with improvements are welcome.Development, issues, supportThe development happens on GitHub,
at thefedora-python/tox-current-envrepository.
You can use theissue trackerthere for any discussion
or send Pull Requests.TestsIn order to run the tests, you’ll needtoxand Python from 3.6 to 3.10 installed.
The integration tests assume all of them are available.
On Fedora, you just need todnf install tox.Runtoxto invoke the tests.Running tests of this plugin with its own--current-envflag will most likely blow up.LicenseThetox-current-envproject is licensed under the so-called MIT license, full text available in theLICENSEfile.Code of ConductThetox-current-envproject follows theFedora’s Code of Conduct.