python-introspect 0.1.8__tar.gz → 0.1.9__tar.gz

{python_introspect-0.1.8/src/python_introspect.egg-info → python_introspect-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.8
+Version: 0.1.9
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT

{python_introspect-0.1.8 → python_introspect-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.8"
+version = "0.1.9"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
 requires-python = ">=3.10"

{python_introspect-0.1.8 → python_introspect-0.1.9}/src/python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.8"
+__version__ = "0.1.9"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -56,6 +56,11 @@ from .environment_projection import (
     overlay_dataclass_from_environment,
 )
 from .annotation_types import (
+    coerce_enum_member,
+    declared_enum_type,
+    enum_import_path,
+    enum_input_values,
+    enum_member_names,
     enum_member_type,
     get_enum_from_list,
     is_enum_type,
@@ -108,6 +113,11 @@ __all__ = [
     "EnvironmentVariable",
     "overlay_dataclass_from_environment",
     # Annotation type operations
+    "coerce_enum_member",
+    "declared_enum_type",
+    "enum_import_path",
+    "enum_input_values",
+    "enum_member_names",
     "enum_member_type",
     "get_enum_from_list",
     "is_enum_type",

python_introspect-0.1.9/src/python_introspect/annotation_types.py

@@ -0,0 +1,156 @@
+"""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 declared_enum_type(annotation: object) -> type[Enum] | None:
+    """Return the enum carried by transparent annotation wrappers.
+
+    Schema and transport projections need to recognise the same enum when it is
+    wrapped by ``Annotated``, ``Optional``, or a homogeneous container.  Mixed
+    unions and heterogeneous containers admit values outside that enum, so they
+    deliberately have no single declared enum owner.
+    """
+
+    resolved = resolve_annotated(annotation)
+    if is_enum_type(resolved):
+        return resolved
+
+    optional_member = optional_member_type(resolved)
+    if optional_member is not None:
+        return declared_enum_type(optional_member)
+
+    origin = get_origin(resolved)
+    members = get_args(resolved)
+    if origin in {list, set, frozenset} and len(members) == 1:
+        return declared_enum_type(members[0])
+    if origin is tuple and len(members) == 2 and members[1] is Ellipsis:
+        return declared_enum_type(members[0])
+
+    return None
+
+
+def enum_input_values(annotation: object) -> tuple[str, ...]:
+    """Return declaration-derived string inputs accepted for an enum.
+
+    String-valued members expose their value.  Members whose values are not
+    strings expose their name, which keeps JSON and command-line projections
+    unambiguous, including enums whose concrete value is ``None``.
+    """
+
+    enum_type = declared_enum_type(annotation)
+    if enum_type is None:
+        return ()
+    return tuple(
+        member.value if isinstance(member.value, str) else member.name for member in enum_type
+    )
+
+
+def enum_member_names(annotation: object) -> tuple[str, ...]:
+    """Return member names for the single enum carried by an annotation."""
+
+    enum_type = declared_enum_type(annotation)
+    if enum_type is None:
+        return ()
+    return tuple(member.name for member in enum_type)
+
+
+def enum_import_path(annotation: object) -> str | None:
+    """Return the import path of the single enum carried by an annotation."""
+
+    enum_type = declared_enum_type(annotation)
+    if enum_type is None:
+        return None
+    return f"{enum_type.__module__}.{enum_type.__qualname__}"
+
+
+def coerce_enum_member(annotation: object, value: object) -> Enum:
+    """Coerce an enum value or declared member name through its annotation."""
+
+    enum_type = declared_enum_type(annotation)
+    if enum_type is None:
+        raise TypeError(f"Annotation does not declare one enum type: {annotation!r}")
+    if isinstance(value, enum_type):
+        return value
+    for member in enum_type:
+        if value == member.value or value == member.name:
+            return member
+    raise ValueError(f"{value!r} is not a valid {enum_type.__module__}.{enum_type.__name__}")
+
+
+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.8 → python_introspect-0.1.9/src/python_introspect.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.8
+Version: 0.1.9
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT

{python_introspect-0.1.8 → python_introspect-0.1.9}/tests/test_annotation_types.py

@@ -2,6 +2,11 @@ from enum import Enum
 from typing import Annotated, Optional
 
 from python_introspect import (
+    coerce_enum_member,
+    declared_enum_type,
+    enum_import_path,
+    enum_input_values,
+    enum_member_names,
     enum_member_type,
     get_enum_from_list,
     is_list_of_enums,
@@ -18,6 +23,15 @@ class Mode(Enum):
     SECOND = "second"
 
 
+class OptionalMode(Enum):
+    ENABLED = "enabled"
+    INHERIT = None
+
+
+class OtherMode(Enum):
+    THIRD = "third"
+
+
 def test_optional_operations_derive_from_the_annotation() -> None:
     annotated = Annotated[int, "units"]
     optional = make_optional(annotated)
@@ -44,3 +58,22 @@ def test_enum_operations_derive_from_the_annotation() -> None:
     assert is_list_of_enums(list[Mode])
     assert get_enum_from_list(list[Mode]) is Mode
     assert get_enum_from_list(list[str]) is None
+
+
+def test_enum_schema_operations_follow_the_single_nested_declaration() -> None:
+    annotation = Annotated[list[Optional[Mode]], "modes"]
+
+    assert declared_enum_type(annotation) is Mode
+    assert enum_input_values(annotation) == ("first", "second")
+    assert enum_member_names(annotation) == ("FIRST", "SECOND")
+    assert enum_import_path(annotation) == f"{Mode.__module__}.{Mode.__qualname__}"
+    assert declared_enum_type(Mode | OtherMode) is None
+    assert declared_enum_type(Mode | str) is None
+    assert declared_enum_type(tuple[Mode, ...]) is Mode
+    assert declared_enum_type(tuple[Mode, str]) is None
+
+
+def test_enum_input_coercion_accepts_values_and_non_string_member_names() -> None:
+    assert coerce_enum_member(OptionalMode, "enabled") is OptionalMode.ENABLED
+    assert coerce_enum_member(Optional[OptionalMode], "INHERIT") is OptionalMode.INHERIT
+    assert enum_input_values(OptionalMode) == ("enabled", "INHERIT")

{python_introspect-0.1.8 → python_introspect-0.1.9}/tests/test_init.py

@@ -11,7 +11,7 @@ class TestPackageImports:
         """Test that __version__ is available."""
         assert hasattr(python_introspect, "__version__")
         assert isinstance(python_introspect.__version__, str)
-        assert python_introspect.__version__ == "0.1.8"
+        assert python_introspect.__version__ == "0.1.9"
 
     def test_signature_analyzer_import(self):
         """Test SignatureAnalyzer is importable."""

python_introspect-0.1.8/src/python_introspect/annotation_types.py

@@ -1,87 +0,0 @@
-"""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]