python-introspect 0.1.5__tar.gz → 0.1.6__tar.gz

{python_introspect-0.1.5/src/python_introspect.egg-info → python_introspect-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.5
+Version: 0.1.6
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -20,6 +20,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: annotated-types>=0.7.0
 Requires-Dist: metaclass-registry>=0.1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

{python_introspect-0.1.5 → python_introspect-0.1.6}/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",
 ]
 

{python_introspect-0.1.5 → python_introspect-0.1.6}/src/python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     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 @@ from .enableable import (
     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 @@ __all__ = [
     "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",
 ]

python_introspect-0.1.6/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]

python_introspect-0.1.6/src/python_introspect/dataclass_projection.py

@@ -0,0 +1,269 @@
+"""Dataclass construction and projection derived from declared annotations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import MISSING, fields, is_dataclass
+from enum import Enum
+from pathlib import Path
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    TypeVar,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .annotation_types import is_union_type
+from .validation import validate_annotated_dataclass, validate_annotation_value
+
+
+DataclassT = TypeVar("DataclassT")
+
+
+def dataclass_from_mapping(
+    target_type: type[DataclassT],
+    values: Mapping[str, object],
+) -> DataclassT:
+    """Construct one dataclass from the fields declared by its class."""
+
+    if not isinstance(target_type, type) or not is_dataclass(target_type):
+        raise TypeError(
+            "dataclass_from_mapping requires a dataclass type; "
+            f"got {target_type!r}."
+        )
+    if not isinstance(values, Mapping):
+        raise TypeError("dataclass_from_mapping requires a mapping.")
+    non_text_keys = tuple(key for key in values if not isinstance(key, str))
+    if non_text_keys:
+        raise TypeError(
+            f"{target_type.__name__} field names must be strings; "
+            f"got {non_text_keys!r}."
+        )
+
+    declared_fields = tuple(
+        declared_field for declared_field in fields(target_type) if declared_field.init
+    )
+    declared_names = {declared_field.name for declared_field in declared_fields}
+    extras = tuple(sorted(set(values) - declared_names))
+    if extras:
+        raise ValueError(
+            f"{target_type.__name__} received undeclared field(s): {', '.join(extras)}."
+        )
+
+    annotations = get_type_hints(target_type, include_extras=True)
+    constructor_values: dict[str, object] = {}
+    missing: list[str] = []
+    for declared_field in declared_fields:
+        if declared_field.name not in values:
+            if declared_field.default is MISSING and declared_field.default_factory is MISSING:
+                missing.append(declared_field.name)
+            continue
+        annotation = annotations.get(declared_field.name, declared_field.type)
+        constructor_values[declared_field.name] = _mapping_value_for_annotation(
+            annotation,
+            values[declared_field.name],
+            path=f"{target_type.__name__}.{declared_field.name}",
+        )
+    if missing:
+        raise ValueError(
+            f"{target_type.__name__} is missing required field(s): {', '.join(missing)}."
+        )
+
+    result = target_type(**constructor_values)
+    validate_annotated_dataclass(result)
+    return result
+
+
+def project_dataclass(
+    target_type: type[DataclassT],
+    source: object,
+    **overrides: object,
+) -> DataclassT:
+    """Project shared declared fields from one dataclass into another."""
+
+    if not isinstance(target_type, type) or not is_dataclass(target_type):
+        raise TypeError(
+            "project_dataclass requires a dataclass target type; "
+            f"got {target_type!r}."
+        )
+    if not is_dataclass(source) or isinstance(source, type):
+        raise TypeError("project_dataclass requires a dataclass source instance.")
+
+    target_fields = tuple(
+        declared_field for declared_field in fields(target_type) if declared_field.init
+    )
+    target_names = {declared_field.name for declared_field in target_fields}
+    invalid_overrides = tuple(sorted(set(overrides) - target_names))
+    if invalid_overrides:
+        raise ValueError(
+            f"{target_type.__name__} received undeclared override(s): "
+            f"{', '.join(invalid_overrides)}."
+        )
+
+    source_values = {
+        declared_field.name: object.__getattribute__(source, declared_field.name)
+        for declared_field in fields(source)
+    }
+    constructor_values = {
+        declared_field.name: source_values[declared_field.name]
+        for declared_field in target_fields
+        if declared_field.name in source_values
+    }
+    constructor_values.update(overrides)
+    result = target_type(**constructor_values)
+    validate_annotated_dataclass(result)
+    return result
+
+
+def _mapping_value_for_annotation(
+    annotation: object,
+    value: object,
+    *,
+    path: str,
+) -> object:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        base_type = get_args(annotation)[0]
+        converted = _mapping_value_for_annotation(base_type, value, path=path)
+        validate_annotation_value(annotation, converted, path=path)
+        return converted
+    if annotation is Any:
+        return value
+    if annotation is tuple:
+        if not isinstance(value, (list, tuple)):
+            raise TypeError(f"{path} must be an array.")
+        return tuple(value)
+    if is_union_type(annotation):
+        successes: list[object] = []
+        errors: list[Exception] = []
+        for member_type in get_args(annotation):
+            try:
+                converted = _mapping_value_for_annotation(
+                    member_type,
+                    value,
+                    path=path,
+                )
+                validate_annotation_value(member_type, converted, path=path)
+            except (TypeError, ValueError) as error:
+                errors.append(error)
+                continue
+            successes.append(converted)
+        if len(successes) == 1:
+            return successes[0]
+        exact_matches = tuple(
+            converted
+            for converted in successes
+            if type(converted) is type(value)
+        )
+        if len(exact_matches) == 1:
+            return exact_matches[0]
+        if successes:
+            raise TypeError(
+                f"{path} ambiguously matches multiple members of {annotation!r}."
+            )
+        value_errors = tuple(
+            error for error in errors if isinstance(error, ValueError)
+        )
+        if len(value_errors) == 1:
+            raise value_errors[0]
+        if value_errors:
+            details = "; ".join(str(error) for error in value_errors)
+            raise ValueError(
+                f"{path} does not match any constrained union member: {details}"
+            )
+        detail = f" Last error: {errors[-1]}" if errors else ""
+        raise TypeError(f"{path} does not match its declared union.{detail}") from (
+            errors[-1] if errors else None
+        )
+    if origin is Literal:
+        validate_annotation_value(annotation, value, path=path)
+        return value
+    if origin is tuple:
+        if not isinstance(value, (list, tuple)):
+            raise TypeError(f"{path} must be an array.")
+        member_types = get_args(annotation)
+        if not member_types:
+            return tuple(value)
+        if len(member_types) == 2 and member_types[1] is Ellipsis:
+            return tuple(
+                _mapping_value_for_annotation(
+                    member_types[0],
+                    item,
+                    path=f"{path}[{index}]",
+                )
+                for index, item in enumerate(value)
+            )
+        if member_types and len(value) != len(member_types):
+            raise ValueError(f"{path} must contain {len(member_types)} item(s); got {len(value)}.")
+        return tuple(
+            _mapping_value_for_annotation(
+                member_type,
+                item,
+                path=f"{path}[{index}]",
+            )
+            for index, (member_type, item) in enumerate(zip(member_types, value))
+        )
+    if origin is list:
+        if not isinstance(value, list):
+            raise TypeError(f"{path} must be an array.")
+        member_types = get_args(annotation)
+        if not member_types:
+            return list(value)
+        return [
+            _mapping_value_for_annotation(
+                member_types[0],
+                item,
+                path=f"{path}[{index}]",
+            )
+            for index, item in enumerate(value)
+        ]
+    if origin in {dict, Mapping}:
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{path} must be an object.")
+        member_types = get_args(annotation)
+        if len(member_types) != 2:
+            return dict(value)
+        key_type, item_type = member_types
+        return {
+            _mapping_value_for_annotation(
+                key_type,
+                key,
+                path=f"{path}.key",
+            ): _mapping_value_for_annotation(
+                item_type,
+                item,
+                path=f"{path}[{key!r}]",
+            )
+            for key, item in value.items()
+        }
+    if annotation is type(None):
+        if value is not None:
+            raise TypeError(f"{path} must be null.")
+        return None
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        if isinstance(value, annotation):
+            return value
+        try:
+            return annotation(value)
+        except ValueError as error:
+            choices = tuple(member.value for member in annotation)
+            raise ValueError(f"{path} must be one of {choices!r}; got {value!r}.") from error
+    if isinstance(annotation, type) and is_dataclass(annotation):
+        if isinstance(value, annotation):
+            return value
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{path} must be an object.")
+        return dataclass_from_mapping(annotation, value)
+    if annotation is Path:
+        if isinstance(value, Path):
+            return value
+        if not isinstance(value, str):
+            raise TypeError(f"{path} must be a path string.")
+        return Path(value)
+    if annotation is float and type(value) is int:
+        return float(value)
+    validate_annotation_value(annotation, value, path=path)
+    return value

python_introspect-0.1.6/src/python_introspect/environment_projection.py

@@ -0,0 +1,130 @@
+"""Environment overlays derived from dataclass annotations."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, fields, is_dataclass, replace
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, TypeVar, get_args, get_origin, get_type_hints
+
+from .annotation_types import is_union_type, optional_member_type
+from .validation import validate_annotated_dataclass, validate_annotation_value
+
+
+DataclassT = TypeVar("DataclassT")
+
+
+@dataclass(frozen=True, slots=True)
+class EnvironmentVariable:
+    """Bind one declared dataclass field to an environment variable."""
+
+    name: str
+    clear_on_empty: bool = False
+
+    def __post_init__(self) -> None:
+        validate_annotated_dataclass(self)
+        if not self.name:
+            raise ValueError("Environment variable names must not be empty.")
+
+
+def overlay_dataclass_from_environment(
+    base: DataclassT,
+    environment: Mapping[str, str] | None = None,
+) -> DataclassT:
+    """Overlay environment-bound fields while preserving the dataclass type."""
+
+    if not is_dataclass(base) or isinstance(base, type):
+        raise TypeError("overlay_dataclass_from_environment requires a dataclass instance.")
+    source = os.environ if environment is None else environment
+    owner_type = type(base)
+    annotations = get_type_hints(owner_type, include_extras=True)
+    replacements: dict[str, object] = {}
+    for declared_field in fields(base):
+        if not declared_field.init:
+            continue
+        annotation = annotations.get(declared_field.name, declared_field.type)
+        binding = _environment_binding(annotation)
+        if binding is None or binding.name not in source:
+            continue
+        raw_value = source[binding.name]
+        if not isinstance(raw_value, str):
+            raise TypeError(
+                f"{binding.name} must be text; got {type(raw_value).__name__}."
+            )
+        if raw_value == "":
+            if binding.clear_on_empty:
+                replacements[declared_field.name] = None
+            continue
+        replacements[declared_field.name] = _text_value_for_annotation(
+            annotation,
+            raw_value,
+            path=binding.name,
+        )
+
+    result = replace(base, **replacements)
+    validate_annotated_dataclass(result)
+    return result
+
+
+def _environment_binding(annotation: object) -> EnvironmentVariable | None:
+    if get_origin(annotation) is not Annotated:
+        return None
+    bindings = tuple(
+        metadata
+        for metadata in get_args(annotation)[1:]
+        if isinstance(metadata, EnvironmentVariable)
+    )
+    if len(bindings) > 1:
+        raise TypeError("A field cannot declare multiple environment variables.")
+    return bindings[0] if bindings else None
+
+
+def _text_value_for_annotation(
+    annotation: object,
+    value: str,
+    *,
+    path: str,
+) -> object:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        base_type = get_args(annotation)[0]
+        converted = _text_value_for_annotation(base_type, value, path=path)
+        validate_annotation_value(annotation, converted, path=path)
+        return converted
+    if is_union_type(annotation):
+        member_type = optional_member_type(annotation)
+        if member_type is None:
+            raise TypeError(
+                f"{path} cannot populate ambiguous union {annotation!r} from text."
+            )
+        return _text_value_for_annotation(member_type, value, path=path)
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        try:
+            return annotation(value)
+        except ValueError as error:
+            choices = tuple(member.value for member in annotation)
+            raise ValueError(f"{path} must be one of {choices!r}.") from error
+    if annotation is Path:
+        return Path(value)
+    if annotation is str:
+        return value
+    if annotation is bool:
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off"}:
+            return False
+        raise ValueError(f"{path} must be a boolean value.")
+    if annotation is int:
+        try:
+            return int(value)
+        except ValueError as error:
+            raise ValueError(f"{path} must be an integer.") from error
+    if annotation is float:
+        try:
+            return float(value)
+        except ValueError as error:
+            raise ValueError(f"{path} must be a number.") from error
+    raise TypeError(f"{path} cannot populate declared type {annotation!r} from text.")