[FAQ]: The tox answer should recommend `poetry install --no-root` instead of `poetry install`

• I have searched the issues of this repo and believe that this is not a duplicate.

In the FAQ, there is a recommendation for how to use tox with Poetry. It suggests this tox.ini:

[tox]
isolated_build = true
envlist = py27, py36

[testenv]
whitelist_externals = poetry
commands =
    poetry install -v
    poetry run pytest tests/

With this configuration, when a user runs tox:

1. tox packages the project with Poetry.
2. tox creates a virtual environment.
3. tox installs the package it built, but not its dependencies (inst-nodeps).
4. tox calls poetry install, which installs the project dependencies, and then installs the project, as editable, overwriting what tox installed in step 3.
5. tox calls poetry run pytest tests which tests against the package as it exists in the working directory, not as it was packaged by Poetry.

To fix this, the recommended commands should be:

commands =
    poetry install --no-root -v
    poetry run pytest tests/

[sinoroc]

I believe Poetry should be left out of tox.ini entirely. This is the pattern I would recommend:

tox.ini

[tox]
envlist = py{36,37,38}-django{22,30}
isolated_build = True

[testenv]
# ...
deps =
    django22: Django==2.2
    django30: Django==3.0
extras =
    test
commands =
    pytest

pyproject.toml

[tool.poetry]
# ...

[tool.poetry.dependencies]
python = "^3.6"
django = "^2.2 || ^3.0"
#
pytest = { version = "^5.2", optional = true }

[tool.poetry.extras]
test = ["pytest"]

[build-system]
# ...

[sinoroc]

I was unaware that tox would build the package with Poetry via the [build-system] section of pyproject.toml. I thought it wasn’t, and that that was the reason it had to be hacked in with the pattern presently suggested in the documentation. Maybe that documentation was written at a time before tox was made aware of [build-system], when the pattern it recommends was necessary.

This is enabled by the isolated_build = true setting. This lets tox know to look into pyproject.toml’s build-system section, and delegates the build to the proper build backend, which in the case here is poetry obviously. This was always (as far as I can remember at least), clearly the case in both FAQ’s (poetry and tox), but then poetry’s FAQ muddies the water by recommending commands = poetry install, which is a step back: it destroys the work done by isolated_build.

This isolated build feature is the new standard (look up PEP 517 and PEP 518), works also with setuptools, flit, etc.

The missing element here is about the development dependencies. How to let tox know what the dev dependencies are?

This can be solved by using the extras (which is a standard, i.e. specified by a PEP), this pattern is quite common nowadays and is guaranteed to work across many different tools (not only tox, and poetry).

On the other hand, generating a requirements.txt file (not a standard, there is no PEP specification) dynamically, feels unnecessary to me. And poetry’s own dev-dependencies field is not a standard either, so tox doesn’t know how to handle it.

But again, if one wants to go all-in with poetry and use all its features (even the non standard ones), feel free. But it means that you will have to work harder to make it cooperate with other tools that do follow standards. Which could be fine, maybe there isn’t even need for tox to begin with. Just running poetry run pytest could be perfectly good, no need for more.

So my point is: in my opinion poetry’s FAQ on the topic of tox is misleading and shows a largely sub-optimal pattern.

---

I have been thinking for a while about writing a plugin for tox that would offer tox a way to automatically pick up poetry’s dev dependencies. Maybe that would put this issue to rest. Or maybe there’s already such a plugin? If you know of one, let us know.