Tox: Using 'python' in commands is confusing

[pytoxbot]

• Bitbucket: https://bitbucket.org/hpk42/tox/issue/305
• Originally reported by: @warsaw
• Originally created at: 2016-01-21T16:02:13.141

Another feedback from my fellow sprinters new to tox.

Very often you'll see something like this in your tox.ini:

[testenv:coverage]
basepython = python3
commands =
    python -m coverage run {[coverage]rc} -m nose -v
    python -m coverage combine {[coverage]rc}
    python -m coverage html {[coverage]rc}
    python -m coverage report -m {[coverage]rc}

The details aren't important other than what we're doing here is invoking some python interpreter to run some commands. In the commands lines we see the string "python" and while tox does the right thing by substituting basepython for that, it's confusing when people see it because they think that it's literally using /usr/bin/python (i.e. Python 2) for those commands.

I thought maybe we could use {basepython} -m blah but that doesn't work. Any thoughts on a way to make it obvious the "python" in commands is being substituted instead of actually using Python 2?

[obestwalter]

it's confusing when people see it because they think that it's literally using /usr/bin/python (i.e. Python 2) for those commands.

I am not sure if I understand the source of the confusion correctly. My own understanding is that when I say "python" in commands the executable used is the correct one in the context of my tox environment, so in the case of your example the python executable in the virtualenv that was created from the basepython. In the case of your example it would be <whatever>/.tox/coverage/bin/python which was created from the python3 basepython.

I personally would not want to change the invocation in tox.ini to something other than simply python - especially not {basepython} because that would actually be lying about what is used - as not {basepython} is called but the executable in the virtualenv that was created from {basepython}.

Alternatively we could document the behaviour more clearly (explain the concept better) or make the output more "educational" by telling the user which python is used for invocations?

[warsaw]

@obestwalter The confusion comes about because people see the python command and think it should be /usr/bin/python. I think if people clearly understood that this is the environment's virtualenv's bin/python it could help.

[RonnyPfannschmidt]

@warsaw then perhaps the documentation should spell {envpython} -m ... ?

[freddrake]

When writing my first tox.ini, I started by writing bin/python instead of python; it surprised me that that didn't work.

The documentation definitely needs to address this more clearly.