tox hook workflow

[obestwalter]

(See #421 (comment) and the following comments for the initial discussion)

Summary: a tox run goes through distinct phases. This is implicitly explained in the documentation and becomes obvious when working a while with tox (especially when running tox -vv. Nevertheless it might help make this a bit more explicit in e.g. the documentation. It also might help in further development to have some "official" terminology for those phases. Might also help with naming of new hooks, etc.

If you look into the code there is the action class, which has reporting hooks to log start and finish of those actions. Those are phases in one respect, but don't map entirely satisfactorily to what the user might think of as phases. The actions that are reported are: packaging, getenv, finishvenv, developpkg, installpkg, envreport, runtests. They are also marked by the context in which they run, which is GLOB for global context and (some envname) for environment context (which might be one of the default environments or whatever environment the user has created).

The test run is executed in subcommand_test.

Those map vaguely onto what a tox user might think about how to organize things (and maybe where to hook into to change the behaviour), but not quite. e.g. finding the interpreter executable is not mirrored as action. I have not looked into the code in enough detail why that is.

Looking at a tox run from the outside, the phases of a test run (meaning: show help, show config or show envs not taken into account here) could be described as:

• GLOB initialization
• GLOB package build (optional)
• ENV interpreter discovery
• ENV environment creation
• ENV dependency installation (optional)
• ENV package under test installation (optional)
• ENV command execution (optional) (not atm (Regression since 2.5.0: empty commands section causes error #454) but with next release again).
• GLOB report results

[gaborbernat]

shouldn't there be another reporting phase at the end, again with GLOB scope?

[gaborbernat]

I've created a diagram of the stages, and the flow of the application:

Let me know what you think 👍

[obestwalter]

Great! Which tool did you use for that? Would it get too cuttered, if it would be mentioned which hook are called in which phase?

[gaborbernat]

used Lucid chart diagram, I can give it a try and see how it looks; you are referring to the plugin hooks, yes?

[obestwalter]

Correct: https://github.com/tox-dev/tox/blob/master/tox/hookspecs.py

[gaborbernat]

I'll take this.

[gaborbernat]

Duplicate of #867.

[obestwalter]

Normally the duplicate is the issue that was opened later 👅

[gaborbernat]

I'm actually will reopen this with a different scope: presenting the flow with hooks for plugin writers. Different audience.

[obestwalter]

I think that is a good idea. Reminds me of a talk I heard from Daniele Procida: https://www.youtube.com/watch?v=azf6yzuJt54

General idea is to always have the audience in mind and write the docs according to that. So good idea to separate that with different audiences in mind 👍

YouTube

Daniele Procida How documentation works, and how to make it work for your project PyCon 2017

"Speaker: Daniele Procida Nearly everyone (especially in the Python community) agrees that good documentation is important to the success of software project...