1"""Hook specifications for tox - see https://pluggy.readthedocs.io/"""
2import pluggy
3
4hookspec = pluggy.HookspecMarker("tox")
5
6
7@hookspec
8def tox_addoption(parser):
9    """ add command line options to the argparse-style parser object."""
10
11
12@hookspec
13def tox_configure(config):
14    """Called after command line options are parsed and ini-file has been read.
15
16    Please be aware that the config object layout may change between major tox versions.
17    """
18
19
20@hookspec(firstresult=True)
21def tox_package(session, venv):
22    """Return the package to be installed for the given venv.
23
24    Called once for every environment."""
25
26
27@hookspec(firstresult=True)
28def tox_get_python_executable(envconfig):
29    """Return a python executable for the given python base name.
30
31    The first plugin/hook which returns an executable path will determine it.
32
33    ``envconfig`` is the testenv configuration which contains
34    per-testenv configuration, notably the ``.envname`` and ``.basepython``
35    setting.
36    """
37
38
39@hookspec(firstresult=True)
40def tox_testenv_create(venv, action):
41    """Perform creation action for this venv.
42
43    Some example usage:
44
45    - To *add* behavior but still use tox's implementation to set up a
46      virtualenv, implement this hook but do not return a value (or explicitly
47      return ``None``).
48    - To *override* tox's virtualenv creation, implement this hook and return
49      a non-``None`` value.
50
51    .. note:: This api is experimental due to the unstable api of
52        :class:`tox.venv.VirtualEnv`.
53
54    .. note:: This hook uses ``firstresult=True`` (see `pluggy first result only`_) -- hooks
55        implementing this will be run until one returns non-``None``.
56
57    .. _`pluggy first result only`: https://pluggy.readthedocs.io/en/latest/#first-result-only
58    """
59
60
61@hookspec(firstresult=True)
62def tox_testenv_install_deps(venv, action):
63    """Perform install dependencies action for this venv.
64
65    Some example usage:
66
67    - To *add* behavior but still use tox's implementation to install
68      dependencies, implement this hook but do not return a value (or
69      explicitly return ``None``).  One use-case may be to install (or ensure)
70      non-python dependencies such as debian packages.
71    - To *override* tox's installation of dependencies, implement this hook
72      and return a non-``None`` value.  One use-case may be to install via
73      a different installation tool such as `pip-accel`_ or `pip-faster`_.
74
75    .. note:: This api is experimental due to the unstable api of
76        :class:`tox.venv.VirtualEnv`.
77
78    .. note:: This hook uses ``firstresult=True`` (see `pluggy first result only`_) -- hooks
79        implementing this will be run until one returns non-``None``.
80
81    .. _pip-accel: https://github.com/paylogic/pip-accel
82    .. _pip-faster: https://github.com/Yelp/venv-update
83    """
84
85
86@hookspec
87def tox_runtest_pre(venv):
88    """Perform arbitrary action before running tests for this venv.
89
90    This could be used to indicate that tests for a given venv have started, for instance.
91    """
92
93
94@hookspec(firstresult=True)
95def tox_runtest(venv, redirect):
96    """Run the tests for this venv.
97
98    .. note:: This hook uses ``firstresult=True`` (see `pluggy first result only`_) -- hooks
99        implementing this will be run until one returns non-``None``.
100    """
101
102
103@hookspec
104def tox_runtest_post(venv):
105    """Perform arbitrary action after running tests for this venv.
106
107    This could be used to have per-venv test reporting of pass/fail status.
108    """
109
110
111@hookspec(firstresult=True)
112def tox_runenvreport(venv, action):
113    """Get the installed packages and versions in this venv.
114
115    This could be used for alternative (ie non-pip) package managers, this
116    plugin should return a ``list`` of type ``str``
117    """
118
119
120@hookspec
121def tox_cleanup(session):
122    """Called just before the session is destroyed, allowing any final cleanup operation"""
123