Fix documentation and typing issues

Signed-off-by: Bernát Gábor <[email protected]>

docs/changelog/2275.removal.rst

@@ -1,3 +1,3 @@
-`tox_add_core_config` and `tox_add_env_config` now take a `state: State` argument instead of a configuration one, and
-`Config` not longer provides the `envs` property (instead users should migrate to `State.envs`) -
-by :user:`gaborbernat`.
+``tox_add_core_config`` and ``tox_add_env_config`` now take a ``state: State`` argument instead of a configuration one,
+and ``Config`` not longer provides the ``envs`` property (instead users should migrate to ``State.envs``) - by
+:user:`gaborbernat`.

docs/conf.py

@@ -139,13 +139,16 @@ def resolve_xref(
                 "tox.tox_env.installer.T": "typing.TypeVar",
                 "ToxParserT": "typing.TypeVar",
                 "_Section": "Section",
+                "ArgumentParser": "argparse.ArgumentParser",
+                "Factory": "tox.config.loader.convert.Factory",
             }
             if target in mapping:
+                if target == "Factory":
+                    type = "attr"
                 node["reftarget"] = mapping[target]
-            if target == "_Section":
-                target = "Section"
-                contnode = Text(target, target)
-
+                if target == "_Section":
+                    target = "Section"
+                    contnode = Text(target, target)
             return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
 
     app.connect("autodoc-skip-member", skip_member)

docs/plugins_api.rst

@@ -73,6 +73,9 @@ config
 .. autoclass:: tox.config.types.Command
    :members:
 
+.. autoclass:: tox.config.loader.convert.Factory
+   :members:
+
 environments
 ------------
 .. autoclass:: tox.tox_env.api.ToxEnv
@@ -136,3 +139,6 @@ session
 
 .. autoclass:: tox.session.env_select.EnvSelector
    :members:
+
+.. autoclass:: tox.tox_env.info.Info
+   :members:

src/tox/config/cli/parser.py

@@ -223,7 +223,7 @@ def _add_base_options(self) -> None:
 
     def parse_known_args(  # type: ignore[override]
         self,
-        args: Sequence[str] | None,
+        args: Sequence[str] | None = None,
         namespace: Parsed | None = None,
     ) -> tuple[Parsed, list[str]]:
         if args is None:

src/tox/report.py

@@ -94,7 +94,7 @@ def __init__(self, name: str) -> None:
         self.name: str = name
 
 
-class ToxHandler(logging.StreamHandler):
+class ToxHandler(logging.StreamHandler):  # type: ignore[type-arg] # is generic but at runtime doesn't take a type arg
     # """Controls tox output."""
 
     def __init__(self, level: int, is_colored: bool, out_err: OutErr) -> None:
@@ -217,7 +217,7 @@ def setup_report(verbosity: int, is_colored: bool) -> ToxHandler:
         logger = logging.getLogger(name)
         logger.filters.clear()
         logger.addFilter(lower_info_level)
-    out_err: OutErr = (sys.stdout, sys.stderr)  # type: ignore[arg-type,assignment]
+    out_err: OutErr = (sys.stdout, sys.stderr)  # type: ignore[assignment]
     handler = ToxHandler(level, is_colored, out_err)
     LOGGER.addHandler(handler)
 

src/tox/tox_env/info.py

@@ -11,6 +11,8 @@
 
 
 class Info:
+    """Stores metadata about the tox environment."""
+
     def __init__(self, path: Path) -> None:
         self._path = path / ".tox-info.json"
         try:
@@ -29,7 +31,14 @@ def compare(
         section: str,
         sub_section: str | None = None,
     ) -> Iterator[tuple[bool, Any | None]]:
-        """Cache"""
+        """
+        Compare new information with the existing one and update if differs.
+
+        :param value: the value stored
+        :param section: the primary key of the information
+        :param sub_section: the secondary key of the information
+        :return: a tuple where the first value is if it differs and the second is the old value
+        """
         old = self._content.get(section)
         if sub_section is not None and old is not None:
             old = old.get(sub_section)

src/tox/tox_env/python/pip/req/file.py

@@ -263,7 +263,7 @@ def _parse_line(self, line: str) -> tuple[str, Namespace]:
     def _handle_requirement_line(line: ParsedLine) -> ParsedRequirement:
         # For editable requirements, we don't support per-requirement options, so just return the parsed requirement.
         # get the options that apply to requirements
-        req_options = {}
+        req_options: dict[str, Any] = {}
         if line.is_editable:
             req_options["is_editable"] = line.is_editable
         if line.constraint:

tests/execute/local_subprocess/bad_process.py

@@ -12,7 +12,7 @@
 out = sys.stdout
 
 
-def handler(signum: signal.Signals, _: FrameType) -> None:  # noqa: U101
+def handler(signum: int, _: FrameType | None) -> None:  # noqa: U101
     _p(f"how about no signal {signum!r}")
 
 

tests/execute/local_subprocess/local_subprocess_sigint.py

@@ -37,7 +37,7 @@ def show_outcome(outcome: Outcome | None) -> None:
         print("done show outcome", file=sys.stderr)
 
 
-def handler(s: signal.Signals, f: FrameType) -> None:
+def handler(s: int, f: FrameType | None) -> None:
     logging.info(f"signal {s} at {f}")
     global interrupt_done
     if interrupt_done is False:  # pragma: no branch

tests/execute/local_subprocess/test_local_subprocess.py

@@ -187,12 +187,14 @@ def test_local_execute_basic_fail(capsys: CaptureFixture, caplog: LogCaptureFixt
     record = caplog.records[0]
     assert record.levelno == logging.CRITICAL
     assert record.msg == "exit %s (%.2f seconds) %s> %s%s"
+    assert record.args is not None
     _code, _duration, _cwd, _cmd, _metadata = record.args
     assert _code == 3
     assert _cwd == cwd
     assert _cmd == request.shell_cmd
     assert isinstance(_duration, float)
     assert _duration > 0
+    assert isinstance(_metadata, str)
     assert _metadata.startswith(" pid=")
 
 

tox.ini

@@ -55,7 +55,7 @@ description = run type check on code base
 setenv =
     {tty:MYPY_FORCE_COLOR = 1}
 deps =
-    mypy==0.910
+    mypy==0.930
     types-cachetools
     types-chardet
     types-freezegun