python-introspect 0.1.10__tar.gz → 0.1.12__tar.gz

{python_introspect-0.1.10/src/python_introspect.egg-info → python_introspect-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.10
+Version: 0.1.12
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -37,7 +37,7 @@ Dynamic: license-file
 # python-introspect
 
 Extensible analysis of callable signatures, dataclass fields, type hints, and
-docstrings.
+docstrings, plus signature-derived callable declaration projection.
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://badge.fury.io/py/python-introspect.svg)](https://badge.fury.io/py/python-introspect)
@@ -66,6 +66,11 @@ for name, info in parameters.items():
 dataclass types, and instances. It returns a mapping of names to
 ``ParameterInfo`` records.
 
+Use ``callable_declaration_kwargs`` when declaration identity should omit
+keyword arguments equal to their signature defaults. The caller supplies value
+equality so array, lazy, or other framework-specific values keep their owning
+semantics.
+
 ## Extension points
 
 Use ``register_namespace_provider`` to contribute names used while resolving

{python_introspect-0.1.10 → python_introspect-0.1.12}/README.md

@@ -1,7 +1,7 @@
 # python-introspect
 
 Extensible analysis of callable signatures, dataclass fields, type hints, and
-docstrings.
+docstrings, plus signature-derived callable declaration projection.
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://badge.fury.io/py/python-introspect.svg)](https://badge.fury.io/py/python-introspect)
@@ -30,6 +30,11 @@ for name, info in parameters.items():
 dataclass types, and instances. It returns a mapping of names to
 ``ParameterInfo`` records.
 
+Use ``callable_declaration_kwargs`` when declaration identity should omit
+keyword arguments equal to their signature defaults. The caller supplies value
+equality so array, lazy, or other framework-specific values keep their owning
+semantics.
+
 ## Extension points
 
 Use ``register_namespace_provider`` to contribute names used while resolving

{python_introspect-0.1.10 → python_introspect-0.1.12}/pyproject.toml

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

{python_introspect-0.1.10 → python_introspect-0.1.12}/src/python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.10"
+__version__ = "0.1.12"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -72,6 +72,7 @@ from .annotation_types import (
     resolve_optional,
 )
 from .callable_declaration import callable_declaration_kwargs
+from .runtime_parameter import RuntimeParameterDeclarationABC
 
 __all__ = [
     # Version
@@ -130,4 +131,6 @@ __all__ = [
     "resolve_optional",
     # Callable declarations
     "callable_declaration_kwargs",
+    # Runtime-supplied callable parameters
+    "RuntimeParameterDeclarationABC",
 ]

python_introspect-0.1.12/src/python_introspect/docstring_annotations.py

@@ -0,0 +1,193 @@
+"""Typed annotation inference from callable defaults and docstring declarations."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from abc import ABC
+from collections.abc import Callable, Mapping, Sequence
+from functools import reduce
+from operator import or_
+from typing import Any, ClassVar
+
+from metaclass_registry import AutoRegisterMeta
+
+from .annotation_types import make_optional
+from .validation import validate_annotation_value
+
+
+class DocstringTypeDeclaration(ABC, metaclass=AutoRegisterMeta):
+    """Nominal owner for one family of docstring type expressions."""
+
+    __registry_key__ = "declaration_name"
+    __skip_if_no_key__ = True
+
+    declaration_name: ClassVar[str | None] = None
+    expression_pattern: ClassVar[re.Pattern[str] | None] = None
+    annotation: ClassVar[object | None] = None
+
+    @classmethod
+    def annotations_for(cls, description: str | None) -> tuple[object, ...]:
+        """Return every declaration matched by the parameter's type expression."""
+
+        expression = _type_expression(description)
+        if not expression:
+            return ()
+        annotations = {
+            declaration.require_annotation()
+            for declaration_type in cls.__registry__.values()
+            for declaration in (declaration_type(),)
+            if declaration.matches(expression)
+        }
+        return tuple(sorted(annotations, key=_annotation_sort_key))
+
+    def matches(self, expression: str) -> bool:
+        """Return whether this declaration owns a token in ``expression``."""
+
+        pattern = type(self).expression_pattern
+        return pattern is not None and pattern.search(expression) is not None
+
+    def require_annotation(self) -> object:
+        """Return the annotation owned by this concrete declaration."""
+
+        annotation = type(self).annotation
+        if annotation is None:
+            raise TypeError(f"{type(self).__name__}.annotation must declare a Python type.")
+        return annotation
+
+
+class BooleanDocstringType(DocstringTypeDeclaration):
+    declaration_name = "boolean"
+    expression_pattern = re.compile(r"\b(?:bool|boolean|true|false)\b")
+    annotation = bool
+
+
+class IntegerDocstringType(DocstringTypeDeclaration):
+    declaration_name = "integer"
+    expression_pattern = re.compile(r"\b(?:int|integer|ints|integers)\b")
+    annotation = int
+
+
+class FloatDocstringType(DocstringTypeDeclaration):
+    declaration_name = "float"
+    expression_pattern = re.compile(r"\b(?:float|double|scalar|scalars|number|numeric)\b")
+    annotation = float
+
+
+class StringDocstringType(DocstringTypeDeclaration):
+    declaration_name = "string"
+    expression_pattern = re.compile(r"\b(?:str|string|strings)\b")
+    annotation = str
+
+
+class TupleDocstringType(DocstringTypeDeclaration):
+    declaration_name = "tuple"
+    expression_pattern = re.compile(r"\btuple\b")
+    annotation = tuple[Any, ...]
+
+
+class SequenceDocstringType(DocstringTypeDeclaration):
+    declaration_name = "sequence"
+    expression_pattern = re.compile(r"\b(?:ndarray|array(?:[_ -]?like)?|sequence|iterable)\b")
+    annotation = Sequence[Any]
+
+
+class ListDocstringType(DocstringTypeDeclaration):
+    declaration_name = "list"
+    expression_pattern = re.compile(r"\blist\b")
+    annotation = list[Any]
+
+
+class MappingDocstringType(DocstringTypeDeclaration):
+    declaration_name = "mapping"
+    expression_pattern = re.compile(r"\b(?:dict|dictionary|mapping)\b")
+    annotation = Mapping[str, Any]
+
+
+class CallableDocstringType(DocstringTypeDeclaration):
+    declaration_name = "callable"
+    expression_pattern = re.compile(r"\b(?:callable|function)\b")
+    annotation = Callable[..., Any]
+
+
+def infer_parameter_annotation(
+    parameter: inspect.Parameter,
+    description: str | None,
+) -> object:
+    """Infer one missing annotation from declaration-owned runtime evidence."""
+
+    if parameter.annotation is not inspect.Parameter.empty:
+        return parameter.annotation
+
+    documented = DocstringTypeDeclaration.annotations_for(description)
+    default = parameter.default
+    if default is inspect.Parameter.empty:
+        return _union_annotation(documented) if documented else Any
+    if default is None:
+        inferred = _union_annotation(documented)
+        return Any if inferred is Any else make_optional(inferred)
+    if documented and any(
+        _annotation_accepts_default(annotation, default) for annotation in documented
+    ):
+        return _union_annotation(documented)
+    return type(default)
+
+
+def _type_expression(description: str | None) -> str:
+    """Return the first non-empty docstring line that declares a parameter type."""
+
+    if not description:
+        return ""
+    expression = next(
+        (line.strip().lower() for line in description.splitlines() if line.strip()),
+        "",
+    )
+    return _without_nested_type_arguments(expression)
+
+
+def _without_nested_type_arguments(expression: str) -> str:
+    """Remove bracketed member signatures while retaining their owning type."""
+
+    depth = 0
+    projected: list[str] = []
+    for character in expression:
+        if character == "[":
+            depth += 1
+            continue
+        if character == "]":
+            depth = max(0, depth - 1)
+            continue
+        if depth == 0:
+            projected.append(character)
+    return "".join(projected)
+
+
+def _union_annotation(annotations: tuple[object, ...]) -> object:
+    if not annotations:
+        return Any
+    if len(annotations) == 1:
+        return annotations[0]
+    return reduce(or_, annotations)
+
+
+def _annotation_accepts_default(annotation: object, default: object) -> bool:
+    try:
+        validate_annotation_value(annotation, default, path="parameter default")
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def _annotation_sort_key(annotation: object) -> tuple[str, str]:
+    origin = getattr(annotation, "__origin__", None)
+    owner = origin or annotation
+    return (
+        str(getattr(owner, "__module__", "")),
+        str(getattr(owner, "__qualname__", annotation)),
+    )
+
+
+__all__ = [
+    "DocstringTypeDeclaration",
+    "infer_parameter_annotation",
+]

python_introspect-0.1.12/src/python_introspect/runtime_parameter.py

@@ -0,0 +1,85 @@
+"""Nominal declarations for runtime-supplied callable parameters."""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import ClassVar
+
+
+class RuntimeParameterDeclarationABC(ABC):
+    """Semantic owner for one parameter supplied by runtime infrastructure."""
+
+    preserve_for_execution: ClassVar[bool] = False
+    is_semantic_control: ClassVar[bool] = False
+
+    @classmethod
+    @abstractmethod
+    def require_parameter_name(cls) -> str:
+        """Return the public callable parameter name."""
+
+    @classmethod
+    @abstractmethod
+    def parameter(cls) -> inspect.Parameter:
+        """Return the complete callable signature parameter declaration."""
+
+    @classmethod
+    def validated_parameter(cls) -> inspect.Parameter:
+        """Return the parameter after proving its nominal declaration is coherent."""
+
+        parameter = cls.parameter()
+        if not isinstance(parameter, inspect.Parameter):
+            raise TypeError(f"{cls.__name__}.parameter() must return inspect.Parameter.")
+        parameter_name = cls.require_parameter_name()
+        if not isinstance(parameter_name, str) or not parameter_name.strip():
+            raise TypeError(
+                f"{cls.__name__}.require_parameter_name() must return a non-empty string."
+            )
+        if parameter.name != parameter_name:
+            raise TypeError(
+                f"{cls.__name__}.parameter() name {parameter.name!r} does not "
+                f"match require_parameter_name() {parameter_name!r}."
+            )
+        return parameter
+
+    @classmethod
+    def require_declaration_type(
+        cls,
+        candidate: object,
+        *,
+        boundary: str,
+    ) -> type[RuntimeParameterDeclarationABC]:
+        """Require one nominal runtime-parameter declaration type."""
+
+        if not isinstance(candidate, type) or not issubclass(candidate, cls):
+            raise TypeError(
+                f"{boundary} must contain {cls.__name__} subclasses, got {candidate!r}."
+            )
+        candidate.validated_parameter()
+        return candidate
+
+    @classmethod
+    def require_declaration_types(
+        cls,
+        candidates: Iterable[object],
+        *,
+        boundary: str,
+    ) -> tuple[type[RuntimeParameterDeclarationABC], ...]:
+        """Require coherent declarations with unique public parameter names."""
+
+        declarations: list[type[RuntimeParameterDeclarationABC]] = []
+        seen_names: set[str] = set()
+        for candidate in candidates:
+            declaration = cls.require_declaration_type(candidate, boundary=boundary)
+            parameter_name = declaration.require_parameter_name()
+            if parameter_name in seen_names:
+                raise ValueError(
+                    f"{boundary} declares duplicate runtime parameter {parameter_name!r}."
+                )
+            declarations.append(declaration)
+            seen_names.add(parameter_name)
+        return tuple(declarations)
+
+
+__all__ = ("RuntimeParameterDeclarationABC",)

{python_introspect-0.1.10 → python_introspect-0.1.12}/src/python_introspect/signature_analyzer.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 
 from metaclass_registry import AutoRegisterMeta
 from .annotation_types import optional_member_type
+from .docstring_annotations import infer_parameter_annotation
 
 # =============================================================================
 # PLUGIN REGISTRY - Allows frameworks to extend type resolution
@@ -173,19 +174,21 @@ class DocstringParseState:
     parameters: Dict[str, str] = field(default_factory=dict)
     returns: Optional[str] = None
     examples: Optional[str] = None
-    current_param: Optional[str] = None
+    current_params: Tuple[str, ...] = ()
     current_param_lines: List[str] = field(default_factory=list)
 
     def finalize_current_param(self) -> None:
         """Commit the active parameter description, if one is being parsed."""
-        if self.current_param and self.current_param_lines:
-            self.parameters[self.current_param] = (
-                "\n".join(self.current_param_lines).strip()
+        if self.current_params and self.current_param_lines:
+            description = "\n".join(self.current_param_lines).strip()
+            self.parameters.update(
+                (parameter_name, description)
+                for parameter_name in self.current_params
             )
 
     def reset_current_param(self) -> None:
         """Clear parameter continuation state after a section transition."""
-        self.current_param = None
+        self.current_params = ()
         self.current_param_lines = []
 
     def transition_to(self, section: "DocstringSection") -> "DocstringSection":
@@ -283,6 +286,13 @@ class ParametersDocstringSection(DocstringSection):
         "additional parameters:",
     )
     numpy_headers = ("args", "arguments", "parameters", "additional parameters")
+    parameter_declaration_pattern = re.compile(
+        r"^(?:"
+        r":param\s+(?P<sphinx_name>\w+)"
+        r"|[-•*]\s*(?P<bullet_names>\w+(?:\s*,\s*\w+)*)"
+        r"|(?P<plain_names>\w+(?:\s*,\s*\w+)*)"
+        r")\s*:\s*(?P<description>.+)$"
+    )
 
     def consume(
         self,
@@ -290,46 +300,32 @@ class ParametersDocstringSection(DocstringSection):
         original_line: str,
         line: str,
     ) -> None:
-        param_match_google = re.match(r"^(\w+):\s*(.+)", line)
-        param_match_sphinx = re.match(r"^:param\s+(\w+):\s*(.+)", line)
-        param_match_numpy = re.match(r"^(\w+)\s*:\s*(.+)", line)
-        param_match_inline = re.match(
-            r"^(\w+):\s*(\w+(?:\[.*?\])?|\w+(?:\s*\|\s*\w+)*)\s+(.+)",
-            line,
-        )
-        param_match_bullet = re.match(r"^[-•*]\s*(\w+):\s*(.+)", line)
-
-        if (
-            param_match_google
-            or param_match_sphinx
-            or param_match_numpy
-            or param_match_inline
-            or param_match_bullet
-        ):
+        declaration = self.parameter_declaration_pattern.fullmatch(line)
+        if declaration is not None:
             state.finalize_current_param()
-
-            if param_match_google:
-                param_name, param_desc = param_match_google.groups()
-            elif param_match_sphinx:
-                param_name, param_desc = param_match_sphinx.groups()
-            elif param_match_numpy:
-                param_name, param_desc = param_match_numpy.groups()
-            elif param_match_inline:
-                param_name, param_type, param_desc = param_match_inline.groups()
-                param_desc = f"{param_type} - {param_desc}"
-            else:
-                param_name, param_desc = param_match_bullet.groups()
-
-            state.current_param = param_name
-            state.current_param_lines = [param_desc.strip()]
-        elif state.current_param and (
+            declared_names = next(
+                value
+                for value in (
+                    declaration.group("sphinx_name"),
+                    declaration.group("bullet_names"),
+                    declaration.group("plain_names"),
+                )
+                if value is not None
+            )
+            state.current_params = tuple(
+                name.strip() for name in declared_names.split(",")
+            )
+            state.current_param_lines = [
+                declaration.group("description").strip()
+            ]
+        elif state.current_params and (
             original_line.startswith("    ") or original_line.startswith("\t")
         ):
             state.current_param_lines.append(line)
         elif not line:
             state.finalize_current_param()
             state.reset_current_param()
-        elif state.current_param:
+        elif state.current_params:
             state.current_param_lines.append(line)
         else:
             state.parameters.update(DocstringExtractor._parse_inline_parameters(line))
@@ -731,12 +727,16 @@ class CallableAnalysisContext:
 
     @staticmethod
     def annotation_namespace_targets(target: Callable) -> Tuple[Callable, ...]:
-        """Return wrapped-to-public callables whose namespaces can own annotations."""
+        """Return runtime-to-declaration callables whose namespaces own annotations."""
 
         unwrapped = inspect.unwrap(target)
         if unwrapped is target:
             return (target,)
-        return (unwrapped, target)
+        # ``functools.wraps`` copies the declaration's annotation strings onto a
+        # wrapper whose runtime globals belong to the decorator module.  Merge
+        # outward so the unwrapped declaration, which authored those strings,
+        # has final authority over colliding names.
+        return (target, unwrapped)
 
     def type_hints(self) -> Dict[str, Any]:
         """Resolve type hints using the context-owned namespace."""
@@ -854,14 +854,6 @@ class SignatureAnalyzer:
                 continue 
 
             from typing import Any
-            param_type = type_hints.get(param_name)
-            if param_type is None:
-                param_type = (
-                    param.annotation
-                    if param.annotation is not inspect.Parameter.empty
-                    else Any
-                )
-            param_type, annotation_description = _parameter_annotation_help(param_type)
             default_value = param.default if param.default != inspect.Parameter.empty else None
             is_required = param.default == inspect.Parameter.empty
 
@@ -872,8 +864,17 @@ class SignatureAnalyzer:
                 else None
             )
             if param_description is None:
+                annotation = type_hints.get(param_name, param.annotation)
+                _base_annotation, annotation_description = _parameter_annotation_help(
+                    annotation
+                )
                 param_description = annotation_description
 
+            annotation = type_hints.get(param_name, param.annotation)
+            if annotation is inspect.Parameter.empty:
+                annotation = infer_parameter_annotation(param, param_description)
+            param_type, _annotation_description = _parameter_annotation_help(annotation)
+
             parameters[param_name] = ParameterInfo(
                 name=param_name,
                 param_type=param_type,

{python_introspect-0.1.10 → python_introspect-0.1.12}/src/python_introspect/validation.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping, Sequence, Set
+from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Set as AbstractSet
 from dataclasses import fields, is_dataclass, replace
 from functools import singledispatch
 from typing import (
@@ -10,13 +11,14 @@ from typing import (
     Any,
     ClassVar,
     Literal,
+    TypeVar,
     get_args,
     get_origin,
     get_type_hints,
-    TypeVar,
 )
 
 from annotated_types import Ge, Gt, Interval, Le, Len, Lt, MaxLen, MinLen, Predicate
+
 from .annotation_types import is_union_type
 
 
@@ -133,21 +135,22 @@ def validate_annotation_value(
         )
     if origin is Literal:
         choices = get_args(annotation)
-        if not any(
-            type(value) is type(choice) and value == choice
-            for choice in choices
-        ):
+        if not any(type(value) is type(choice) and value == choice for choice in choices):
             raise AnnotationValidationError(f"{path} must be one of {choices!r}.")
         return
     if origin is tuple:
         _validate_tuple(annotation, value, path)
         return
-    if origin in {list, set, frozenset, Sequence, Set}:
+    if origin in {list, set, frozenset, Sequence, AbstractSet}:
         _validate_sequence(annotation, value, path)
         return
     if origin in {dict, Mapping}:
         _validate_mapping(annotation, value, path)
         return
+    if origin is Callable:
+        if not callable(value):
+            raise TypeError(f"{path} must be callable; got {type(value).__name__}.")
+        return
     if origin is ClassVar:
         return
     if annotation is None or annotation is type(None):

{python_introspect-0.1.10 → python_introspect-0.1.12/src/python_introspect.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.10
+Version: 0.1.12
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -37,7 +37,7 @@ Dynamic: license-file
 # python-introspect
 
 Extensible analysis of callable signatures, dataclass fields, type hints, and
-docstrings.
+docstrings, plus signature-derived callable declaration projection.
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://badge.fury.io/py/python-introspect.svg)](https://badge.fury.io/py/python-introspect)
@@ -66,6 +66,11 @@ for name, info in parameters.items():
 dataclass types, and instances. It returns a mapping of names to
 ``ParameterInfo`` records.
 
+Use ``callable_declaration_kwargs`` when declaration identity should omit
+keyword arguments equal to their signature defaults. The caller supplies value
+equality so array, lazy, or other framework-specific values keep their owning
+semantics.
+
 ## Extension points
 
 Use ``register_namespace_provider`` to contribute names used while resolving

{python_introspect-0.1.10 → python_introspect-0.1.12}/src/python_introspect.egg-info/SOURCES.txt

@@ -5,9 +5,11 @@ src/python_introspect/__init__.py
 src/python_introspect/annotation_types.py
 src/python_introspect/callable_declaration.py
 src/python_introspect/dataclass_projection.py
+src/python_introspect/docstring_annotations.py
 src/python_introspect/enableable.py
 src/python_introspect/environment_projection.py
 src/python_introspect/exceptions.py
+src/python_introspect/runtime_parameter.py
 src/python_introspect/signature_analyzer.py
 src/python_introspect/unified_parameter_analyzer.py
 src/python_introspect/validation.py
@@ -22,6 +24,8 @@ tests/test_dataclass_projection.py
 tests/test_environment_projection.py
 tests/test_exceptions.py
 tests/test_init.py
+tests/test_runtime_parameter.py
 tests/test_signature_analyzer.py
 tests/test_unified_parameter_analyzer.py
+tests/test_validate_python_release_action.py
 tests/test_validation.py

{python_introspect-0.1.10 → python_introspect-0.1.12}/tests/test_init.py

@@ -11,42 +11,48 @@ class TestPackageImports:
         """Test that __version__ is available."""
         assert hasattr(python_introspect, "__version__")
         assert isinstance(python_introspect.__version__, str)
-        assert python_introspect.__version__ == "0.1.10"
+        assert python_introspect.__version__ == "0.1.12"
 
     def test_signature_analyzer_import(self):
         """Test SignatureAnalyzer is importable."""
         assert hasattr(python_introspect, "SignatureAnalyzer")
         from python_introspect import SignatureAnalyzer
+
         assert SignatureAnalyzer is not None
 
     def test_parameter_info_import(self):
         """Test ParameterInfo is importable."""
         assert hasattr(python_introspect, "ParameterInfo")
         from python_introspect import ParameterInfo
+
         assert ParameterInfo is not None
 
     def test_docstring_info_import(self):
         """Test DocstringInfo is importable."""
         assert hasattr(python_introspect, "DocstringInfo")
         from python_introspect import DocstringInfo
+
         assert DocstringInfo is not None
 
     def test_docstring_extractor_import(self):
         """Test DocstringExtractor is importable."""
         assert hasattr(python_introspect, "DocstringExtractor")
         from python_introspect import DocstringExtractor
+
         assert DocstringExtractor is not None
 
     def test_unified_parameter_analyzer_import(self):
         """Test UnifiedParameterAnalyzer is importable."""
         assert hasattr(python_introspect, "UnifiedParameterAnalyzer")
         from python_introspect import UnifiedParameterAnalyzer
+
         assert UnifiedParameterAnalyzer is not None
 
     def test_unified_parameter_info_import(self):
         """Test UnifiedParameterInfo is importable."""
         assert hasattr(python_introspect, "UnifiedParameterInfo")
         from python_introspect import UnifiedParameterInfo
+
         assert UnifiedParameterInfo is not None
 
     def test_exceptions_import(self):
@@ -57,6 +63,7 @@ class TestPackageImports:
             DocstringParsingError,
             TypeResolutionError,
         )
+
         assert IntrospectionError is not None
         assert SignatureAnalysisError is not None
         assert DocstringParsingError is not None
@@ -98,6 +105,7 @@ class TestPublicAPI:
         """Test that 'from python_introspect import *' works."""
         # This is a sanity check that __all__ is properly defined
         import python_introspect
+
         all_names = python_introspect.__all__
 
         for name in all_names:

python_introspect-0.1.12/tests/test_runtime_parameter.py

@@ -0,0 +1,58 @@
+"""Tests for nominal runtime-parameter declarations."""
+
+import inspect
+
+import pytest
+
+from python_introspect import RuntimeParameterDeclarationABC
+
+
+class ExampleRuntimeParameter(RuntimeParameterDeclarationABC):
+    @classmethod
+    def require_parameter_name(cls) -> str:
+        return "runtime_value"
+
+    @classmethod
+    def parameter(cls) -> inspect.Parameter:
+        return inspect.Parameter(
+            cls.require_parameter_name(),
+            inspect.Parameter.KEYWORD_ONLY,
+            annotation=int,
+        )
+
+
+class StructuralImpostor:
+    @classmethod
+    def require_parameter_name(cls) -> str:
+        return "runtime_value"
+
+    @classmethod
+    def parameter(cls) -> inspect.Parameter:
+        return inspect.Parameter("runtime_value", inspect.Parameter.KEYWORD_ONLY)
+
+
+class MismatchedRuntimeParameter(ExampleRuntimeParameter):
+    @classmethod
+    def parameter(cls) -> inspect.Parameter:
+        return inspect.Parameter("different_name", inspect.Parameter.KEYWORD_ONLY)
+
+
+def test_runtime_parameter_requires_nominal_subclass() -> None:
+    with pytest.raises(TypeError, match="RuntimeParameterDeclarationABC subclasses"):
+        RuntimeParameterDeclarationABC.require_declaration_type(
+            StructuralImpostor,
+            boundary="test declarations",
+        )
+
+
+def test_runtime_parameter_requires_matching_declared_name() -> None:
+    with pytest.raises(TypeError, match="does not match require_parameter_name"):
+        MismatchedRuntimeParameter.validated_parameter()
+
+
+def test_runtime_parameter_collection_requires_unique_names() -> None:
+    with pytest.raises(ValueError, match="duplicate runtime parameter 'runtime_value'"):
+        RuntimeParameterDeclarationABC.require_declaration_types(
+            (ExampleRuntimeParameter, ExampleRuntimeParameter),
+            boundary="test declarations",
+        )

{python_introspect-0.1.10 → python_introspect-0.1.12}/tests/test_signature_analyzer.py

@@ -1,10 +1,11 @@
 """Tests for SignatureAnalyzer."""
 
 import inspect
+from collections.abc import Callable as CallableABC, Sequence
 from dataclasses import dataclass, field
 from enum import Enum
 from functools import wraps
-from typing import get_args
+from typing import get_args, get_origin
 from typing import Annotated, Optional, List, Dict, Any
 from python_introspect import (
     SignatureAnalyzer,
@@ -90,6 +91,49 @@ class TestSignatureAnalyzer:
         assert params["slice_by_slice"].param_type is bool
         assert params["slice_by_slice"].default_value is False
 
+    def test_unannotated_callable_parameters_derive_types_from_declarations(self):
+        """Defaults and NumPy-style type lines form a typed authoring signature."""
+
+        def external(
+            image,
+            values=None,
+            exclude_border=False,
+            block_size=2,
+            reducer=max,
+        ):
+            """External array operation.
+
+            Parameters
+            ----------
+            image : ndarray
+                Input image.
+            values : ndarray, optional
+                Optional values.
+            exclude_border : tuple of ints, int, or False, optional
+                Border exclusion.
+            block_size : array_like or int
+                Block dimensions.
+            reducer : callable
+                Reduction function.
+            """
+
+        params = SignatureAnalyzer.analyze(external)
+
+        assert set(get_args(params["values"].param_type)) == {
+            Sequence[Any],
+            type(None),
+        }
+        assert set(get_args(params["exclude_border"].param_type)) == {
+            bool,
+            int,
+            tuple[Any, ...],
+        }
+        assert set(get_args(params["block_size"].param_type)) == {
+            int,
+            Sequence[Any],
+        }
+        assert get_origin(params["reducer"].param_type) is CallableABC
+
     def test_wrapped_callable_resolves_postponed_annotations_from_original_namespace(self):
         """Wrapper modules do not own postponed annotations copied from originals."""
         def original(mode: "WrappedAnnotationMode | str" = WrappedAnnotationMode.A):
@@ -106,6 +150,27 @@ class TestSignatureAnalyzer:
 
         assert get_args(params["mode"].param_type) == (WrappedAnnotationMode, str)
 
+    def test_wrapped_declaration_namespace_overrides_decorator_name_collision(self):
+        """Copied annotation strings resolve against their declaration owner."""
+
+        def original(mode: "WrappedAnnotationMode" = WrappedAnnotationMode.A):
+            pass
+
+        wrapper_namespace = {"wraps": wraps, "original": original}
+        exec(
+            "@wraps(original)\n"
+            "def wrapper(*args, **kwargs):\n"
+            "    return original(*args, **kwargs)\n",
+            wrapper_namespace,
+        )
+        wrapper = wrapper_namespace["wrapper"]
+        wrapper.__globals__["WrappedAnnotationMode"] = lambda: None
+        wrapper.__signature__ = inspect.signature(original)
+
+        params = SignatureAnalyzer.analyze(wrapper)
+
+        assert params["mode"].param_type is WrappedAnnotationMode
+
     def test_analyze_function_with_docstring(self):
         """Test analyzing function with docstring parameters."""
         def documented_func(name: str, age: int = 25):
@@ -419,6 +484,23 @@ class TestDocstringExtractor:
         # NumPy style parsing support
         assert "x" in info.parameters or info.parameters == {}
 
+    def test_extract_numpy_style_multi_name_declaration(self):
+        """One NumPy declaration can author the same description for many names."""
+
+        def func(in_range="image", out_range="dtype"):
+            """Rescale values.
+
+            Parameters
+            ----------
+            in_range, out_range : str or 2-tuple, optional
+                Accepted intensity bounds.
+            """
+
+        info = DocstringExtractor.extract(func)
+
+        assert info.parameters["in_range"].startswith("str or 2-tuple")
+        assert info.parameters["out_range"] == info.parameters["in_range"]
+
     def test_extract_multiline_parameter_description(self):
         """Test extracting multiline parameter descriptions."""
         def func(description: str):

python_introspect-0.1.12/tests/test_validate_python_release_action.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+from zipfile import ZipFile
+
+import pytest
+
+ACTION_SCRIPT = (
+    Path(__file__).parents[1]
+    / ".github"
+    / "actions"
+    / "validate-python-release"
+    / "validate_python_release.py"
+)
+
+
+def _load_action() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("validate_python_release", ACTION_SCRIPT)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _git(repository: Path, *arguments: str) -> str:
+    return subprocess.run(
+        ("git", *arguments),
+        cwd=repository,
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+
+
+def _release_repository(tmp_path: Path, tag: str, *, annotated: bool = True) -> str:
+    _git(tmp_path, "init")
+    _git(tmp_path, "config", "user.email", "release@example.test")
+    _git(tmp_path, "config", "user.name", "Release Test")
+    (tmp_path / "tracked.txt").write_text("release\n", encoding="utf-8")
+    _git(tmp_path, "add", "tracked.txt")
+    _git(tmp_path, "commit", "-m", "Release candidate")
+    if annotated:
+        _git(tmp_path, "tag", "-a", tag, "-m", tag)
+    else:
+        _git(tmp_path, "tag", tag)
+    return _git(tmp_path, "rev-parse", "HEAD")
+
+
+def _wheel(tmp_path: Path, version: str = "1.2.3") -> None:
+    distribution = tmp_path / "dist" / f"demo_package-{version}-py3-none-any.whl"
+    distribution.parent.mkdir()
+    with ZipFile(distribution, "w") as wheel:
+        wheel.writestr(
+            f"demo_package-{version}.dist-info/METADATA",
+            "Metadata-Version: 2.1\n" "Name: demo-package\n" f"Version: {version}\n",
+        )
+
+
+def test_action_accepts_one_matching_annotated_release(tmp_path: Path) -> None:
+    action = _load_action()
+    commit = _release_repository(tmp_path, "v1.2.3")
+    _wheel(tmp_path)
+
+    assert (
+        action.main(
+            [
+                "--repository-root",
+                str(tmp_path),
+                "--tag",
+                "v1.2.3",
+                "--commit",
+                commit,
+            ]
+        )
+        == 0
+    )
+
+
+@pytest.mark.parametrize(
+    ("tag", "version", "annotated"),
+    [
+        ("v1.2.4", "1.2.3", True),
+        ("v1.2.3", "1.2.3", False),
+    ],
+)
+def test_action_rejects_mismatched_or_lightweight_tags(
+    tmp_path: Path,
+    tag: str,
+    version: str,
+    annotated: bool,
+) -> None:
+    action = _load_action()
+    commit = _release_repository(tmp_path, tag, annotated=annotated)
+    _wheel(tmp_path, version)
+
+    assert (
+        action.main(
+            [
+                "--repository-root",
+                str(tmp_path),
+                "--tag",
+                tag,
+                "--commit",
+                commit,
+            ]
+        )
+        == 1
+    )
+
+
+def test_action_rejects_a_commit_other_than_the_tag_target(tmp_path: Path) -> None:
+    action = _load_action()
+    _release_repository(tmp_path, "v1.2.3")
+    _wheel(tmp_path)
+    (tmp_path / "tracked.txt").write_text("later\n", encoding="utf-8")
+    _git(tmp_path, "add", "tracked.txt")
+    _git(tmp_path, "commit", "-m", "Later commit")
+    later_commit = _git(tmp_path, "rev-parse", "HEAD")
+
+    assert (
+        action.main(
+            [
+                "--repository-root",
+                str(tmp_path),
+                "--tag",
+                "v1.2.3",
+                "--commit",
+                later_commit,
+            ]
+        )
+        == 1
+    )

{python_introspect-0.1.10 → python_introspect-0.1.12}/tests/test_validation.py

@@ -1,6 +1,7 @@
+from collections.abc import Callable
 from dataclasses import dataclass, make_dataclass
 from enum import Enum
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal
 
 import pytest
 from annotated_types import Ge, Gt, Le, MinLen, Predicate
@@ -9,6 +10,7 @@ from python_introspect import (
     AnnotatedDataclassValidationMixin,
     overlay_non_none_dataclass,
     validate_annotated_dataclass,
+    validate_annotation_value,
 )
 
 
@@ -93,6 +95,19 @@ def test_literal_validation_preserves_nominal_identity() -> None:
         LiteralConfig(value=True)
 
 
+def test_callable_validation_uses_the_declared_runtime_contract() -> None:
+    class CallableInstance:
+        def __call__(self) -> None:
+            pass
+
+    annotation = Callable[..., Any]
+    validate_annotation_value(annotation, max, path="reducer")
+    validate_annotation_value(annotation, CallableInstance(), path="reducer")
+
+    with pytest.raises(TypeError, match="reducer must be callable"):
+        validate_annotation_value(annotation, 7, path="reducer")
+
+
 @dataclass(frozen=True)
 class ConnectionSpec:
     host: str = "localhost"