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

python_introspect-0.1.6/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: python-introspect
+Version: 0.1.6
+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: annotated-types>=0.7.0
+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.6/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.6}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.4"
+version = "0.1.6"
 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,10 @@ classifiers = [
     "Topic :: Utilities",
 ]
 
-dependencies = []
+dependencies = [
+    "annotated-types>=0.7.0",
+    "metaclass-registry>=0.1.0",
+]
 
 [project.optional-dependencies]
 dev = [
@@ -58,14 +60,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.6/src/python_introspect/__init__.py

@@ -0,0 +1,118 @@
+"""
+python-introspect: Pure Python introspection toolkit
+
+This package provides utilities for introspecting Python functions, methods,
+dataclasses, and type hints.
+
+Extensibility:
+    Use register_namespace_provider() and register_type_resolver() to extend
+    type resolution for framework-specific types (lazy configs, proxies, etc.)
+"""
+
+__version__ = "0.1.6"
+
+from .signature_analyzer import (
+    SignatureAnalyzer,
+    ParameterInfo,
+    DocstringInfo,
+    DocstringExtractor,
+    # 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,
+    SignatureAnalysisError,
+    DocstringParsingError,
+    TypeResolutionError,
+)
+from .enableable import (
+    Enableable,
+    is_enableable,
+    mark_enableable,
+)
+from .validation import (
+    AnnotationValidationError,
+    overlay_non_none_dataclass,
+    validate_annotated_dataclass,
+    validate_annotation_value,
+)
+from .dataclass_projection import (
+    dataclass_from_mapping,
+    project_dataclass,
+)
+from .environment_projection import (
+    EnvironmentVariable,
+    overlay_dataclass_from_environment,
+)
+from .annotation_types import (
+    enum_member_type,
+    get_enum_from_list,
+    is_enum_type,
+    is_list_of_enums,
+    is_union_type,
+    make_optional,
+    optional_member_type,
+    resolve_annotated,
+    resolve_optional,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Signature analysis
+    "SignatureAnalyzer",
+    "ParameterInfo",
+    "DocstringInfo",
+    "DocstringExtractor",
+    # 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",
+    "DocstringParsingError",
+    "TypeResolutionError",
+    # Enableable
+    "Enableable",
+    "is_enableable",
+    "mark_enableable",
+    # Runtime annotation validation
+    "AnnotationValidationError",
+    "overlay_non_none_dataclass",
+    "validate_annotated_dataclass",
+    "validate_annotation_value",
+    # Dataclass projection
+    "dataclass_from_mapping",
+    "project_dataclass",
+    # Environment projection
+    "EnvironmentVariable",
+    "overlay_dataclass_from_environment",
+    # Annotation type operations
+    "enum_member_type",
+    "get_enum_from_list",
+    "is_enum_type",
+    "is_list_of_enums",
+    "is_union_type",
+    "make_optional",
+    "optional_member_type",
+    "resolve_annotated",
+    "resolve_optional",
+]

python_introspect-0.1.6/src/python_introspect/annotation_types.py

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

python_introspect-0.1.6/src/python_introspect/dataclass_projection.py

@@ -0,0 +1,269 @@
+"""Dataclass construction and projection derived from declared annotations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import MISSING, fields, is_dataclass
+from enum import Enum
+from pathlib import Path
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    TypeVar,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from .annotation_types import is_union_type
+from .validation import validate_annotated_dataclass, validate_annotation_value
+
+
+DataclassT = TypeVar("DataclassT")
+
+
+def dataclass_from_mapping(
+    target_type: type[DataclassT],
+    values: Mapping[str, object],
+) -> DataclassT:
+    """Construct one dataclass from the fields declared by its class."""
+
+    if not isinstance(target_type, type) or not is_dataclass(target_type):
+        raise TypeError(
+            "dataclass_from_mapping requires a dataclass type; "
+            f"got {target_type!r}."
+        )
+    if not isinstance(values, Mapping):
+        raise TypeError("dataclass_from_mapping requires a mapping.")
+    non_text_keys = tuple(key for key in values if not isinstance(key, str))
+    if non_text_keys:
+        raise TypeError(
+            f"{target_type.__name__} field names must be strings; "
+            f"got {non_text_keys!r}."
+        )
+
+    declared_fields = tuple(
+        declared_field for declared_field in fields(target_type) if declared_field.init
+    )
+    declared_names = {declared_field.name for declared_field in declared_fields}
+    extras = tuple(sorted(set(values) - declared_names))
+    if extras:
+        raise ValueError(
+            f"{target_type.__name__} received undeclared field(s): {', '.join(extras)}."
+        )
+
+    annotations = get_type_hints(target_type, include_extras=True)
+    constructor_values: dict[str, object] = {}
+    missing: list[str] = []
+    for declared_field in declared_fields:
+        if declared_field.name not in values:
+            if declared_field.default is MISSING and declared_field.default_factory is MISSING:
+                missing.append(declared_field.name)
+            continue
+        annotation = annotations.get(declared_field.name, declared_field.type)
+        constructor_values[declared_field.name] = _mapping_value_for_annotation(
+            annotation,
+            values[declared_field.name],
+            path=f"{target_type.__name__}.{declared_field.name}",
+        )
+    if missing:
+        raise ValueError(
+            f"{target_type.__name__} is missing required field(s): {', '.join(missing)}."
+        )
+
+    result = target_type(**constructor_values)
+    validate_annotated_dataclass(result)
+    return result
+
+
+def project_dataclass(
+    target_type: type[DataclassT],
+    source: object,
+    **overrides: object,
+) -> DataclassT:
+    """Project shared declared fields from one dataclass into another."""
+
+    if not isinstance(target_type, type) or not is_dataclass(target_type):
+        raise TypeError(
+            "project_dataclass requires a dataclass target type; "
+            f"got {target_type!r}."
+        )
+    if not is_dataclass(source) or isinstance(source, type):
+        raise TypeError("project_dataclass requires a dataclass source instance.")
+
+    target_fields = tuple(
+        declared_field for declared_field in fields(target_type) if declared_field.init
+    )
+    target_names = {declared_field.name for declared_field in target_fields}
+    invalid_overrides = tuple(sorted(set(overrides) - target_names))
+    if invalid_overrides:
+        raise ValueError(
+            f"{target_type.__name__} received undeclared override(s): "
+            f"{', '.join(invalid_overrides)}."
+        )
+
+    source_values = {
+        declared_field.name: object.__getattribute__(source, declared_field.name)
+        for declared_field in fields(source)
+    }
+    constructor_values = {
+        declared_field.name: source_values[declared_field.name]
+        for declared_field in target_fields
+        if declared_field.name in source_values
+    }
+    constructor_values.update(overrides)
+    result = target_type(**constructor_values)
+    validate_annotated_dataclass(result)
+    return result
+
+
+def _mapping_value_for_annotation(
+    annotation: object,
+    value: object,
+    *,
+    path: str,
+) -> object:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        base_type = get_args(annotation)[0]
+        converted = _mapping_value_for_annotation(base_type, value, path=path)
+        validate_annotation_value(annotation, converted, path=path)
+        return converted
+    if annotation is Any:
+        return value
+    if annotation is tuple:
+        if not isinstance(value, (list, tuple)):
+            raise TypeError(f"{path} must be an array.")
+        return tuple(value)
+    if is_union_type(annotation):
+        successes: list[object] = []
+        errors: list[Exception] = []
+        for member_type in get_args(annotation):
+            try:
+                converted = _mapping_value_for_annotation(
+                    member_type,
+                    value,
+                    path=path,
+                )
+                validate_annotation_value(member_type, converted, path=path)
+            except (TypeError, ValueError) as error:
+                errors.append(error)
+                continue
+            successes.append(converted)
+        if len(successes) == 1:
+            return successes[0]
+        exact_matches = tuple(
+            converted
+            for converted in successes
+            if type(converted) is type(value)
+        )
+        if len(exact_matches) == 1:
+            return exact_matches[0]
+        if successes:
+            raise TypeError(
+                f"{path} ambiguously matches multiple members of {annotation!r}."
+            )
+        value_errors = tuple(
+            error for error in errors if isinstance(error, ValueError)
+        )
+        if len(value_errors) == 1:
+            raise value_errors[0]
+        if value_errors:
+            details = "; ".join(str(error) for error in value_errors)
+            raise ValueError(
+                f"{path} does not match any constrained union member: {details}"
+            )
+        detail = f" Last error: {errors[-1]}" if errors else ""
+        raise TypeError(f"{path} does not match its declared union.{detail}") from (
+            errors[-1] if errors else None
+        )
+    if origin is Literal:
+        validate_annotation_value(annotation, value, path=path)
+        return value
+    if origin is tuple:
+        if not isinstance(value, (list, tuple)):
+            raise TypeError(f"{path} must be an array.")
+        member_types = get_args(annotation)
+        if not member_types:
+            return tuple(value)
+        if len(member_types) == 2 and member_types[1] is Ellipsis:
+            return tuple(
+                _mapping_value_for_annotation(
+                    member_types[0],
+                    item,
+                    path=f"{path}[{index}]",
+                )
+                for index, item in enumerate(value)
+            )
+        if member_types and len(value) != len(member_types):
+            raise ValueError(f"{path} must contain {len(member_types)} item(s); got {len(value)}.")
+        return tuple(
+            _mapping_value_for_annotation(
+                member_type,
+                item,
+                path=f"{path}[{index}]",
+            )
+            for index, (member_type, item) in enumerate(zip(member_types, value))
+        )
+    if origin is list:
+        if not isinstance(value, list):
+            raise TypeError(f"{path} must be an array.")
+        member_types = get_args(annotation)
+        if not member_types:
+            return list(value)
+        return [
+            _mapping_value_for_annotation(
+                member_types[0],
+                item,
+                path=f"{path}[{index}]",
+            )
+            for index, item in enumerate(value)
+        ]
+    if origin in {dict, Mapping}:
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{path} must be an object.")
+        member_types = get_args(annotation)
+        if len(member_types) != 2:
+            return dict(value)
+        key_type, item_type = member_types
+        return {
+            _mapping_value_for_annotation(
+                key_type,
+                key,
+                path=f"{path}.key",
+            ): _mapping_value_for_annotation(
+                item_type,
+                item,
+                path=f"{path}[{key!r}]",
+            )
+            for key, item in value.items()
+        }
+    if annotation is type(None):
+        if value is not None:
+            raise TypeError(f"{path} must be null.")
+        return None
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        if isinstance(value, annotation):
+            return value
+        try:
+            return annotation(value)
+        except ValueError as error:
+            choices = tuple(member.value for member in annotation)
+            raise ValueError(f"{path} must be one of {choices!r}; got {value!r}.") from error
+    if isinstance(annotation, type) and is_dataclass(annotation):
+        if isinstance(value, annotation):
+            return value
+        if not isinstance(value, Mapping):
+            raise TypeError(f"{path} must be an object.")
+        return dataclass_from_mapping(annotation, value)
+    if annotation is Path:
+        if isinstance(value, Path):
+            return value
+        if not isinstance(value, str):
+            raise TypeError(f"{path} must be a path string.")
+        return Path(value)
+    if annotation is float and type(value) is int:
+        return float(value)
+    validate_annotation_value(annotation, value, path=path)
+    return value