diff --git a/README.rst b/README.rst index c59636f..9440a85 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,186 @@ +=============== tox-current-env =============== +--------------------------------------------------------------------------------------- +`tox `_ plugin to run tests in current Python environment +--------------------------------------------------------------------------------------- -... TODO ... +The ``tox-current-env`` plugin adds two options: + +``tox --current-env`` + Runs the tox testenv's ``commands`` in the current Python environment + (that is, the environment where ``tox`` is invoked from and installed in). + Unlike regular ``tox`` invocation, this installs no dependendencies declared in ``deps``. + An attempt to run this with a Python version that doesn't match will fail + (if ``tox`` is invoked from an Python 3.7 environment, any non 3.7 testenv will fail). + +``tox --print-deps-only`` + Instead of running any ``commands``, + simply prints the declared dependencies in ``deps`` to the standard output. + This is useful for preparing the current environment for the above. + +Invoking ``tox`` without any of the above options should behave as regular ``tox`` invocation without this plugin. +Any deviation from this behavior is considered a bug. + + +Motivation +---------- + +Obviously, ``tox`` was created to run tests in isolated Python virtual environments. +The ``--current-env`` flag totally defeats the purpose of ``tox``. +Why would anybody do that, you might ask. + +This plugin was created for `Fedora `_'s needs. +When we package Python software as RPM packages, we try to run the upstream test suite during package build. +However there is no standardization of declaring Python test dependencies or invoking tests. +The de-facto standard is ``tox``. +However we need to test if the software works integrated into Fedora, +not if it works with ``pip``-installed packages in an isolated environment. +By running the tests in *current environment*, we can achieve that. + +If you are interested in the RPM packaging part of this, +see Fedora's `%pyproject RPM macros `_. + + +Installation +------------ + +Install this via ``pip``: + +.. code-block:: console + + $ python -m pip install tox-current-env + +Or install the development version by cloning `the git repository `_ +and ``pip``-installing locally: + +.. code-block:: console + + $ git clone https://github.com/fedora-python/tox-current-env + $ cd tox-current-env + $ python -m pip install -e . + + +Usage +----- + +When the plugin is installed, use ``tox`` with the ``--current-env`` or `` --print-deps-only`` and all the other options as usual. Assuming your ``tox`` is installed on Python 3.7: + +.. code-block:: console + + $ tox -e py37 --current-env + py37 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 the ``py36`` environment's test will fail: + +.. code-block:: console + + $ tox -e py37 --current-env + py36 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: + +.. code-block:: console + + $ tox -e py37 --print-deps-only + 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 :) + + +Caveats, warnings and limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Running (especially third party software's) tests in your system installed Python environment is dangerous. +Always install ``tox`` and this plugin to some isolated environment, +such as Python virtualenv, Linux container or chroot. +You have been warned. + +In order to support the ``python`` command in the ``commands`` section, +the current environment invocation of ``tox`` creates a fake virtual environment +that just have a symbolic link to the Python executable. +This can lead to slightly different results of tests than invoking them directly, +especially if you have assumptions about ``sys.executable`` in your tests. +Any other commands (such as ``pytest``) are not linked anywhere +and it is the users' responsibility to make sure such commands are in ``$PATH`` and use the correct Python. + +Regardless of any `Python flags `_ used in the shebang of ``tox``, +the tests are invoked with ``sys.executable`` without any added flags +(unless explicitly invoked with them in the ``commands`` section). + +The ``installed:`` line in the output of ``tox --print-deps-only`` shows irrelevant output +(based on the content of the real or faked virtual environment). + +Running ``tox --current-env`` after regular ``tox`` +(that is without the ``--current-env`` switch) +or vice versa is not supported without the ``--recreate/-r`` flag +(``tox`` will emergency abort in that situation). +Additionally, running ``tox --current-env``, +uninstalling the ``tox-current-env`` +and running ``tox`` without the ``--recreate/-r`` flag +will most likely attempt to install packages into your current environment +and will provide further undefined results. +Being uninstalled, ``tox-current-env`` cannot longer prevent this. + +The current environment's Python is tested for the major and minor version only. +Possibly multiple different 3.X versions (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 an alpha quality software. +Use it at your on your own risk. + + +Development, issues, support +---------------------------- + +The development happens on GitHub, +at the `fedora-python/tox-current-env `_ repository. +You can use the `issue tracker `_ there for any discussion +or send Pull Requests. + + +Tests +~~~~~ + +In order to run the tests, you'll need ``tox`` and Python 3.6, 3.7 and 3.8 installed. +The integration tests assume all three are available. +On Fedora, you just need to ``dnf install tox``. + +Run ``tox`` to invoke the tests. + +Running tests of this plugin with this plugin installed and ``--current-env`` flag will most likely blow up. + + +License +------- + +The ``tox-current-env`` project is licensed under so-called MIT license, full text available in the `LICENSE `_ file. + + +Code of Conduct +--------------- + +The ``tox-current-env`` project follows the `Fedora's Code of Conduct `_. diff --git a/setup.py b/setup.py index 3927041..b79fb9d 100644 --- a/setup.py +++ b/setup.py @@ -25,6 +25,7 @@ setup( "Framework :: tox", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", + "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7",