python-introspect 0.1.2__tar.gz → 0.1.3__tar.gz

{python_introspect-0.1.2/src/python_introspect.egg-info → python_introspect-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.2
+Version: 0.1.3
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -28,8 +28,9 @@ 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: mkdocs>=1.5.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.0.0; 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

{python_introspect-0.1.2 → python_introspect-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.2"
+version = "0.1.3"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -37,8 +37,9 @@ dev = [
     "mypy>=1.0",
 ]
 docs = [
-    "mkdocs>=1.5.0",
-    "mkdocs-material>=9.0.0",
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme>=2.0.0",
+    "sphinx-autodoc-typehints>=1.24.0",
 ]
 
 [project.urls]
@@ -57,14 +58,14 @@ python_functions = ["test_*"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "0.1.3"
 
 [tool.black]
 line-length = 100
 target-version = ["py39"]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "0.1.3"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{python_introspect-0.1.2 → python_introspect-0.1.3}/src/python_introspect/__init__.py

@@ -3,15 +3,20 @@ 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.2"
+__version__ = "0.1.3"
 
 from .signature_analyzer import (
     SignatureAnalyzer,
     ParameterInfo,
     DocstringInfo,
     DocstringExtractor,
+    # Plugin registration
     register_namespace_provider,
     register_type_resolver,
 )
@@ -25,6 +30,12 @@ from .exceptions import (
     DocstringParsingError,
     TypeResolutionError,
 )
+from .enableable import (
+    Enableable,
+    is_enableable,
+    mark_enableable,
+    ENABLED_FIELD,
+)
 
 __all__ = [
     # Version
@@ -34,15 +45,20 @@ __all__ = [
     "ParameterInfo",
     "DocstringInfo",
     "DocstringExtractor",
+    # Plugin registration
+    "register_namespace_provider",
+    "register_type_resolver",
     # Unified analysis
     "UnifiedParameterAnalyzer",
     "UnifiedParameterInfo",
-    # Plugin system
-    "register_namespace_provider",
-    "register_type_resolver",
     # Exceptions
     "IntrospectionError",
     "SignatureAnalysisError",
     "DocstringParsingError",
     "TypeResolutionError",
+    # Enableable
+    "Enableable",
+    "is_enableable",
+    "mark_enableable",
+    "ENABLED_FIELD",
 ]

python_introspect-0.1.3/src/python_introspect/enableable.py

@@ -0,0 +1,79 @@
+"""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 dataclasses import dataclass
+from typing import Any
+
+
+ENABLED_FIELD = 'enabled'
+
+_ENABLEABLE_TAG = object()
+
+
+class EnableableMeta(ABCMeta):
+    """Metaclass enabling nominal isinstance checks for branded callables."""
+
+    def __instancecheck__(cls, instance: Any) -> bool:  # type: ignore[override]
+        if getattr(instance, '__enableable_tag__', None) is _ENABLEABLE_TAG:
+            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
+
+
+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)
+        if ENABLED_FIELD not in sig.parameters:
+            raise TypeError(
+                f"Enableable callable '{getattr(obj, '__name__', obj)}' must have an '{ENABLED_FIELD}' parameter"
+            )
+
+    setattr(obj, '__enableable_tag__', _ENABLEABLE_TAG)
+    return obj

{python_introspect-0.1.2 → python_introspect-0.1.3}/src/python_introspect/signature_analyzer.py

@@ -1,86 +1,82 @@
 # File: python_introspect/signature_analyzer.py
+"""
+Signature analysis with extensible type resolution.
+
+This module provides pure Python introspection with a plugin architecture
+for framework-specific extensions. Register namespace providers and type
+resolvers to extend functionality without modifying this code.
+"""
 
 import ast
 import inspect
 import dataclasses
 import re
 from typing import Any, Dict, Callable, get_type_hints, NamedTuple, Union, Optional, Type, List
+
 from dataclasses import dataclass
 
-# Plugin system for namespace and type resolution
-# External packages can register their own providers/resolvers
+# =============================================================================
+# PLUGIN REGISTRY - Allows frameworks to extend type resolution
+# =============================================================================
+
+# Namespace providers: functions that return Dict[str, Any] for get_type_hints()
+# Used to resolve forward references like "GlobalPipelineConfig" -> actual class
 _namespace_providers: List[Callable[[], Dict[str, Any]]] = []
+
+# Type resolvers: functions that map types to their "real" types
+# e.g., LazyWellFilterConfig -> WellFilterConfig
 _type_resolvers: List[Callable[[type], Optional[type]]] = []
 
 
 def register_namespace_provider(provider: Callable[[], Dict[str, Any]]) -> None:
     """Register a namespace provider for forward reference resolution.
 
-    Args:
-        provider: A callable that returns a dict of names to types/values
-                 to be used when resolving forward references in type hints.
+    The provider function should return a dict of names to types/values
+    that will be available during get_type_hints() resolution.
 
     Example:
-        def my_namespace_provider():
-            import mypackage
-            return vars(mypackage)
-
-        register_namespace_provider(my_namespace_provider)
+        register_namespace_provider(lambda: {'MyClass': MyClass, 'MyEnum': MyEnum})
     """
     _namespace_providers.append(provider)
 
 
 def register_type_resolver(resolver: Callable[[type], Optional[type]]) -> None:
-    """Register a type resolver for custom type transformations.
+    """Register a type resolver for lazy/proxy type unwrapping.
 
-    Args:
-        resolver: A callable that takes a type and returns either:
-                 - A transformed type (e.g., LazyConfig -> Config)
-                 - None to defer to other resolvers
+    The resolver function should return the resolved type if it can handle
+    the input type, or None to defer to other resolvers.
 
     Example:
-        def my_type_resolver(t):
+        def resolve_lazy(t):
             if t.__name__.startswith('Lazy'):
                 return get_base_type(t)
             return None
-
-        register_type_resolver(my_type_resolver)
+        register_type_resolver(resolve_lazy)
     """
     _type_resolvers.append(resolver)
 
 
-def _get_registered_namespaces() -> Dict[str, Any]:
-    """Get all registered namespaces merged together."""
-    result = {}
+def _get_extended_namespace() -> Dict[str, Any]:
+    """Get combined namespace from all registered providers."""
+    result: Dict[str, Any] = {}
     for provider in _namespace_providers:
         try:
-            namespace = provider()
-            if namespace:
-                result.update(namespace)
+            result.update(provider())
         except Exception:
-            # Silently skip providers that fail
-            pass
+            pass  # Ignore providers that fail
     return result
 
 
 def _resolve_type(t: type) -> type:
-    """Resolve a type using registered type resolvers.
-
-    Args:
-        t: The type to resolve
-
-    Returns:
-        The resolved type, or the original type if no resolver handled it
-    """
+    """Resolve a type through registered resolvers, returning the unwrapped type."""
     for resolver in _type_resolvers:
         try:
             resolved = resolver(t)
             if resolved is not None:
                 return resolved
         except Exception:
-            # Silently skip resolvers that fail
-            pass
-    return t
+            pass  # Ignore resolvers that fail
+    return t  # No resolver handled it, return as-is
 
 
 @dataclass(frozen=True)
@@ -440,13 +436,14 @@ class SignatureAnalyzer:
         """
         sig = inspect.signature(callable_obj)
         # Build comprehensive namespace for forward reference resolution
-        # Start with registered namespaces, then add function's globals
+        # Start with registered namespace providers, then add function's globals
+        extended_ns = _get_extended_namespace()
         globalns = {
-            **_get_registered_namespaces(),
+            **extended_ns,
             **getattr(callable_obj, '__globals__', {})
         }
 
-        # For functions with a module, prioritize the function's actual module globals
+        # Prioritize the function's actual module globals for type resolution
         if hasattr(callable_obj, '__module__') and callable_obj.__module__:
             try:
                 import sys
@@ -454,7 +451,7 @@ class SignatureAnalyzer:
                 if actual_module:
                     # Function's module globals should take precedence for type resolution
                     globalns = {
-                        **_get_registered_namespaces(),
+                        **extended_ns,
                         **vars(actual_module)  # This overwrites with the actual module types
                     }
             except Exception:
@@ -640,10 +637,10 @@ class SignatureAnalyzer:
         # Use the class object itself as the key (classes are hashable and have stable identity)
         cache_key = dataclass_type
         if cache_key in SignatureAnalyzer._dataclass_analysis_cache:
-            logger.info(f"✅ CACHE HIT for {dataclass_type.__name__} (id={id(dataclass_type)})")
+            logger.debug(f"✅ CACHE HIT for {dataclass_type.__name__} (id={id(dataclass_type)})")
             return SignatureAnalyzer._dataclass_analysis_cache[cache_key]
 
-        logger.info(f"❌ CACHE MISS for {dataclass_type.__name__} (id={id(dataclass_type)}), cache has {len(SignatureAnalyzer._dataclass_analysis_cache)} entries")
+        logger.debug(f"❌ CACHE MISS for {dataclass_type.__name__} (id={id(dataclass_type)}), cache has {len(SignatureAnalyzer._dataclass_analysis_cache)} entries")
 
         try:
             # Try to get type hints, fall back to __annotations__ if resolution fails
@@ -1013,7 +1010,8 @@ class SignatureAnalyzer:
     def _resolve_lazy_dataclass_for_docs(dataclass_type: type) -> type:
         """Resolve lazy dataclasses to their base classes for documentation extraction.
 
-        Uses registered type resolvers to handle custom type transformations.
+        Uses registered type resolvers to unwrap lazy/proxy types.
+        Falls back to heuristics if no resolver handles the type.
 
         Args:
             dataclass_type: The dataclass type (potentially lazy)
@@ -1021,7 +1019,40 @@ class SignatureAnalyzer:
         Returns:
             The resolved dataclass type for documentation extraction
         """
-        return _resolve_type(dataclass_type)
+        try:
+            # First, try registered type resolvers (framework-specific)
+            resolved = _resolve_type(dataclass_type)
+            if resolved is not dataclass_type:
+                return resolved
+
+            # Fallback heuristics for common patterns (framework-agnostic)
+            class_name = dataclass_type.__name__
+
+            # Handle LazyXxxConfig -> XxxConfig by looking in same module
+            if class_name.startswith('Lazy') and class_name.endswith('Config'):
+                try:
+                    base_class_name = class_name[4:]  # Remove 'Lazy' prefix
+                    module = __import__(dataclass_type.__module__, fromlist=[base_class_name])
+                    if hasattr(module, base_class_name):
+                        return getattr(module, base_class_name)
+                except (ImportError, AttributeError):
+                    pass
+
+            # Try to find GlobalXxxConfig version in same module
+            if not class_name.startswith('Global') and class_name.endswith('Config'):
+                try:
+                    global_class_name = f'Global{class_name}'
+                    module = __import__(dataclass_type.__module__, fromlist=[global_class_name])
+                    if hasattr(module, global_class_name):
+                        return getattr(module, global_class_name)
+                except (ImportError, AttributeError):
+                    pass
+
+            # If no resolution found, return the original type
+            return dataclass_type
+
+        except Exception:
+            return dataclass_type
 
     @staticmethod
     def _extract_all_field_docs(dataclass_type: type) -> Dict[str, str]:
@@ -1120,16 +1151,12 @@ class SignatureAnalyzer:
             parameters = SignatureAnalyzer._analyze_dataclass(dataclass_type)
 
             # Update default values with current instance values
-            # For lazy dataclasses, use object.__getattribute__ to preserve None values for placeholders
+            # CRITICAL: Always use object.__getattribute__ to bypass __getattribute__ overrides
+            # This ensures we get the raw stored value, not a resolved/computed value
             for name, param_info in parameters.items():
-                if hasattr(instance, name):
-                    # Check if this is a lazy dataclass that should preserve None values
-                    if hasattr(instance, '_resolve_field_value'):
-                        # This is a lazy dataclass - use object.__getattribute__ to get stored value
-                        current_value = object.__getattribute__(instance, name)
-                    else:
-                        # Regular dataclass - use normal getattr
-                        current_value = getattr(instance, name)
+                try:
+                    # Bypass __getattribute__ to get raw stored value (not resolved)
+                    current_value = object.__getattribute__(instance, name)
 
                     # Create new ParameterInfo with current value as default
                     parameters[name] = ParameterInfo(
@@ -1139,6 +1166,9 @@ class SignatureAnalyzer:
                         is_required=param_info.is_required,
                         description=param_info.description
                     )
+                except AttributeError:
+                    # Field doesn't exist on instance, keep signature default
+                    pass
 
             return parameters
 

{python_introspect-0.1.2 → python_introspect-0.1.3}/src/python_introspect/unified_parameter_analyzer.py

@@ -82,12 +82,11 @@ class UnifiedParameterAnalyzer:
             if dataclasses.is_dataclass(target):
                 result = UnifiedParameterAnalyzer._analyze_dataclass_type(target)
             else:
-                # CRITICAL FIX: For classes, use _analyze_object_instance with use_signature_defaults=True
-                # This traverses MRO to get all inherited parameters with signature defaults
+                # For classes, use _analyze_object_instance to traverse MRO
                 # Create a dummy instance just to get the class hierarchy analyzed
                 try:
                     dummy_instance = target.__new__(target)
-                    result = UnifiedParameterAnalyzer._analyze_object_instance(dummy_instance, use_signature_defaults=True)
+                    result = UnifiedParameterAnalyzer._analyze_object_instance(dummy_instance)
                 except:
                     # If we can't create a dummy instance, fall back to just analyzing __init__
                     result = UnifiedParameterAnalyzer._analyze_callable(target.__init__)
@@ -147,12 +146,14 @@ class UnifiedParameterAnalyzer:
         return unified_params
 
     @staticmethod
-    def _analyze_object_instance(instance: object, use_signature_defaults: bool = False) -> Dict[str, UnifiedParameterInfo]:
+    def _analyze_object_instance(instance: object) -> Dict[str, UnifiedParameterInfo]:
         """Analyze a regular object instance by examining its full inheritance hierarchy.
 
+        Always returns CLASS signature defaults (not instance values).
+        ObjectState extracts instance values separately via object.__getattribute__.
+
         Args:
             instance: Object instance to analyze
-            use_signature_defaults: If True, use signature defaults instead of instance values
         """
         # Use MRO to get all constructor parameters from the inheritance chain
         instance_class = type(instance)
@@ -184,20 +185,13 @@ class UnifiedParameterAnalyzer:
                 # Add parameters that haven't been seen yet (most specific wins)
                 for param_name, param_info in class_params.items():
                     if param_name not in all_params and param_name != 'kwargs':
-                        # CRITICAL FIX: For reset functionality, use signature defaults instead of instance values
-                        if use_signature_defaults:
-                            default_value = param_info.default_value
-                        else:
-                            # Get current value from instance if it exists
-                            default_value = getattr(instance, param_name, param_info.default_value)
-
-                        # Create parameter info with appropriate default value
+                        # Always use signature defaults - ObjectState extracts instance values separately
                         all_params[param_name] = UnifiedParameterInfo(
                             name=param_name,
                             param_type=param_info.param_type,
-                            default_value=default_value,
+                            default_value=param_info.default_value,
                             is_required=param_info.is_required,
-                            description=param_info.description,  # CRITICAL FIX: Include description
+                            description=param_info.description,
                             source_type="object_instance"
                         )
 
@@ -210,28 +204,14 @@ class UnifiedParameterAnalyzer:
 
     @staticmethod
     def _analyze_dataclass_instance(instance: object) -> Dict[str, UnifiedParameterInfo]:
-        """Analyze a dataclass instance."""
-        # Get the type and analyze it
-        dataclass_type = type(instance)
-        unified_params = UnifiedParameterAnalyzer._analyze_dataclass_type(dataclass_type)
-
-        # Update default values with current instance values
-        for name, param_info in unified_params.items():
-            if hasattr(instance, name):
-                # For regular dataclasses, use normal getattr
-                current_value = getattr(instance, name)
-
-                # Create new UnifiedParameterInfo with current value as default
-                unified_params[name] = UnifiedParameterInfo(
-                    name=param_info.name,
-                    param_type=param_info.param_type,
-                    default_value=current_value,
-                    is_required=param_info.is_required,
-                    description=param_info.description,
-                    source_type="dataclass_instance"
-                )
+        """Analyze a dataclass instance.
 
-        return unified_params
+        Always returns CLASS signature defaults (not instance values).
+        ObjectState extracts instance values separately via object.__getattribute__.
+        """
+        # Get the type and analyze it - returns CLASS signature defaults
+        dataclass_type = type(instance)
+        return UnifiedParameterAnalyzer._analyze_dataclass_type(dataclass_type)
     
     @staticmethod
     def analyze_nested(target: Union[Callable, Type, object], parent_info: Dict[str, UnifiedParameterInfo] = None) -> Dict[str, UnifiedParameterInfo]:

{python_introspect-0.1.2 → python_introspect-0.1.3/src/python_introspect.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.2
+Version: 0.1.3
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT
@@ -28,8 +28,9 @@ 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: mkdocs>=1.5.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.0.0; 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

{python_introspect-0.1.2 → python_introspect-0.1.3}/src/python_introspect.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/python_introspect/__init__.py
+src/python_introspect/enableable.py
 src/python_introspect/exceptions.py
 src/python_introspect/signature_analyzer.py
 src/python_introspect/unified_parameter_analyzer.py

{python_introspect-0.1.2 → python_introspect-0.1.3}/src/python_introspect.egg-info/requires.txt

@@ -7,5 +7,6 @@ black>=23.0
 mypy>=1.0
 
 [docs]
-mkdocs>=1.5.0
-mkdocs-material>=9.0.0
+sphinx>=7.0.0
+sphinx-rtd-theme>=2.0.0
+sphinx-autodoc-typehints>=1.24.0