chore: annotate parser type_ arg as TypeAnnotation (#302)

## Summary

Fixes #301

Annotates the `type_` parameter on `list_parser`, `set_parser`,
`tuple_parser`, `dict_parser`, and `_get_parser` with
`fgpyo.util.types.TypeAnnotation` — the existing alias for the union of
runtime objects (`type | typing._GenericAlias | UnionType |
types.GenericAlias`) these parsers receive (`list[int]`, `int | None`,
`Literal["a", "b"]`, etc.). `TypeAlias` is the marker for declaring
aliases (`Foo: TypeAlias = ...`), so `TypeAnnotation` is the better fit
at this position.

**Annotation-only — runtime behavior is unchanged**, and the four public
parser entry points keep the same dispatch logic and return types.
Callers passing the kinds of annotation objects already exercised by
`tests/fgpyo/util/test_inspect.py` are unaffected.

With the more specific annotation in place, mypy can now check these
signatures meaningfully. That lets us drop five `# type:
ignore[comparison-overlap]` comments on the `typing.get_origin(...) is
list/set/tuple/dict/Literal` branches, and remove a vestigial `parser:
partial[type_]` forward declaration. A few internal calls (dict lookup
keyed by `type_`, `partial(type_)` in the constructor branches, and
calls into helpers in `types.py` that still take `Type[UnionType]` /
`Type[LiteralType]`) get narrow `# type: ignore[...]` comments — these
paths are runtime-safe today, and widening the `types.py` helper
signatures would let the ignores collapse together in a follow-up.

## Test plan

- \`uv run poe fix-and-check-all\` is clean (ruff, mypy, 842 pytest, 17
doctests).
- No new tests — the four public parsers' dispatch paths are already
covered in \`tests/fgpyo/util/test_inspect.py\`.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: msto

fgpyo/util/inspect.py

@@ -10,7 +10,6 @@
 from dataclasses import is_dataclass as is_dataclasses_class
 from enum import Enum
 from functools import partial
-from pathlib import PurePath
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import ClassVar
@@ -21,6 +20,7 @@
 from typing import TypeVar
 
 import fgpyo.util.types as types
+from fgpyo.util.types import TypeAnnotation
 
 attr: python_types.ModuleType | None
 MISSING: frozenset[Any]
@@ -150,7 +150,7 @@ def split_at_given_level(
 
 
 def list_parser(
-    cls: type, type_: TypeAlias, parsers: dict[type, Callable[[str], Any]] | None = None
+    cls: type, type_: TypeAnnotation, parsers: dict[type, Callable[[str], Any]] | None = None
 ) -> partial:
     """
     Returns a function that parses a "stringified" list into a `List` of the correct type.
@@ -179,7 +179,7 @@ def list_parser(
 
 
 def set_parser(
-    cls: type, type_: TypeAlias, parsers: dict[type, Callable[[str], Any]] | None = None
+    cls: type, type_: TypeAnnotation, parsers: dict[type, Callable[[str], Any]] | None = None
 ) -> partial:
     """
     Returns a function that parses a stringified set into a `Set` of the correct type.
@@ -210,7 +210,7 @@ def set_parser(
 
 
 def tuple_parser(
-    cls: type, type_: TypeAlias, parsers: dict[type, Callable[[str], Any]] | None = None
+    cls: type, type_: TypeAnnotation, parsers: dict[type, Callable[[str], Any]] | None = None
 ) -> partial:
     """
     Returns a function that parses a stringified tuple into a `Tuple` of the correct type.
@@ -254,7 +254,7 @@ def tuple_parse(tuple_string: str) -> tuple[Any, ...]:
 
 
 def dict_parser(
-    cls: type, type_: TypeAlias, parsers: dict[type, Callable[[str], Any]] | None = None
+    cls: type, type_: TypeAnnotation, parsers: dict[type, Callable[[str], Any]] | None = None
 ) -> partial:
     """
     Returns a function that parses a stringified dict into a `Dict` of the correct type.
@@ -307,7 +307,7 @@ def dict_parse(dict_string: str) -> dict[Any, Any]:
 
 
 def _get_parser(  # noqa: C901
-    cls: type[Any], type_: TypeAlias, parsers: dict[type, Callable[[str], Any]] | None = None
+    cls: type[Any], type_: TypeAnnotation, parsers: dict[type, Callable[[str], Any]] | None = None
 ) -> partial:
     """
     Attempts to find a parser for a provided type.
@@ -319,7 +319,6 @@ def _get_parser(  # noqa: C901
         parsers: an optional mapping from type to the function to use for parsing that type (allows
             for parsing of more complex types)
     """
-    parser: partial[type_]
     if parsers is None:
         parsers = cls._parsers()
 
@@ -328,13 +327,9 @@ def get_parser() -> partial:  # noqa: C901
         nonlocal type_
         nonlocal parsers
         try:
-            return functools.partial(parsers[type_])
+            return functools.partial(parsers[type_])  # type: ignore[index]
         except KeyError as ex:
-            if (
-                type_ in [str, int, float]
-                or isinstance(type_, type)
-                and issubclass(type_, PurePath)
-            ):
+            if types.is_known_str_constructible(type_):
                 return functools.partial(type_)
             elif type_ is bool:
                 return functools.partial(types.parse_bool)
@@ -346,13 +341,13 @@ def get_parser() -> partial:  # noqa: C901
                 raise ValueError("Unable to parse set (try typing.Set[type])") from ex
             elif type_ is dict:
                 raise ValueError("Unable to parse dict (try typing.Mapping[type])") from ex
-            elif typing.get_origin(type_) is list:  # type: ignore[comparison-overlap]
+            elif typing.get_origin(type_) is list:
                 return list_parser(cls, type_, parsers)
-            elif typing.get_origin(type_) is set:  # type: ignore[comparison-overlap]
+            elif typing.get_origin(type_) is set:
                 return set_parser(cls, type_, parsers)
-            elif typing.get_origin(type_) is tuple:  # type: ignore[comparison-overlap]
+            elif typing.get_origin(type_) is tuple:
                 return tuple_parser(cls, type_, parsers)
-            elif typing.get_origin(type_) is dict:  # type: ignore[comparison-overlap]
+            elif typing.get_origin(type_) is dict:
                 return dict_parser(cls, type_, parsers)
             elif isinstance(type_, type) and issubclass(type_, Enum):
                 return types.make_enum_parser(type_)
@@ -365,7 +360,7 @@ def get_parser() -> partial:  # noqa: C901
                     union=type_,
                     parsers=[_get_parser(cls, arg, parsers) for arg in typing.get_args(type_)],
                 )
-            elif typing.get_origin(type_) is Literal:  # type: ignore[comparison-overlap]
+            elif typing.get_origin(type_) is Literal:
                 return types.make_literal_parser(
                     type_,
                     [_get_parser(cls, type(arg), parsers) for arg in typing.get_args(type_)],

fgpyo/util/types.py

@@ -8,6 +8,7 @@
 from collections.abc import Sequence
 from enum import Enum
 from functools import partial
+from pathlib import PurePath
 from types import UnionType
 from typing import Literal
 from typing import TypeAlias
@@ -25,6 +26,21 @@
 T = TypeVar("T")
 
 
+# NB: since `_GenericAlias` is a private attribute of the `typing` module, mypy doesn't find it
+TypeAnnotation: TypeAlias = type | typing._GenericAlias | UnionType | types.GenericAlias  # type: ignore[name-defined]
+"""
+A function parameter's type annotation may be any of the following:
+    1) `type`, when declaring any of the built-in Python types
+    2) `typing._GenericAlias`, when declaring generic collection types or union types using pre-PEP
+        585 and pre-PEP 604 syntax (e.g. `List[int]`, `Optional[int]`, or `Union[int, None]`)
+    3) `types.UnionType`, when declaring union types using PEP604 syntax (e.g. `int | None`)
+    4) `types.GenericAlias`, when declaring generic collection types using PEP 585 syntax (e.g.
+       `list[int]`)
+`types.GenericAlias` is a subclass of `type`, but `typing._GenericAlias` and `types.UnionType` are
+not and must be considered explicitly.
+"""
+
+
 class InspectException(Exception):  # noqa: N818
     """Raised when type inspection or parsing fails."""
 
@@ -64,40 +80,28 @@ def make_enum_parser(enum: type[EnumType]) -> partial:
     return partial(_make_enum_parser_worker, enum)
 
 
-def is_constructible_from_str(type_: type) -> bool:
-    """Returns true if the provided type can be constructed from a string."""
+def is_known_str_constructible(type_: TypeAnnotation) -> TypeGuard[type]:
+    """
+    Returns true if `type_` is one of the built-in types known to be constructible from a str.
+
+    Complements `is_constructible_from_str`, which detects str-constructibility via constructor
+    signature inspection. This predicate covers types whose constructors aren't annotated for
+    introspection (e.g. `int`, `str`, `float`) or whose subclasses don't all share an annotation
+    (e.g. `PurePath`).
+    """
+    return isinstance(type_, type) and (type_ in (str, int, float) or issubclass(type_, PurePath))
+
+
+def is_constructible_from_str(type_: TypeAnnotation) -> TypeGuard[type]:
+    """Returns true if the provided type is a class constructible from a single str argument."""
+    if not isinstance(type_, type):
+        return False
     try:
         sig = inspect.signature(type_)
         ((argname, _),) = sig.bind(object()).arguments.items()
-    except TypeError:  # Can be raised by signature() or Signature.bind().
+    except (TypeError, ValueError):
         return False
-    except ValueError:
-        # Can be raised for classes, if the relevant info is in `__init__`.
-        if not isinstance(type_, type):
-            raise
-    else:
-        if sig.parameters[argname].annotation is str:
-            return True
-    # FIXME
-    # if isinstance(type_, type):
-    #     # signature() first checks __new__, if it is present.
-    #     return _is_constructible_from_str(type_.__init__(object(), type_))
-    return False
-
-
-# NB: since `_GenericAlias` is a private attribute of the `typing` module, mypy doesn't find it
-TypeAnnotation: TypeAlias = type | typing._GenericAlias | UnionType | types.GenericAlias  # type: ignore[name-defined]
-"""
-A function parameter's type annotation may be any of the following:
-    1) `type`, when declaring any of the built-in Python types
-    2) `typing._GenericAlias`, when declaring generic collection types or union types using pre-PEP
-        585 and pre-PEP 604 syntax (e.g. `List[int]`, `Optional[int]`, or `Union[int, None]`)
-    3) `types.UnionType`, when declaring union types using PEP604 syntax (e.g. `int | None`)
-    4) `types.GenericAlias`, when declaring generic collection types using PEP 585 syntax (e.g.
-       `list[int]`)
-`types.GenericAlias` is a subclass of `type`, but `typing._GenericAlias` and `types.UnionType` are
-not and must be considered explicitly.
-"""
+    return sig.parameters[argname].annotation is str
 
 
 def _is_optional(dtype: TypeAnnotation) -> bool: