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

python_introspect-0.1.5/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: python-introspect
+Version: 0.1.5
+Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
+Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
+License: MIT
+Project-URL: Homepage, https://github.com/OpenHCSDev/python-introspect
+Project-URL: Repository, https://github.com/OpenHCSDev/python-introspect
+Project-URL: Issues, https://github.com/OpenHCSDev/python-introspect/issues
+Keywords: introspection,reflection,signature,dataclass,type-hints,docstring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: metaclass-registry>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
+Dynamic: license-file
+
+# python-introspect
+
+Extensible analysis of callable signatures, dataclass fields, type hints, and
+docstrings.
+
+[![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)
+
+## Quick start
+
+```python
+from python_introspect import SignatureAnalyzer
+
+def resize(image, factor: float = 0.5, *, preserve_range: bool = True):
+    """Resize an image.
+
+    Args:
+        image: Input image.
+        factor: Scale factor.
+        preserve_range: Preserve the input intensity range.
+    """
+
+parameters = SignatureAnalyzer().analyze(resize)
+
+for name, info in parameters.items():
+    print(name, info.param_type, info.default_value, info.is_required)
+```
+
+``analyze`` is the unified entry point for functions, methods, classes,
+dataclass types, and instances. It returns a mapping of names to
+``ParameterInfo`` records.
+
+## Extension points
+
+Use ``register_namespace_provider`` to contribute names used while resolving
+forward references and ``register_type_resolver`` to unwrap application proxy
+types. Wrappers can declare their user-facing inspection target through the
+signature-target helpers in ``python_introspect.signature_analyzer``.
+
+## Installation
+
+```bash
+python -m pip install python-introspect
+```
+
+The runtime depends on metaclass-registry. Repository and issues:
+[OpenHCSDev/python-introspect](https://github.com/OpenHCSDev/python-introspect).
+
+## Documentation
+
+The maintained sources are in [`docs/source`](docs/source). Documentation
+changes are checked by the repository's [documentation
+workflow](https://github.com/OpenHCSDev/python-introspect/actions/workflows/docs.yml);
+the local warnings-as-errors build command is documented in
+[`development.rst`](docs/source/development.rst).

python_introspect-0.1.5/README.md

@@ -0,0 +1,55 @@
+# python-introspect
+
+Extensible analysis of callable signatures, dataclass fields, type hints, and
+docstrings.
+
+[![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)
+
+## Quick start
+
+```python
+from python_introspect import SignatureAnalyzer
+
+def resize(image, factor: float = 0.5, *, preserve_range: bool = True):
+    """Resize an image.
+
+    Args:
+        image: Input image.
+        factor: Scale factor.
+        preserve_range: Preserve the input intensity range.
+    """
+
+parameters = SignatureAnalyzer().analyze(resize)
+
+for name, info in parameters.items():
+    print(name, info.param_type, info.default_value, info.is_required)
+```
+
+``analyze`` is the unified entry point for functions, methods, classes,
+dataclass types, and instances. It returns a mapping of names to
+``ParameterInfo`` records.
+
+## Extension points
+
+Use ``register_namespace_provider`` to contribute names used while resolving
+forward references and ``register_type_resolver`` to unwrap application proxy
+types. Wrappers can declare their user-facing inspection target through the
+signature-target helpers in ``python_introspect.signature_analyzer``.
+
+## Installation
+
+```bash
+python -m pip install python-introspect
+```
+
+The runtime depends on metaclass-registry. Repository and issues:
+[OpenHCSDev/python-introspect](https://github.com/OpenHCSDev/python-introspect).
+
+## Documentation
+
+The maintained sources are in [`docs/source`](docs/source). Documentation
+changes are checked by the repository's [documentation
+workflow](https://github.com/OpenHCSDev/python-introspect/actions/workflows/docs.yml);
+the local warnings-as-errors build command is documented in
+[`development.rst`](docs/source/development.rst).

{python_introspect-0.1.4 → python_introspect-0.1.5}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.4"
+version = "0.1.5"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = {text = "MIT"}
 authors = [
     {name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}
@@ -18,7 +18,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -26,7 +25,9 @@ classifiers = [
     "Topic :: Utilities",
 ]
 
-dependencies = []
+dependencies = [
+    "metaclass-registry>=0.1.0",
+]
 
 [project.optional-dependencies]
 dev = [
@@ -58,14 +59,14 @@ python_functions = ["test_*"]
 
 [tool.ruff]
 line-length = 100
-target-version = "0.1.4"
+target-version = "py310"
 
 [tool.black]
 line-length = 100
-target-version = ["py39"]
+target-version = ["py310"]
 
 [tool.mypy]
-python_version = "0.1.4"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

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

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -19,10 +19,15 @@ from .signature_analyzer import (
     # Plugin registration
     register_namespace_provider,
     register_type_resolver,
+    set_signature_analysis_target,
+    signature_analysis_target,
 )
 from .unified_parameter_analyzer import (
     UnifiedParameterAnalyzer,
     UnifiedParameterInfo,
+    add_parameter_exclusions,
+    set_parameter_exclusions,
+    parameter_exclusions,
 )
 from .exceptions import (
     IntrospectionError,
@@ -34,7 +39,6 @@ from .enableable import (
     Enableable,
     is_enableable,
     mark_enableable,
-    ENABLED_FIELD,
 )
 
 __all__ = [
@@ -48,9 +52,14 @@ __all__ = [
     # Plugin registration
     "register_namespace_provider",
     "register_type_resolver",
+    "set_signature_analysis_target",
+    "signature_analysis_target",
     # Unified analysis
     "UnifiedParameterAnalyzer",
     "UnifiedParameterInfo",
+    "add_parameter_exclusions",
+    "set_parameter_exclusions",
+    "parameter_exclusions",
     # Exceptions
     "IntrospectionError",
     "SignatureAnalysisError",
@@ -60,5 +69,4 @@ __all__ = [
     "Enableable",
     "is_enableable",
     "mark_enableable",
-    "ENABLED_FIELD",
 ]

python_introspect-0.1.5/src/python_introspect/enableable.py

@@ -0,0 +1,156 @@
+"""Nominal enable semantics as type-safe metadata.
+
+This module provides a single, shared "axis" for objects and callables that
+participate in enabled semantics.
+
+Design goals:
+- Nominal (not structural): only explicitly branded callables qualify.
+- Dataclass-friendly: configs can inherit Enableable to get an enabled field.
+- Callable-safe: branded callables must declare an `enabled` parameter.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import ABC, ABCMeta
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from typing import Any
+from typing import get_type_hints
+from weakref import WeakKeyDictionary
+
+
+_ENABLEABLE_TAG = object()
+_enableable_objects: WeakKeyDictionary[Any, object] = WeakKeyDictionary()
+_enableable_objects_by_id: dict[int, tuple[Any, object]] = {}
+
+
+def _remember_enableable(obj: Any) -> None:
+    """Record explicit enableable branding without mutating the object."""
+    try:
+        _enableable_objects[obj] = _ENABLEABLE_TAG
+    except TypeError:
+        _enableable_objects_by_id[id(obj)] = (obj, _ENABLEABLE_TAG)
+
+
+def _is_marked_enableable(obj: Any) -> bool:
+    """Return whether an object was explicitly branded as enableable."""
+    try:
+        if _enableable_objects.get(obj) is _ENABLEABLE_TAG:
+            return True
+    except TypeError:
+        pass
+
+    fallback_record = _enableable_objects_by_id.get(id(obj))
+    return fallback_record is not None and fallback_record[0] is obj
+
+
+class EnableableMeta(ABCMeta):
+    """Metaclass enabling nominal isinstance checks for branded callables."""
+
+    def __instancecheck__(cls, instance: Any) -> bool:  # type: ignore[override]
+        if _is_marked_enableable(instance):
+            return True
+        return super().__instancecheck__(instance)
+
+
+@dataclass(frozen=True)
+class Enableable(ABC, metaclass=EnableableMeta):
+    """Mixin indicating an object participates in enabled semantics."""
+
+    enabled: bool = True
+    """Run this callable or configuration when enabled; skip it when disabled."""
+
+    @classmethod
+    def callable_field(cls):
+        """Return the dataclass field that defines callable enable semantics."""
+        return fields(Enableable)[0]
+
+    @classmethod
+    def require_parameter_name(cls) -> str:
+        return cls.callable_field().name
+
+    @classmethod
+    def default_value(cls) -> bool:
+        return cls.callable_field().default
+
+    @classmethod
+    def annotation_type(cls) -> type[bool]:
+        return get_type_hints(Enableable)[cls.require_parameter_name()]
+
+    @classmethod
+    def parameter(cls) -> inspect.Parameter:
+        return inspect.Parameter(
+            cls.require_parameter_name(),
+            inspect.Parameter.KEYWORD_ONLY,
+            default=cls.default_value(),
+            annotation=cls.annotation_type(),
+        )
+
+    @classmethod
+    def parameter_in(cls, values: Mapping[Any, Any]) -> bool:
+        """Return whether a kwargs-like mapping carries the enable parameter."""
+        return cls.require_parameter_name() in values
+
+    @classmethod
+    def is_parameter_key(cls, key: Any) -> bool:
+        """Return whether key names the enable parameter."""
+        return key == cls.require_parameter_name()
+
+    @classmethod
+    def disabled_in(cls, values: Mapping[Any, Any]) -> bool:
+        """Return whether a kwargs-like mapping explicitly disables execution."""
+        if not cls.parameter_in(values):
+            return False
+        return values[cls.require_parameter_name()] is False
+
+    @classmethod
+    def without_parameter(cls, values: Mapping[Any, Any]) -> dict[Any, Any]:
+        """Return a copy of mapping values without the enable parameter."""
+        return {
+            key: value
+            for key, value in values.items()
+            if not cls.is_parameter_key(key)
+        }
+
+
+def is_enableable(obj: Any) -> bool:
+    """Return True iff obj is nominally Enableable.
+
+    Works for both instances (using isinstance) and classes (using issubclass).
+    This is needed because widget creation code needs to check if a type (class)
+    is enableable, not just instances.
+    """
+
+    # Check if obj is a type/class
+    if isinstance(obj, type):
+        # obj is a class - check if it's a subclass of Enableable
+        try:
+            return issubclass(obj, Enableable)
+        except TypeError:
+            # obj is not a class or is not class-like (e.g., a generic type)
+            return False
+    else:
+        # obj is an instance - use isinstance
+        return isinstance(obj, Enableable)
+
+
+def mark_enableable(obj: Any, *, enabled_default: bool = True) -> Any:
+    """Nominally brand an object/callable as Enableable.
+
+    This does not wrap and does not change call semantics.
+    """
+
+    _ = enabled_default  # reserved for future: default enabled semantics
+
+    # If we're branding a callable, require the enabled kwarg to exist.
+    if callable(obj) and not isinstance(obj, type):
+        sig = inspect.signature(obj)
+        parameter_name = Enableable.require_parameter_name()
+        if parameter_name not in sig.parameters:
+            raise TypeError(
+                f"Enableable callable {obj!r} must have an '{parameter_name}' parameter"
+            )
+
+    _remember_enableable(obj)
+    return obj