github.com_fedora-python_to.../README.rst

===============
tox-current-env
===============
---------------------------------------------------------------------------------------
`tox <https://tox.readthedocs.io/>`_  plugin to run tests in current Python environment
---------------------------------------------------------------------------------------

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 <https://fedoralovespython.org/>`_'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 <https://src.fedoraproject.org/rpms/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 <https://github.com/fedora-python/tox-current-env>`_
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 <https://docs.python.org/3/using/cmdline.html>`_ 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 <https://github.com/fedora-python/tox-current-env>`_ repository.
You can use the `issue tracker <https://github.com/fedora-python/tox-current-env/issues>`_  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 <https://github.com/fedora-python/tox-current-env/blob/master/LICENSE>`_ file.


Code of Conduct
---------------

The ``tox-current-env`` project follows the `Fedora's Code of Conduct <https://docs.fedoraproject.org/en-US/project/code-of-conduct/>`_.
Add documentation 2019-07-22 14:31:38 +02:00			`===============`
Initial commit 2019-07-17 13:54:09 +02:00			`tox-current-env`
			`===============`
Add documentation 2019-07-22 14:31:38 +02:00			`---------------------------------------------------------------------------------------`
			`tox <https://tox.readthedocs.io/>`_ plugin to run tests in current Python environment
			`---------------------------------------------------------------------------------------`

			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 <https://fedoralovespython.org/>`_'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 <https://src.fedoraproject.org/rpms/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 <https://github.com/fedora-python/tox-current-env>`_
			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 <https://docs.python.org/3/using/cmdline.html>`_ 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 <https://github.com/fedora-python/tox-current-env>`_ repository.
			You can use the `issue tracker <https://github.com/fedora-python/tox-current-env/issues>`_ 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 <https://github.com/fedora-python/tox-current-env/blob/master/LICENSE>`_ file.


			`Code of Conduct`
			`---------------`
Initial commit 2019-07-17 13:54:09 +02:00
Add documentation 2019-07-22 14:31:38 +02:00			The ``tox-current-env`` project follows the `Fedora's Code of Conduct <https://docs.fedoraproject.org/en-US/project/code-of-conduct/>`_.