Function tox_parameters

tools/toxnox.py:27–177

r"""Decorator to create a parameter/tagging structure for a nox session function that acts to a large degree like tox's generative environments. The output is a ``nox.parametrize()`` decorator that's built up from individual ``nox.param()`` instances. :param names: names of the par

(
    names: Sequence[str],
    token_lists: Sequence[Sequence[str]],
    *,
    base_tag: str | None = None,
    filter_: Callable[..., bool] | None = None,
    always_include_in_tag: Sequence[str] | None = None,
)

def tox_parameters(
    names: Sequence[str],
    token_lists: Sequence[Sequence[str]],
    *,
    base_tag: str | None = None,
    filter_: Callable[..., bool] | None = None,
    always_include_in_tag: Sequence[str] | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    r"""Decorator to create a parameter/tagging structure for a nox session
    function that acts to a large degree like tox's generative environments.

    The output is a ``nox.parametrize()`` decorator that's built up from
    individual ``nox.param()`` instances.

    :param names: names of the parameters sent to the session function.
     These names go straight to the first argument of ``nox.parametrize()``
     and should all match argument names accepted by the decorated function
     (except for ``python``, which is optional).
    :param token_lists: a sequence of lists of values for each parameter.  a
     ``nox.param()`` will be created for the full product of these values,
     minus those filtered out using the ``filter_`` callable.   These tokens
     are used to create the args, tags, and ids of each ``nox.param()``.  The
     list of tags will be generated out including all values for a parameter
     joined by ``-``, as well as combinations that include a subset of those
     values, where the omitted elements of the tag are implicitly considered to
     match the "default" value, indicated by them being first in their
     collection (with the exception of "python", where the current python in
     use is the default). Additionally, values that start with an underscore
     are omitted from all ids and tags.   Values that refer to Python versions
     wlil be expanded to the full Python executable name when passed as
     arguments to the session function, which is currently a workaround to
     allow free-threaded python interpreters to be located.
    :param base_tag: optional tag that will be appended to all tags generated,
     e.g. if the decorator yields tags like ``python314-x86-windows``, a
     ``basetag`` value of ``all`` would yield the
     tag as ``python314-x86-windows-all``.
    :param filter\_: optional filtering function, must accept keyword arguments
     matching the names in ``names``.   Returns True or False indicating if
     a certain tag combination should be included.
    :param always_include_in_tag: list of names from ``names`` that indicate
     parameters that should always be part of all tags, and not be omitted
     as a "default"


    """

    PY_RE = re.compile(r"(?:python)?([234]\.\d+(t?))")

    def _is_py_version(token: str) -> bool:
        return bool(PY_RE.match(token))

    def _python_to_tag(token: str) -> str:
        m = PY_RE.match(token)
        if m:
            return f"py{m.group(1).replace('.', '')}"
        else:
            return token