python-introspect 0.1.16__tar.gz → 0.2.2__tar.gz

{python_introspect-0.1.16/src/python_introspect.egg-info → python_introspect-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.16
+Version: 0.2.2
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -24,6 +24,7 @@ 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: tomli>=2.0.1; python_version < "3.11" and 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"
@@ -94,3 +95,19 @@ 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).
+
+### Parameter declarations in 0.2
+
+`UnifiedParameterAnalyzer` now returns the original `ParameterInfo` declarations
+from `SignatureAnalyzer`. `UnifiedParameterInfo`, its `source_type` tag, and
+`analyze_nested` were removed. Use `analyze` and the declared `param_type` for
+parameter topology.
+
+`ParameterInfo` retains its five public fields, constructor and `_replace`
+operation, and is now a frozen declaration rather than a tuple. Tuple unpacking
+and NamedTuple helpers are no longer supported. Dataclass descriptions are
+derived on first help access; value/default overlays preserve that deferred
+source, and renaming preserves the original field's help. Callable descriptions
+still participate eagerly in inferred parameter types. A presentation extraction
+error yields absent help without discarding valid types/defaults. Factory errors
+remain uncached and retryable.

{python_introspect-0.1.16 → python_introspect-0.2.2}/README.md

@@ -58,3 +58,19 @@ 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).
+
+### Parameter declarations in 0.2
+
+`UnifiedParameterAnalyzer` now returns the original `ParameterInfo` declarations
+from `SignatureAnalyzer`. `UnifiedParameterInfo`, its `source_type` tag, and
+`analyze_nested` were removed. Use `analyze` and the declared `param_type` for
+parameter topology.
+
+`ParameterInfo` retains its five public fields, constructor and `_replace`
+operation, and is now a frozen declaration rather than a tuple. Tuple unpacking
+and NamedTuple helpers are no longer supported. Dataclass descriptions are
+derived on first help access; value/default overlays preserve that deferred
+source, and renaming preserves the original field's help. Callable descriptions
+still participate eagerly in inferred parameter types. A presentation extraction
+error yields absent help without discarding valid types/defaults. Factory errors
+remain uncached and retryable.

{python_introspect-0.1.16 → python_introspect-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.16"
+version = "0.2.2"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -33,6 +33,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
+    "tomli>=2.0.1; python_version < '3.11'",
     "pytest-cov>=4.0",
     "ruff>=0.1.0",
     "black>=23.0",

{python_introspect-0.1.16 → python_introspect-0.2.2}/src/python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.16"
+__version__ = "0.2.2"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
@@ -24,7 +24,6 @@ from .signature_analyzer import (
 )
 from .unified_parameter_analyzer import (
     UnifiedParameterAnalyzer,
-    UnifiedParameterInfo,
     add_parameter_exclusions,
     set_parameter_exclusions,
     parameter_exclusions,
@@ -51,6 +50,19 @@ from .dataclass_projection import (
     dataclass_from_mapping,
     project_dataclass,
 )
+from .jsonable import (
+    JsonObject,
+    JsonScalar,
+    JsonValue,
+    to_jsonable,
+)
+from .public_api import (
+    declared_public_names,
+    exported_public_names,
+    is_declared_public_name,
+    lazy_exports,
+    public_names_from_objects,
+)
 from .environment_projection import (
     EnvironmentVariable,
     overlay_dataclass_from_environment,
@@ -89,7 +101,6 @@ __all__ = [
     "signature_analysis_target",
     # Unified analysis
     "UnifiedParameterAnalyzer",
-    "UnifiedParameterInfo",
     "add_parameter_exclusions",
     "set_parameter_exclusions",
     "parameter_exclusions",
@@ -111,6 +122,17 @@ __all__ = [
     # Dataclass projection
     "dataclass_from_mapping",
     "project_dataclass",
+    # JSON-native projection
+    "JsonObject",
+    "JsonScalar",
+    "JsonValue",
+    "to_jsonable",
+    # Module public surfaces
+    "declared_public_names",
+    "exported_public_names",
+    "is_declared_public_name",
+    "lazy_exports",
+    "public_names_from_objects",
     # Environment projection
     "EnvironmentVariable",
     "overlay_dataclass_from_environment",

{python_introspect-0.1.16 → python_introspect-0.2.2}/src/python_introspect/annotation_types.py

@@ -2,9 +2,54 @@
 
 from __future__ import annotations
 
+import sys
 import types
 from enum import Enum
-from typing import Annotated, Union, get_args, get_origin
+from typing import Annotated, Literal, Union, get_args, get_origin, get_type_hints
+
+
+def resolved_class_annotations(owner: type) -> dict[str, object]:
+    """Resolve nested type strings in the class that declared each field.
+
+    Python 3.10 leaves strings inside PEP 585 aliases unresolved. Complete
+    those declarations without interpreting Literal values or Annotated metadata.
+    """
+    annotations = get_type_hints(owner, include_extras=True)
+    unresolved = set(annotations)
+    for declaration in owner.__mro__:
+        class_namespace = dict(vars(declaration))
+        module = sys.modules.get(declaration.__module__)
+        module_namespace = {} if module is None else vars(module)
+        for name in class_namespace.get("__annotations__", {}):
+            if name in unresolved:
+                annotations[name] = _resolve_nested_type_strings(
+                    annotations[name], class_namespace, module_namespace
+                )
+                unresolved.remove(name)
+    return annotations
+
+
+def _resolve_nested_type_strings(annotation: object, globalns: dict, localns: dict) -> object:
+    if isinstance(annotation, str):
+        return _resolve_nested_type_strings(eval(annotation, globalns, localns), globalns, localns)
+    if isinstance(annotation, list):
+        resolved = [_resolve_nested_type_strings(member, globalns, localns) 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)
+        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)
+    if all(member is original for member, original in zip(resolved, members)):
+        return annotation
+    if isinstance(annotation, types.GenericAlias):
+        return types.GenericAlias(origin, resolved)
+    if is_union_type(annotation):
+        return Union[resolved]  # noqa: UP007 - dynamically derived member tuple
+    return origin[resolved]
 
 
 def is_union_type(annotation: object) -> bool:

{python_introspect-0.1.16 → python_introspect-0.2.2}/src/python_introspect/dataclass_projection.py

@@ -13,10 +13,9 @@ from typing import (
     TypeVar,
     get_args,
     get_origin,
-    get_type_hints,
 )
 
-from .annotation_types import is_union_type
+from .annotation_types import is_union_type, resolved_class_annotations
 from .validation import validate_annotated_dataclass, validate_annotation_value
 
 DataclassT = TypeVar("DataclassT")
@@ -53,7 +52,7 @@ def dataclass_from_mapping(
             f"{target_type.__name__} received undeclared field(s): {', '.join(extras)}."
         )
 
-    annotations = get_type_hints(target_type, include_extras=True)
+    annotations = resolved_class_annotations(target_type)
     decoded_values: dict[str, object] = {}
     missing: list[str] = []
     for declared_field in declared_fields:

python_introspect-0.2.2/src/python_introspect/jsonable.py

@@ -0,0 +1,120 @@
+"""JSON-native projection of declared Python values.
+
+``to_jsonable`` is the encoder paired with ``dataclass_from_mapping``: a
+dataclass projects through its declared fields, and the decoder rebuilds it
+from the same declarations. Further value types join through
+``to_jsonable.register``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from functools import singledispatch
+from pathlib import Path
+from typing import ForwardRef, TypeAlias
+
+from metaclass_registry import AutoRegisterMeta
+
+from .signature_analyzer import signature_analysis_target
+
+JsonScalar: TypeAlias = str | int | float | bool | None
+# Recursive aliases retain this declaration's namespace when imported by
+# dataclasses; get_type_hints evaluates the reference in this module.
+_JSON_VALUE_REFERENCE = ForwardRef("JsonValue", module=__name__)
+JsonValue: TypeAlias = (
+    JsonScalar
+    | Mapping[str, _JSON_VALUE_REFERENCE]
+    | tuple[_JSON_VALUE_REFERENCE, ...]
+    | list[_JSON_VALUE_REFERENCE]
+)
+JsonObject: TypeAlias = Mapping[str, JsonValue]
+
+
+def _jsonable_dataclass(value: object) -> JsonValue:
+    """Project fields without ``asdict`` deep-copying immutable containers."""
+
+    return {
+        declared_field.name: to_jsonable(getattr(value, declared_field.name))
+        for declared_field in fields(value)
+    }
+
+
+@singledispatch
+def to_jsonable(value: object) -> JsonValue:
+    """Project dataclasses and registered values into JSON-native data."""
+
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable_dataclass(value)
+    raise TypeError(f"Value is not JSON-serializable: {type(value).__name__}")
+
+
+@to_jsonable.register(Mapping)
+def _jsonable_mapping(value: Mapping) -> JsonValue:
+    return {str(to_jsonable(key)): to_jsonable(item) for key, item in value.items()}
+
+
+@to_jsonable.register(tuple)
+@to_jsonable.register(list)
+@to_jsonable.register(set)
+@to_jsonable.register(frozenset)
+def _jsonable_sequence(value) -> JsonValue:
+    return [to_jsonable(item) for item in value]
+
+
+@to_jsonable.register(Callable)
+def _jsonable_callable(value: Callable[..., object]) -> JsonValue:
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable_dataclass(value)
+    target = signature_analysis_target(value)
+    module = inspect.getmodule(target)
+    module_name = type(target).__module__ if module is None else module.__name__
+    if inspect.isfunction(target) or inspect.ismethod(target) or inspect.isclass(target):
+        qualname = target.__qualname__
+    else:
+        qualname = type(target).__qualname__
+    return {
+        "kind": "callable",
+        "name": qualname.rsplit(".", 1)[-1],
+        "module": module_name,
+        "qualname": qualname,
+        "import_path": f"{module_name}.{qualname}",
+    }
+
+
+@to_jsonable.register(AutoRegisterMeta)
+def _jsonable_registered_type(value: AutoRegisterMeta) -> JsonValue:
+    key_attribute = value.__registry_key__
+    declaring_owner = next(
+        (owner for owner in value.__mro__ if key_attribute in vars(owner)),
+        None,
+    )
+    if declaring_owner is None:
+        raise TypeError(
+            f"Registered type {value.__qualname__} has no declared " f"{key_attribute!r} key."
+        )
+    key = vars(declaring_owner)[key_attribute]
+    if key is None:
+        raise TypeError(f"Registered type {value.__qualname__} has no registry key.")
+    return to_jsonable(key)
+
+
+@to_jsonable.register(Enum)
+def _jsonable_enum(value: Enum) -> JsonValue:
+    return to_jsonable(value.value)
+
+
+@to_jsonable.register(Path)
+def _jsonable_path(value: Path) -> JsonValue:
+    return str(value)
+
+
+@to_jsonable.register(type(None))
+@to_jsonable.register(str)
+@to_jsonable.register(int)
+@to_jsonable.register(float)
+@to_jsonable.register(bool)
+def _jsonable_scalar(value) -> JsonValue:
+    return value

python_introspect-0.2.2/src/python_introspect/public_api.py

@@ -0,0 +1,111 @@
+"""Module public surfaces derived from what a module declares."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from importlib import import_module
+from inspect import isclass, isfunction
+from types import ModuleType
+from typing import Any
+
+
+def declared_public_names(
+    module_globals: Mapping[str, object],
+    *,
+    constant_prefixes: Iterable[str] = (),
+    excluded_names: Iterable[str] = (),
+    extra_names: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """Return public names declared by the module represented by globals()."""
+    module_name = module_globals["__name__"]
+    prefixes = tuple(constant_prefixes)
+    excluded = set(excluded_names)
+    declared_names = tuple(
+        name
+        for name, value in module_globals.items()
+        if name not in excluded
+        if is_declared_public_name(
+            module_name,
+            name,
+            value,
+            constant_prefixes=prefixes,
+        )
+    )
+    return declared_names + tuple(name for name in extra_names if name not in excluded)
+
+
+def exported_public_names(
+    module_globals: Mapping[str, object],
+    *,
+    excluded_names: Iterable[str] = (),
+) -> tuple[str, ...]:
+    """Return public re-export names declared by explicit module imports."""
+    excluded = set(excluded_names)
+    return tuple(
+        name
+        for name, value in module_globals.items()
+        if not name.startswith("_")
+        if name not in excluded
+        if not isinstance(value, ModuleType)
+    )
+
+
+def public_names_from_objects(*objects: Any, extra_names: Iterable[str] = ()) -> tuple[str, ...]:
+    """Return public names from exported object identities plus explicit aliases."""
+    return tuple(item if isinstance(item, str) else item.__name__ for item in objects) + tuple(
+        extra_names
+    )
+
+
+def is_declared_public_name(
+    module_name: str,
+    name: str,
+    value: object,
+    *,
+    constant_prefixes: tuple[str, ...] = (),
+) -> bool:
+    """Return whether a global is a public module declaration."""
+    if name.startswith("_"):
+        return False
+    if name.isupper():
+        return any(name.startswith(prefix) for prefix in constant_prefixes)
+    return (isclass(value) or isfunction(value)) and value.__module__ == module_name
+
+
+def lazy_exports(
+    module_globals: dict[str, object],
+    exports: Mapping[str, Iterable[str]],
+) -> tuple[str, ...]:
+    """Install PEP 562 ``__getattr__``/``__dir__`` resolving names on first access.
+
+    ``exports`` maps each owning module path (absolute, or relative to the
+    package whose ``globals()`` are passed) to the names it supplies. A name is
+    imported from its owner on first access and cached in the module globals.
+    Returns the exported names in declaration order, for ``__all__``.
+    """
+
+    module_name = module_globals["__name__"]
+    package = module_globals.get("__package__") or module_name
+    owners: dict[str, str] = {}
+    for owner, names in exports.items():
+        for name in names:
+            if name in owners:
+                raise ValueError(
+                    f"{module_name} lazy export {name!r} is declared by both "
+                    f"{owners[name]!r} and {owner!r}."
+                )
+            owners[name] = owner
+
+    def __getattr__(name: str) -> object:
+        if name not in owners:
+            raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
+        value = getattr(import_module(owners[name], package), name)
+        module_globals[name] = value
+        return value
+
+    def __dir__() -> list[str]:
+        return sorted(set(module_globals) | set(owners))
+
+    module_globals["__getattr__"] = __getattr__
+    module_globals["__dir__"] = __dir__
+    return tuple(owners)