typing(feat[typeddict]): Replace dict[str, Any] with TypedDicts, object for argparse fields

why: Eliminate imprecise Any annotations where the structure is actually known.
     TypedDicts catch key typos at type-check time; object is semantically correct
     for argparse values (any Python object, not "opts out of type checking").
     Also revealed real bug: exemplar.setup() was missing parallel_write_safe key.
what:
- directive.py: option_spec value Any→Callable[[str], Any] (matches Sphinx's OptionSpec)
- exemplar.py: setup() return dict[str, Any]→SetupDict; fix missing parallel_write_safe
- test_compat.py: create_parser/get_parser/make_parser/parser return Any→ArgumentParser
- test_renderer.py: post_process override list[Any]→list[nodes.Node] + isinstance narrowing
- test_sphinx_fonts.py: config_values middle tuple element Any→object

Author: tony

packages/sphinx-argparse-neo/src/sphinx_argparse_neo/directive.py

@@ -18,6 +18,7 @@
 
 if t.TYPE_CHECKING:
     import argparse
+    from collections.abc import Callable
 
 
 class ArgparseDirective(SphinxDirective):
@@ -66,7 +67,7 @@ class ArgparseDirective(SphinxDirective):
     required_arguments = 0
     optional_arguments = 0
 
-    option_spec: t.ClassVar[dict[str, t.Any]] = {
+    option_spec: t.ClassVar[dict[str, Callable[[str], t.Any]]] = {
         "module": directives.unchanged_required,
         "func": directives.unchanged_required,
         "prog": directives.unchanged,

packages/sphinx-argparse-neo/src/sphinx_argparse_neo/exemplar.py

@@ -117,6 +117,14 @@ def setup(app):
     from sphinx.application import Sphinx
 
 
+class SetupDict(t.TypedDict):
+    """Return type for Sphinx extension setup()."""
+
+    version: str
+    parallel_read_safe: bool
+    parallel_write_safe: bool
+
+
 @dataclasses.dataclass
 class ExemplarConfig:
     """Configuration for argparse_exemplar transformation.
@@ -1219,7 +1227,7 @@ def run(self) -> list[nodes.Node]:
         return _reorder_nodes(flattened, config=config)
 
 
-def setup(app: Sphinx) -> dict[str, t.Any]:
+def setup(app: Sphinx) -> SetupDict:
     """Register the clean argparse directive, lexers, and CLI roles.
 
     Configuration Options
@@ -1303,4 +1311,4 @@ def setup(app: Sphinx) -> dict[str, t.Any]:
 
     register_roles()
 
-    return {"version": "4.0", "parallel_read_safe": True}
+    return {"version": "4.0", "parallel_read_safe": True, "parallel_write_safe": True}

tests/ext/argparse_neo/test_compat.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
+import argparse
 import sys
-import typing as t
 
 import pytest
 
@@ -177,7 +177,7 @@ def test_get_parser_from_module_argparse() -> None:
 
     test_module = types.ModuleType("test_parser_module")
 
-    def create_parser() -> t.Any:
+    def create_parser() -> argparse.ArgumentParser:
         import argparse
 
         return argparse.ArgumentParser(prog="test")
@@ -198,7 +198,7 @@ def test_get_parser_from_module_with_mock() -> None:
 
     test_module = types.ModuleType("test_mock_parser")
 
-    def create_parser() -> t.Any:
+    def create_parser() -> argparse.ArgumentParser:
         import argparse
 
         return argparse.ArgumentParser(prog="mocked")
@@ -225,7 +225,7 @@ def test_get_parser_from_module_dotted_path() -> None:
 
     class CLI:
         @staticmethod
-        def create_parser() -> t.Any:
+        def create_parser() -> argparse.ArgumentParser:
             import argparse
 
             return argparse.ArgumentParser(prog="from_class")
@@ -261,7 +261,7 @@ def test_get_parser_from_entry_point_valid() -> None:
 
     test_module = types.ModuleType("test_entry_point")
 
-    def get_parser() -> t.Any:
+    def get_parser() -> argparse.ArgumentParser:
         import argparse
 
         return argparse.ArgumentParser(prog="entry")
@@ -292,7 +292,7 @@ def test_get_parser_from_entry_point_with_class() -> None:
 
     class Factory:
         @staticmethod
-        def parser() -> t.Any:
+        def parser() -> argparse.ArgumentParser:
             import argparse
 
             return argparse.ArgumentParser(prog="factory")
@@ -313,7 +313,7 @@ def test_get_parser_from_entry_point_with_mock() -> None:
 
     test_module = types.ModuleType("test_entry_mock")
 
-    def make_parser() -> t.Any:
+    def make_parser() -> argparse.ArgumentParser:
         import argparse
 
         return argparse.ArgumentParser(prog="with_mock")

tests/ext/argparse_neo/test_renderer.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import typing as t
 
 from docutils import nodes
 
@@ -482,18 +481,20 @@ def test_post_process_custom() -> None:
     """Test custom post_process implementation."""
 
     class CustomRenderer(ArgparseRenderer):
-        def post_process(self, result_nodes: list[t.Any]) -> list[t.Any]:
-            # Add a marker to each node
+        def post_process(self, result_nodes: list[nodes.Node]) -> list[nodes.Node]:
+            # Add a marker to each node; Element subclass supports item assignment
             for node in result_nodes:
-                node["custom_marker"] = True
+                if isinstance(node, nodes.Element):
+                    node["custom_marker"] = True
             return result_nodes
 
     renderer = CustomRenderer()
 
     from docutils import nodes as dn
 
-    input_nodes = [dn.paragraph(text="test")]
+    input_nodes: list[nodes.Node] = [dn.paragraph(text="test")]
 
     result = renderer.post_process(input_nodes)
 
+    assert isinstance(result[0], nodes.Element)
     assert result[0].get("custom_marker") is True

tests/ext/test_sphinx_fonts.py

@@ -489,7 +489,7 @@ def test_on_html_page_context_without_attrs() -> None:
 
 def test_setup_return_value() -> None:
     """Verify setup() returns correct metadata dict."""
-    config_values: list[tuple[str, t.Any, str]] = []
+    config_values: list[tuple[str, object, str]] = []
     connections: list[tuple[str, t.Any]] = []
 
     app = t.cast(
@@ -513,7 +513,7 @@ def test_setup_return_value() -> None:
 
 def test_setup_config_values() -> None:
     """Verify setup() registers all expected config values."""
-    config_values: list[tuple[str, t.Any, str]] = []
+    config_values: list[tuple[str, object, str]] = []
     connections: list[tuple[str, t.Any]] = []
 
     app = t.cast(
@@ -538,7 +538,7 @@ def test_setup_config_values() -> None:
 
 def test_setup_event_connections() -> None:
     """Verify setup() connects to builder-inited and html-page-context events."""
-    config_values: list[tuple[str, t.Any, str]] = []
+    config_values: list[tuple[str, object, str]] = []
     connections: list[tuple[str, t.Any]] = []
 
     app = t.cast(