feat: derive runtime projections from declared types

Author: trissim

docs/source/conf.py

@@ -16,7 +16,7 @@
 project = "python-introspect"
 copyright = "2025, Tristan Simas"
 author = "Tristan Simas"
-release = "0.1.5"
+release = "0.1.6"
 version = "0.1"
 
 # -- General configuration ---------------------------------------------------

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.5"
+version = "0.1.6"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,7 @@ classifiers = [
 ]
 
 dependencies = [
+    "annotated-types>=0.7.0",
     "metaclass-registry>=0.1.0",
 ]
 

src/python_introspect/__init__.py

@@ -9,7 +9,7 @@
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.5"
+__version__ = "0.1.6"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -40,6 +40,31 @@
     is_enableable,
     mark_enableable,
 )
+from .validation import (
+    AnnotationValidationError,
+    overlay_non_none_dataclass,
+    validate_annotated_dataclass,
+    validate_annotation_value,
+)
+from .dataclass_projection import (
+    dataclass_from_mapping,
+    project_dataclass,
+)
+from .environment_projection import (
+    EnvironmentVariable,
+    overlay_dataclass_from_environment,
+)
+from .annotation_types import (
+    enum_member_type,
+    get_enum_from_list,
+    is_enum_type,
+    is_list_of_enums,
+    is_union_type,
+    make_optional,
+    optional_member_type,
+    resolve_annotated,
+    resolve_optional,
+)
 
 __all__ = [
     # Version
@@ -69,4 +94,25 @@
     "Enableable",
     "is_enableable",
     "mark_enableable",
+    # Runtime annotation validation
+    "AnnotationValidationError",
+    "overlay_non_none_dataclass",
+    "validate_annotated_dataclass",
+    "validate_annotation_value",
+    # Dataclass projection
+    "dataclass_from_mapping",
+    "project_dataclass",
+    # Environment projection
+    "EnvironmentVariable",
+    "overlay_dataclass_from_environment",
+    # Annotation type operations
+    "enum_member_type",
+    "get_enum_from_list",
+    "is_enum_type",
+    "is_list_of_enums",
+    "is_union_type",
+    "make_optional",
+    "optional_member_type",
+    "resolve_annotated",
+    "resolve_optional",
 ]

src/python_introspect/annotation_types.py

@@ -0,0 +1,87 @@
+"""Generic operations derived directly from Python type annotations."""
+
+from __future__ import annotations
+
+import types
+from enum import Enum
+from typing import Annotated, Union, get_args, get_origin
+
+
+def is_union_type(annotation: object) -> bool:
+    """Return whether ``annotation`` is a typing or PEP 604 union."""
+
+    return get_origin(annotation) in {Union, types.UnionType}
+
+
+def optional_member_type(annotation: object) -> object | None:
+    """Return ``T`` only for the simple optional declaration ``T | None``."""
+
+    if not is_union_type(annotation):
+        return None
+    members = get_args(annotation)
+    if len(members) != 2 or type(None) not in members:
+        return None
+    return next(member for member in members if member is not type(None))
+
+
+def make_optional(annotation: object) -> object:
+    """Return the same declaration with ``None`` admitted exactly once."""
+
+    if is_union_type(annotation) and type(None) in get_args(annotation):
+        return annotation
+    return Union[annotation, type(None)]
+
+
+def resolve_optional(annotation: object) -> object:
+    """Resolve an optional declaration to its non-None member declaration."""
+
+    member_type = optional_member_type(annotation)
+    return annotation if member_type is None else member_type
+
+
+def resolve_annotated(annotation: object) -> object:
+    """Resolve an ``Annotated[T, ...]`` declaration to its owned type ``T``."""
+
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+    return annotation
+
+
+def is_enum_type(annotation: object) -> bool:
+    """Return whether the declaration is an enum type."""
+
+    return isinstance(annotation, type) and issubclass(annotation, Enum)
+
+
+def enum_member_type(annotation: object) -> type[Enum] | None:
+    """Return the enum type declared directly or as a simple optional."""
+
+    if is_enum_type(annotation):
+        return annotation
+    if not is_union_type(annotation):
+        return None
+    members = tuple(
+        member for member in get_args(annotation) if member is not type(None)
+    )
+    if len(members) != 1 or not is_enum_type(members[0]):
+        return None
+    return members[0]
+
+
+def is_list_of_enums(annotation: object) -> bool:
+    """Return whether the declaration is ``list[SomeEnum]``."""
+
+    members = get_args(annotation)
+    return (
+        get_origin(annotation) is list
+        and len(members) == 1
+        and is_enum_type(members[0])
+    )
+
+
+def get_enum_from_list(annotation: object) -> type[Enum] | None:
+    """Return the enum type from ``list[SomeEnum]`` when declared."""
+
+    if not is_list_of_enums(annotation):
+        return None
+    return get_args(annotation)[0]