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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.9
+Version: 0.1.11
 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.9 → python_introspect-0.1.11}/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.9 → python_introspect-0.1.11}/pyproject.toml

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

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

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.9"
+__version__ = "0.1.11"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -71,6 +71,8 @@ from .annotation_types import (
     resolve_annotated,
     resolve_optional,
 )
+from .callable_declaration import callable_declaration_kwargs
+from .runtime_parameter import RuntimeParameterDeclarationABC
 
 __all__ = [
     # Version
@@ -127,4 +129,8 @@ __all__ = [
     "optional_member_type",
     "resolve_annotated",
     "resolve_optional",
+    # Callable declarations
+    "callable_declaration_kwargs",
+    # Runtime-supplied callable parameters
+    "RuntimeParameterDeclarationABC",
 ]

python_introspect-0.1.11/src/python_introspect/callable_declaration.py

@@ -0,0 +1,37 @@
+"""Declaration projections derived from callable signatures."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping
+from typing import TypeVar
+
+
+ParameterValue = TypeVar("ParameterValue")
+
+
+def callable_declaration_kwargs(
+    func: Callable,
+    kwargs: Mapping[str, ParameterValue],
+    *,
+    values_equal: Callable[[object, object], bool],
+) -> dict[str, ParameterValue]:
+    """Return declared kwargs whose values differ from signature defaults.
+
+    Equality remains caller-owned so frameworks can supply semantics for
+    arrays, lazy values, and other values whose ``==`` result is not boolean.
+    """
+
+    try:
+        defaults = {
+            name: parameter.default
+            for name, parameter in inspect.signature(func).parameters.items()
+            if parameter.default is not inspect.Parameter.empty
+        }
+    except (TypeError, ValueError):
+        defaults = {}
+    return {
+        name: value
+        for name, value in kwargs.items()
+        if name not in defaults or not values_equal(value, defaults[name])
+    }

python_introspect-0.1.11/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.9 → python_introspect-0.1.11/src/python_introspect.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.9
+Version: 0.1.11
 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.9 → python_introspect-0.1.11}/src/python_introspect.egg-info/SOURCES.txt

@@ -3,10 +3,12 @@ README.md
 pyproject.toml
 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/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
@@ -16,10 +18,12 @@ src/python_introspect.egg-info/dependency_links.txt
 src/python_introspect.egg-info/requires.txt
 src/python_introspect.egg-info/top_level.txt
 tests/test_annotation_types.py
+tests/test_callable_declaration.py
 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_validation.py

python_introspect-0.1.11/tests/test_callable_declaration.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from operator import attrgetter
+
+from python_introspect import callable_declaration_kwargs
+
+
+def sample_function(value, threshold: float = 1.0, enabled: bool = True):
+    return value
+
+
+def test_callable_declaration_kwargs_projects_signature_defaults() -> None:
+    kwargs = {
+        "threshold": 1,
+        "enabled": False,
+        "extension_parameter": "preserved",
+    }
+
+    declaration = callable_declaration_kwargs(
+        sample_function,
+        kwargs,
+        values_equal=lambda left, right: left == right,
+    )
+
+    assert declaration == {
+        "enabled": False,
+        "extension_parameter": "preserved",
+    }
+
+
+def test_callable_declaration_kwargs_preserves_values_for_opaque_callable() -> None:
+    kwargs = {"extension_parameter": "preserved"}
+
+    declaration = callable_declaration_kwargs(
+        attrgetter("value"),
+        kwargs,
+        values_equal=lambda left, right: left == right,
+    )
+
+    assert declaration == kwargs

{python_introspect-0.1.9 → python_introspect-0.1.11}/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.9"
+        assert python_introspect.__version__ == "0.1.11"
 
     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.11/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",
+        )