python-introspect 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -39,6 +39,7 @@ from .enableable import (
     is_enableable,
     mark_enableable,
 )
+from .choices import AnnotationChoices, declared_annotation_choices
 from .validation import (
     AnnotatedDataclassValidationMixin,
     AnnotationValidationError,
@@ -119,6 +120,8 @@ __all__ = [
     "overlay_non_none_dataclass",
     "validate_annotated_dataclass",
     "validate_annotation_value",
+    "AnnotationChoices",
+    "declared_annotation_choices",
     # Dataclass projection
     "dataclass_from_mapping",
     "project_dataclass",

python_introspect/annotation_types.py

@@ -5,7 +5,15 @@ from __future__ import annotations
 import sys
 import types
 from enum import Enum
-from typing import Annotated, Literal, Union, get_args, get_origin, get_type_hints
+from typing import (
+    Annotated,
+    ForwardRef,
+    Literal,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
 
 
 def resolved_class_annotations(owner: type) -> dict[str, object]:
@@ -13,6 +21,9 @@ def resolved_class_annotations(owner: type) -> dict[str, object]:
 
     Python 3.10 leaves strings inside PEP 585 aliases unresolved. Complete
     those declarations without interpreting Literal values or Annotated metadata.
+    A recursive alias such as ``V = int | list["V"]`` names itself; the inner
+    reference is left as a ``ForwardRef``, the form ``get_type_hints`` produces
+    for it on Python 3.11 and later.
     """
     annotations = get_type_hints(owner, include_extras=True)
     unresolved = set(annotations)
@@ -29,20 +40,34 @@ def resolved_class_annotations(owner: type) -> dict[str, object]:
     return annotations
 
 
-def _resolve_nested_type_strings(annotation: object, globalns: dict, localns: dict) -> object:
+def _resolve_nested_type_strings(
+    annotation: object,
+    globalns: dict,
+    localns: dict,
+    expanding: frozenset[str] = frozenset(),
+) -> object:
     if isinstance(annotation, str):
-        return _resolve_nested_type_strings(eval(annotation, globalns, localns), globalns, localns)
+        if annotation in expanding:
+            return ForwardRef(annotation)
+        return _resolve_nested_type_strings(
+            eval(annotation, globalns, localns), globalns, localns, expanding | {annotation}
+        )
     if isinstance(annotation, list):
-        resolved = [_resolve_nested_type_strings(member, globalns, localns) for member in annotation]
+        resolved = [
+            _resolve_nested_type_strings(member, globalns, localns, expanding)
+            for member in annotation
+        ]
         return annotation if all(a is b for a, b in zip(resolved, annotation)) else resolved
     origin = get_origin(annotation)
     members = get_args(annotation)
     if not members or origin is Literal:
         return annotation
     if origin is Annotated:
-        base = _resolve_nested_type_strings(members[0], globalns, localns)
+        base = _resolve_nested_type_strings(members[0], globalns, localns, expanding)
         return annotation if base is members[0] else Annotated[(base, *members[1:])]
-    resolved = tuple(_resolve_nested_type_strings(member, globalns, localns) for member in members)
+    resolved = tuple(
+        _resolve_nested_type_strings(member, globalns, localns, expanding) for member in members
+    )
     if all(member is original for member, original in zip(resolved, members)):
         return annotation
     if isinstance(annotation, types.GenericAlias):
@@ -143,9 +168,16 @@ def enum_input_values(annotation: object) -> tuple[str, ...]:
 
     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``.
+    unambiguous, including enums whose concrete value is ``None``.  A field
+    declaring :class:`~python_introspect.choices.AnnotationChoices` exposes its
+    choice labels.
     """
 
+    from .choices import declared_annotation_choices
+
+    choices = declared_annotation_choices(annotation)
+    if choices is not None:
+        return tuple(choices.label(choice) for choice in choices.choices())
     enum_type = declared_enum_type(annotation)
     if enum_type is None:
         return ()

python_introspect/choices.py

@@ -0,0 +1,65 @@
+"""Finite value sets declared as ``Annotated`` metadata."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Annotated, get_args, get_origin
+
+from .annotation_types import is_union_type
+
+
+class AnnotationChoices(ABC):
+    """``Annotated`` metadata declaring the finite values a field may hold.
+
+    The declaring package owns the choice set, which may be computed when it is
+    asked for. Validation checks each value (or each item of a sequence value)
+    against it, and form builders render the choices with their labels.
+    ``None`` is never a choice: an ``Optional`` annotation admits it separately.
+    """
+
+    @abstractmethod
+    def choices(self) -> tuple[object, ...]:
+        """Return the admissible values in display order."""
+
+    def label(self, choice: object) -> str:
+        """Return the display label for one admissible value."""
+
+        return str(choice)
+
+    def choice_for_label(self, label: str) -> object:
+        """Decode one display label back to its admissible value."""
+
+        for choice in self.choices():
+            if self.label(choice) == label:
+                return choice
+        raise ValueError(f"{label!r} is not one of {[self.label(c) for c in self.choices()]}.")
+
+
+def declared_annotation_choices(annotation: object) -> AnnotationChoices | None:
+    """Return the choice set declared on an annotation.
+
+    The metadata is found through ``Annotated``, ``Optional`` and homogeneous
+    containers, mirroring how enum declarations are recognised.
+    """
+
+    if get_origin(annotation) is Annotated:
+        base, *metadata = get_args(annotation)
+        for item in metadata:
+            if isinstance(item, AnnotationChoices):
+                return item
+        return declared_annotation_choices(base)
+    members = get_args(annotation)
+    if is_union_type(annotation):
+        found = [
+            choices
+            for member in members
+            if member is not type(None)
+            if (choices := declared_annotation_choices(member)) is not None
+        ]
+        return found[0] if len(found) == 1 else None
+    origin = get_origin(annotation)
+    if origin in {list, set, frozenset} and len(members) == 1:
+        return declared_annotation_choices(members[0])
+    if origin is tuple and len(members) == 2 and members[1] is Ellipsis:
+        return declared_annotation_choices(members[0])
+    return None

python_introspect/validation.py

@@ -19,6 +19,7 @@ from typing import (
 from annotated_types import Ge, Gt, Interval, Le, Len, Lt, MaxLen, MinLen, Predicate
 
 from .annotation_types import is_union_type, resolved_class_annotations
+from .choices import AnnotationChoices
 
 
 class AnnotationValidationError(ValueError):
@@ -146,6 +147,9 @@ def validate_annotation_value(
     if origin in {dict, Mapping}:
         _validate_mapping(annotation, value, path)
         return
+    if origin is type:
+        _validate_class_value(annotation, value, path)
+        return
     if origin is Callable:
         if not callable(value):
             raise TypeError(f"{path} must be callable; got {type(value).__name__}.")
@@ -205,6 +209,21 @@ def _validate_sequence(annotation: object, value: object, path: str) -> None:
             validate_annotation_value(members[0], item, path=f"{path}[{index}]")
 
 
+def _validate_class_value(annotation: object, value: object, path: str) -> None:
+    if not isinstance(value, type):
+        raise TypeError(f"{path} must be a class; got {type(value).__name__}.")
+    members = get_args(annotation)
+    if not members or members[0] is Any:
+        return
+    bounds = get_args(members[0]) if is_union_type(members[0]) else (members[0],)
+    if not any(isinstance(bound, type) and issubclass(value, bound) for bound in bounds):
+        raise TypeError(
+            f"{path} must be a subclass of "
+            f"{' | '.join(_annotation_label(bound) for bound in bounds)}; "
+            f"got {value.__qualname__}."
+        )
+
+
 def _validate_mapping(annotation: object, value: object, path: str) -> None:
     if not isinstance(value, Mapping):
         raise TypeError(f"{path} must be a mapping; got {type(value).__name__}.")
@@ -226,6 +245,20 @@ def _validate_constraint(metadata: object, value: object, path: str) -> None:
     """Ignore annotation metadata that does not declare a runtime constraint."""
 
 
+@_validate_constraint.register
+def _(metadata: AnnotationChoices, value: object, path: str) -> None:
+    if value is None:
+        return
+    choices = metadata.choices()
+    items = value if isinstance(value, (list, tuple, frozenset, set)) else (value,)
+    for item in items:
+        if item not in choices:
+            raise AnnotationValidationError(
+                f"{path} must hold values from "
+                f"{[metadata.label(choice) for choice in choices]}; got {item!r}."
+            )
+
+
 @_validate_constraint.register
 def _(metadata: Ge, value: object, path: str) -> None:
     if value < metadata.ge:

{python_introspect-0.2.2.dist-info → python_introspect-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.2.2
+Version: 0.2.4
 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.2.2.dist-info → python_introspect-0.2.4.dist-info}/RECORD

@@ -1,6 +1,7 @@
-python_introspect/__init__.py,sha256=IHmyKt23hfkRVeRaVD9mDuoWAG7Q7BorK-cP4B9o0Eg,3985
-python_introspect/annotation_types.py,sha256=KZDv0fUAuvVQDEj0U_cozA_31vl3MyNsOfSOcdo3aJk,7557
+python_introspect/__init__.py,sha256=gez9bqvqRza1xmWmaoT9E_s75-LgOukZzcOD-wAkTVI,4113
+python_introspect/annotation_types.py,sha256=AEo84uIUoYSqoyMM6qicyqXxiMHD2IWqytUiJybDS3o,8384
 python_introspect/callable_declaration.py,sha256=O7i0dGJP5rKWSlwfmmqlQLJwNQC_oSTngImVy3idaVE,1409
+python_introspect/choices.py,sha256=kpaFx63SYDvJkCKpXFDvkORyVtHEUnujVcvNQ6jQVN8,2415
 python_introspect/dataclass_projection.py,sha256=531PIrAunWNuQBwnZDBRpDa0Gy8iK_F6B4ThwYqOhCU,10869
 python_introspect/docstring_annotations.py,sha256=RE6AZPgz8aBEIIvUoVEHpraItZfjareKxYvuaZa1H8k,6129
 python_introspect/enableable.py,sha256=Al6t1kpqbxZIvDb70XJPYEk1WgubGiWUQySNcBcLjrY,5253
@@ -11,9 +12,9 @@ python_introspect/public_api.py,sha256=8wkxQKmnxl_46U49Dzq4XXIOqmrYQOD0S0cl9bc-Y
 python_introspect/runtime_parameter.py,sha256=Wf7S1GfnUWhkRzIvjhmoYz2WR0HT2K_MuFDcUEphmJc,3067
 python_introspect/signature_analyzer.py,sha256=DlFaxudB-dANV0FD9MmLJWdvxBKobJbtEn5n6tda2JU,60926
 python_introspect/unified_parameter_analyzer.py,sha256=Qw39mQsYDYq5zEiB6ALRoZqwQeZ4PJmlkFxpTaKkccg,12231
-python_introspect/validation.py,sha256=vj3OwJFShA2n4Zg45rXj8qghsJxDe1JhND8gkuNbfLQ,10447
-python_introspect-0.2.2.dist-info/licenses/LICENSE,sha256=xagEoeTAj1WT64RmyR3E6HH-eTGdgXN6gqPMUUt7L_Y,1070
-python_introspect-0.2.2.dist-info/METADATA,sha256=rwnVJA2UW6z5V1pznJtSjYqb0-H9_Y55ynK00qji8SE,4677
-python_introspect-0.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_introspect-0.2.2.dist-info/top_level.txt,sha256=TZq9Yj1LeXI7A96PDqf7ZbWGSB1zLlQDww0esC91bwY,18
-python_introspect-0.2.2.dist-info/RECORD,,
+python_introspect/validation.py,sha256=MpyvHhHO39SzQqWxVvQHTiAepTcjc79o8A54-YcMe94,11741
+python_introspect-0.2.4.dist-info/licenses/LICENSE,sha256=xagEoeTAj1WT64RmyR3E6HH-eTGdgXN6gqPMUUt7L_Y,1070
+python_introspect-0.2.4.dist-info/METADATA,sha256=3M7pFCMcmRPZald2Yh9ctn4VZ0RzIHmn4ZPHOIGjvb0,4677
+python_introspect-0.2.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_introspect-0.2.4.dist-info/top_level.txt,sha256=TZq9Yj1LeXI7A96PDqf7ZbWGSB1zLlQDww0esC91bwY,18
+python_introspect-0.2.4.dist-info/RECORD,,