✨ feat(plugin): type the plugin and internal API surfaces (#4014)

Author: gaborbernat

docs/changelog/4014.feature.rst

@@ -0,0 +1,14 @@
+The plugin and internal APIs now declare their types, and the code base passes ``mypy --strict`` and ``pyrefly`` next to
+``ty`` - by :user:`gaborjbernat`.
+
+- :meth:`ConfigSet.get <tox.config.sets.ConfigSet.get>` returns a configuration value after checking it against its
+  declared type, so plugins can drop ``cast`` around ``conf["key"]`` reads.
+- The :func:`tox_on_install <tox.plugin.spec.tox_on_install>` hook and :class:`Installer
+  <tox.tox_env.installer.Installer>` type their ``arguments`` as :data:`InstallArguments
+  <tox.tox_env.installer.InstallArguments>`; installer subclasses may narrow it through the new second type parameter.
+- :class:`Parsed <tox.config.cli.parser.Parsed>` declares the CLI option surface, so ``options.<name>`` reads
+  type-check.
+- :meth:`ConfigSet.add_config <tox.config.sets.ConfigSet.add_config>` accepts ``default=None`` for optional values and
+  infers the value type from callable defaults.
+- The journal, the environment cache, and execute metadata hold ``JsonValue`` content; structured ``set_env`` entries
+  match the ``SetEnvEntry`` shape.

docs/conf.py

@@ -74,7 +74,8 @@
     "packaging": ("https://packaging.pypa.io/en/latest", None),
 }
 nitpicky = True
-nitpick_ignore = []
+# a private stdlib class we cannot document, the stdlib itself has no public name for it
+nitpick_ignore = [("py:class", "argparse._ArgumentGroup")]
 linkcheck_workers = 10
 linkcheck_ignore = [
     re.escape(i)
@@ -160,7 +161,8 @@ def resolve_xref(  # ruff:ignore[too-many-arguments]
                 "tox.config.of_type.T": "typing.TypeVar",  # used by Sphinx bases
                 "tox.config.loader.api.T": "typing.TypeVar",  # used by Sphinx bases
                 "tox.config.loader.convert.T": "typing.TypeVar",  # used by Sphinx bases
-                "tox.tox_env.installer.T": "typing.TypeVar",  # used by Sphinx bases
+                "tox.tox_env.installer.EnvT_co": "typing.TypeVar",  # used by Sphinx bases
+                "tox.tox_env.installer.ArgsT": "typing.TypeVar",  # used by Sphinx bases
                 "pathlib._local.Path": "pathlib.Path",
             }
             if target in mapping:

docs/plugin/api.rst

@@ -139,6 +139,14 @@ execute
 installer
 =========
 
+.. autodata:: tox.tox_env.installer.InstallArguments
+
+.. autoclass:: tox.tox_env.python.pip.req.file.RequirementsFile
+
+.. autoclass:: tox.tox_env.python.pip.req_file.PythonDeps
+
+.. autoclass:: tox.tox_env.python.pylock.Pylock
+
 .. autoclass:: tox.tox_env.installer.Installer
     :members:
 

pyproject.toml

@@ -60,7 +60,7 @@ dependencies = [
   "python-discovery>=1.4.4",
   "tomli>=2.4; python_version<'3.11'",
   "tomli-w>=1.2",
-  "typing-extensions>=4.15; python_version<'3.11'",
+  "typing-extensions>=4.15; python_version<'3.13'",
   "virtualenv>=21.1",
 ]
 optional-dependencies.completion = [
@@ -110,7 +110,10 @@ test = [
   "wheel>=0.46.3",
 ]
 type = [
+  "mypy>=2.3",
+  "pyrefly>=1.2",
   "ty>=0.0.19",
+  "types-colorama>=0.4.15",
   "types-docutils>=0.21",
   { include-group = "docs" },
   { include-group = "release" },
@@ -146,6 +149,7 @@ release = [
 ]
 type-min = [
   "ty>=0.0.19",
+  "types-colorama>=0.4.15",
   { include-group = "test" },
 ]
 
@@ -204,6 +208,8 @@ lint.per-file-ignores."tests/**/*.py" = [
 lint.isort = { known-first-party = [
   "tox",
   "tests",
+], known-third-party = [
+  "build", # the local build artifact directory must not sway the classification
 ], required-imports = [
   "from __future__ import annotations",
 ] }
@@ -219,6 +225,19 @@ count = true
 [tool.pyproject-fmt]
 max_supported_python = "3.15"
 
+[tool.mypy]
+mypy_path = "typestubs"
+files = [ "src/tox", "tests/type_check" ]
+warn_redundant_casts = false  # ty requires casts after callable() narrowing that mypy deems redundant
+strict = true
+# re_assert publishes no stubs or py.typed marker
+overrides = [ { module = [ "re_assert" ], ignore_missing_imports = true } ]
+
+[tool.pyrefly]
+project-includes = [ "src/tox", "tests/type_check" ]
+python-platform = "linux"  # ty --python-platform all covers the other platforms; keeps pyrefly output identical on every runner
+search-path = [ "src", "typestubs" ]
+
 [tool.ty]
 src.exclude = []
 environment.extra-paths = [ "typestubs" ]

src/tox/config/cli/env_var.py

@@ -4,14 +4,17 @@
 
 import logging
 import os
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from tox.config.loader.str_convert import StrConvert
 
+if TYPE_CHECKING:
+    from types import UnionType
+
 CONVERT = StrConvert()
 
 
-def get_env_var(key: str, of_type: type[Any]) -> tuple[Any, str] | None:
+def get_env_var(key: str, of_type: type[Any] | UnionType) -> tuple[Any, str] | None:
     """Get the environment variable option.
 
     :param key: the config key requested

src/tox/config/cli/ini.py

@@ -6,14 +6,17 @@
 import os
 from configparser import ConfigParser
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from platformdirs import user_config_dir
 
 from tox.config.loader.api import ConfigLoadArgs
 from tox.config.loader.ini import IniLoader
 from tox.config.source.ini_section import CORE
 
+if TYPE_CHECKING:
+    from types import UnionType
+
 DEFAULT_CONFIG_FILE = Path(user_config_dir("tox")) / "config.ini"
 
 
@@ -25,7 +28,7 @@ def __init__(self) -> None:
         config_file = os.environ.get(self.TOX_CONFIG_FILE_ENV_VAR, None)
         self.is_env_var = config_file is not None
         self.config_file = Path(config_file if config_file is not None else DEFAULT_CONFIG_FILE)
-        self._cache: dict[tuple[str, type[Any]], Any] = {}
+        self._cache: dict[tuple[str, type[Any] | UnionType], Any] = {}
         self.has_config_file: bool | None = self.config_file.exists()
         self.ini: IniLoader | None = None
 
@@ -45,7 +48,7 @@ def _parse_config_file(self) -> None:
         if self.has_tox_section:
             self.ini = IniLoader(CORE, parser, overrides=[], core_section=CORE)
 
-    def get(self, key: str, of_type: type[Any]) -> Any:
+    def get(self, key: str, of_type: type[Any] | UnionType) -> Any:
         cache_key = key, of_type
         if cache_key in self._cache:
             result = self._cache[cache_key]
@@ -60,7 +63,7 @@ def get(self, key: str, of_type: type[Any]) -> Any:
         self._cache[cache_key] = result
         return result
 
-    def _load_key(self, key: str, of_type: type[Any]) -> Any:
+    def _load_key(self, key: str, of_type: type[Any] | UnionType) -> Any:
         if self.ini is None:  # pragma: no cover # this can only happen if we don't call __bool__ first
             return None
         args = ConfigLoadArgs(chain=[key], name=CORE.prefix, env_name=None)