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").
what:
- defaults.py: add FooterIconDict, FuroThemeOptions, FontConfig TypedDicts
- defaults.py: narrow DEFAULT_THEME_OPTIONS, DEFAULT_SPHINX_FONTS, DEFAULT_AUTODOC_OPTIONS
- sphinx_fonts/__init__.py: add FontConfig TypedDict, narrow fonts local variable
- sphinx_argparse_neo/__init__.py: add SetupDict TypedDict, narrow setup() return
- parser.py: ArgumentInfo.default/const/choices Any→object; _format_default Any→object
- compat.py: import_module return Any→types.ModuleType; add import types
- test_parser.py: match object annotation for default field and test param

Author: tony

packages/gp-sphinx/src/gp_sphinx/config.py

@@ -341,8 +341,10 @@ def merge_sphinx_config(
         remove_set = set(remove_extensions)
         ext_list = [e for e in ext_list if e not in remove_set]
 
-    # Theme options
-    merged_theme_options = copy.deepcopy(DEFAULT_THEME_OPTIONS)
+    # Theme options — start from typed defaults, then widen for arbitrary overrides.
+    # dict() conversion before deepcopy keeps the type as dict[str, Any] since
+    # FuroThemeOptions (TypedDict) is not directly assignable to dict[str, Any].
+    merged_theme_options: dict[str, t.Any] = copy.deepcopy(dict(DEFAULT_THEME_OPTIONS))
     if source_repository:
         merged_theme_options["source_repository"] = source_repository
         # Update footer icon URL

packages/gp-sphinx/src/gp_sphinx/defaults.py

@@ -19,6 +19,46 @@
 
 import typing as t
 
+FooterIconDict = t.TypedDict(
+    "FooterIconDict",
+    {"name": str, "url": str, "html": str, "class": str},
+)
+"""A footer icon entry for Furo's ``footer_icons`` theme option."""
+
+
+class FuroThemeOptions(t.TypedDict, total=False):
+    """Typed subset of Furo theme options used by gp-sphinx.
+
+    All keys are optional — pass only what you want to override.
+    """
+
+    footer_icons: list[FooterIconDict]
+    source_repository: str
+    source_branch: str
+    source_directory: str
+    light_logo: str
+    dark_logo: str
+    mask_icon: str
+
+
+class _FontConfigRequired(t.TypedDict):
+    family: str
+    package: str
+    version: str
+    weights: list[int]
+    styles: list[str]
+
+
+class FontConfig(_FontConfigRequired, total=False):
+    """A single font family configuration entry for sphinx-fonts.
+
+    Required keys: ``family``, ``package``, ``version``, ``weights``, ``styles``.
+    Optional key: ``subset`` (defaults to ``"latin"`` when omitted).
+    """
+
+    subset: str
+
+
 GITHUB_SVG_ICON: str = (
     '<svg stroke="currentColor" fill="currentColor" stroke-width="0"'
     ' viewBox="0 0 16 16">'
@@ -65,7 +105,7 @@
 DEFAULT_THEME: str = "sphinx-gptheme"
 """Default Sphinx HTML theme (Furo child theme bundled in this package)."""
 
-DEFAULT_THEME_OPTIONS: dict[str, t.Any] = {
+DEFAULT_THEME_OPTIONS: FuroThemeOptions = {
     "footer_icons": [
         {
             "name": "GitHub",
@@ -168,7 +208,7 @@
 6
 """
 
-DEFAULT_SPHINX_FONTS: list[dict[str, t.Any]] = [
+DEFAULT_SPHINX_FONTS: list[FontConfig] = [
     {
         "family": "IBM Plex Sans",
         "package": "@fontsource/ibm-plex-sans",
@@ -269,7 +309,7 @@
 DEFAULT_COPYBUTTON_REMOVE_PROMPTS: bool = True
 """Whether sphinx-copybutton should strip prompts when copying."""
 
-DEFAULT_AUTODOC_OPTIONS: dict[str, t.Any] = {
+DEFAULT_AUTODOC_OPTIONS: dict[str, bool | str] = {
     "undoc-members": True,
     "members": True,
     "private-members": True,

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

@@ -46,7 +46,15 @@
 __version__ = "0.0.1a0"
 
 
-def setup(app: Sphinx) -> dict[str, t.Any]:
+class SetupDict(t.TypedDict):
+    """Return type for Sphinx extension setup()."""
+
+    version: str
+    parallel_read_safe: bool
+    parallel_write_safe: bool
+
+
+def setup(app: Sphinx) -> SetupDict:
     """Register the argparse directive and configuration options.
 
     Parameters
@@ -56,7 +64,7 @@ def setup(app: Sphinx) -> dict[str, t.Any]:
 
     Returns
     -------
-    dict[str, t.Any]
+    SetupDict
         Extension metadata.
     """
     # Configuration options

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

@@ -13,6 +13,7 @@
 import contextlib
 import importlib
 import sys
+import types
 import typing as t
 
 if t.TYPE_CHECKING:
@@ -131,7 +132,7 @@ def mock_imports(modules: list[str]) -> Iterator[None]:
             del sys.modules[name]
 
 
-def import_module(module_name: str) -> t.Any:
+def import_module(module_name: str) -> types.ModuleType:
     """Import a module by name.
 
     Parameters
@@ -141,7 +142,7 @@ def import_module(module_name: str) -> t.Any:
 
     Returns
     -------
-    t.Any
+    types.ModuleType
         The imported module.
 
     Raises

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

@@ -9,7 +9,6 @@
 
 import argparse
 import dataclasses
-import typing as t
 
 from sphinx_argparse_neo.utils import strip_ansi
 
@@ -45,15 +44,15 @@ class ArgumentInfo:
 
     names: list[str]
     help: str | None
-    default: t.Any
+    default: object
     default_string: str | None
-    choices: list[t.Any] | None
+    choices: list[object] | None
     required: bool
     metavar: str | None
     nargs: str | int | None
     action: str
     type_name: str | None
-    const: t.Any
+    const: object
     dest: str
 
     @property
@@ -185,12 +184,12 @@ class ParserInfo:
     subcommand_dest: str | None
 
 
-def _format_default(default: t.Any) -> str | None:
+def _format_default(default: object) -> str | None:
     """Format a default value for display.
 
     Parameters
     ----------
-    default : t.Any
+    default : object
         The default value to format.
 
     Returns

packages/sphinx-fonts/src/sphinx_fonts/__init__.py

@@ -40,6 +40,24 @@ class SetupDict(t.TypedDict):
     parallel_write_safe: bool
 
 
+class _FontConfigRequired(t.TypedDict):
+    family: str
+    package: str
+    version: str
+    weights: list[int]
+    styles: list[str]
+
+
+class FontConfig(_FontConfigRequired, total=False):
+    """A single font family configuration entry.
+
+    Required keys: ``family``, ``package``, ``version``, ``weights``, ``styles``.
+    Optional key: ``subset`` (defaults to ``"latin"`` when omitted).
+    """
+
+    subset: str
+
+
 def _cache_dir() -> pathlib.Path:
     """Return the local font cache directory.
 
@@ -140,7 +158,7 @@ def _on_builder_inited(app: Sphinx) -> None:
     if app.builder.format != "html":
         return
 
-    fonts: list[dict[str, t.Any]] = app.config.sphinx_fonts
+    fonts: list[FontConfig] = app.config.sphinx_fonts
     variables: dict[str, str] = app.config.sphinx_font_css_variables
     if not fonts:
         return

tests/ext/argparse_neo/test_parser.py

@@ -25,7 +25,7 @@ class FormatDefaultFixture(t.NamedTuple):
     """Test fixture for _format_default function."""
 
     test_id: str
-    default: t.Any
+    default: object
     expected: str | None
 
 
@@ -83,7 +83,7 @@ class FormatDefaultFixture(t.NamedTuple):
     FORMAT_DEFAULT_FIXTURES,
     ids=[f.test_id for f in FORMAT_DEFAULT_FIXTURES],
 )
-def test_format_default(test_id: str, default: t.Any, expected: str | None) -> None:
+def test_format_default(test_id: str, default: object, expected: str | None) -> None:
     """Test default value formatting."""
     assert _format_default(default) == expected