python-introspect 0.1.0__py3-none-any.whl

python_introspect/unified_parameter_analyzer.py

@@ -0,0 +1,275 @@
+"""Unified parameter analysis interface for all parameter sources in OpenHCS TUI.
+
+This module provides a single, consistent interface for analyzing parameters from:
+- Functions and methods
+- Dataclasses and their fields
+- Nested dataclass structures
+- Any callable or type with parameters
+
+Replaces the fragmented approach of SignatureAnalyzer vs FieldIntrospector.
+"""
+
+import inspect
+import dataclasses
+from typing import Dict, Union, Callable, Type, Any, Optional
+from dataclasses import dataclass
+
+from .signature_analyzer import SignatureAnalyzer, ParameterInfo
+
+
+@dataclass
+class UnifiedParameterInfo:
+    """Unified parameter information that works for all parameter sources."""
+    name: str
+    param_type: Type
+    default_value: Any
+    is_required: bool
+    description: Optional[str] = None
+    source_type: str = "unknown"  # "function", "dataclass", "nested"
+    
+    @classmethod
+    def from_parameter_info(cls, param_info: ParameterInfo, source_type: str = "function") -> "UnifiedParameterInfo":
+        """Convert from existing ParameterInfo to unified format."""
+        return cls(
+            name=param_info.name,
+            param_type=param_info.param_type,
+            default_value=param_info.default_value,
+            is_required=param_info.is_required,
+            description=param_info.description,
+            source_type=source_type
+        )
+
+
+class UnifiedParameterAnalyzer:
+    """Single interface for analyzing parameters from any source.
+    
+    This class provides a unified way to extract parameter information
+    from functions, dataclasses, and other parameter sources, ensuring
+    consistent behavior across the entire application.
+    """
+    
+    @staticmethod
+    def analyze(target: Union[Callable, Type, object], exclude_params: Optional[list] = None) -> Dict[str, UnifiedParameterInfo]:
+        """Analyze parameters from any source.
+
+        Args:
+            target: Function, method, dataclass type, or instance to analyze
+            exclude_params: Optional list of parameter names to exclude from analysis
+
+        Returns:
+            Dictionary mapping parameter names to UnifiedParameterInfo objects
+
+        Examples:
+            # Function analysis
+            param_info = UnifiedParameterAnalyzer.analyze(my_function)
+
+            # Dataclass analysis
+            param_info = UnifiedParameterAnalyzer.analyze(MyDataclass)
+
+            # Instance analysis
+            param_info = UnifiedParameterAnalyzer.analyze(my_instance)
+
+            # Instance analysis with exclusions (e.g., exclude 'func' from FunctionStep)
+            param_info = UnifiedParameterAnalyzer.analyze(step_instance, exclude_params=['func'])
+        """
+        if target is None:
+            return {}
+
+        # Determine the type of target and route to appropriate analyzer
+        if inspect.isfunction(target) or inspect.ismethod(target):
+            result = UnifiedParameterAnalyzer._analyze_callable(target)
+        elif inspect.isclass(target):
+            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
+                # 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)
+                except:
+                    # If we can't create a dummy instance, fall back to just analyzing __init__
+                    result = UnifiedParameterAnalyzer._analyze_callable(target.__init__)
+        elif dataclasses.is_dataclass(target):
+            # Instance of dataclass
+            result = UnifiedParameterAnalyzer._analyze_dataclass_instance(target)
+        else:
+            # Try to analyze as callable
+            if callable(target):
+                # Check if it has a __call__ method (callable object)
+                if hasattr(target, '__call__') and not inspect.isfunction(target):
+                    # It's a callable object, analyze its __call__ method
+                    result = UnifiedParameterAnalyzer._analyze_callable(target.__call__)
+                else:
+                    result = UnifiedParameterAnalyzer._analyze_callable(target)
+            else:
+                # For regular object instances (like step instances), analyze their class constructor
+                result = UnifiedParameterAnalyzer._analyze_object_instance(target)
+
+        # Apply exclusions if specified
+        if exclude_params:
+            result = {name: info for name, info in result.items() if name not in exclude_params}
+
+        return result
+    
+    @staticmethod
+    def _analyze_callable(callable_obj: Callable) -> Dict[str, UnifiedParameterInfo]:
+        """Analyze a callable (function, method, etc.)."""
+        # Use existing SignatureAnalyzer for callables
+        param_info_dict = SignatureAnalyzer.analyze(callable_obj)
+
+        # Convert to unified format
+        unified_params = {}
+        for name, param_info in param_info_dict.items():
+            unified_params[name] = UnifiedParameterInfo.from_parameter_info(
+                param_info,
+                source_type="function"
+            )
+
+        return unified_params
+    
+    @staticmethod
+    def _analyze_dataclass_type(dataclass_type: Type) -> Dict[str, UnifiedParameterInfo]:
+        """Analyze a dataclass type using existing SignatureAnalyzer infrastructure."""
+        # CRITICAL FIX: Use existing SignatureAnalyzer._analyze_dataclass method
+        # which already handles all the docstring extraction properly
+        param_info_dict = SignatureAnalyzer._analyze_dataclass(dataclass_type)
+
+        # Convert to unified format
+        unified_params = {}
+        for name, param_info in param_info_dict.items():
+            unified_params[name] = UnifiedParameterInfo.from_parameter_info(
+                param_info,
+                source_type="dataclass"
+            )
+
+        return unified_params
+
+    @staticmethod
+    def _analyze_object_instance(instance: object, use_signature_defaults: bool = False) -> Dict[str, UnifiedParameterInfo]:
+        """Analyze a regular object instance by examining its full inheritance hierarchy.
+
+        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)
+        all_params = {}
+
+        # Traverse MRO from most specific to most general (like dual-axis resolver)
+        for cls in instance_class.__mro__:
+            if cls == object:
+                continue
+
+            # Skip classes without custom __init__
+            if not hasattr(cls, '__init__') or cls.__init__ == object.__init__:
+                continue
+
+            try:
+                # Analyze this class's constructor
+                class_params = UnifiedParameterAnalyzer._analyze_callable(cls.__init__)
+
+                # Remove 'self' parameter
+                if 'self' in class_params:
+                    del class_params['self']
+
+                # Special handling for **kwargs - if we see 'kwargs', skip this class
+                # and let parent classes provide the actual parameters
+                if 'kwargs' in class_params and len(class_params) <= 2:
+                    # This class uses **kwargs, skip it and let parent classes define parameters
+                    continue
+
+                # 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
+                        all_params[param_name] = UnifiedParameterInfo(
+                            name=param_name,
+                            param_type=param_info.param_type,
+                            default_value=default_value,
+                            is_required=param_info.is_required,
+                            description=param_info.description,  # CRITICAL FIX: Include description
+                            source_type="object_instance"
+                        )
+
+            except Exception:
+                # Skip classes that can't be analyzed - this is legitimate since some classes
+                # in MRO might not have analyzable constructors (e.g., ABC, object)
+                continue
+
+        return all_params
+
+    @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"
+                )
+
+        return unified_params
+    
+    @staticmethod
+    def analyze_nested(target: Union[Callable, Type, object], parent_info: Dict[str, UnifiedParameterInfo] = None) -> Dict[str, UnifiedParameterInfo]:
+        """Analyze parameters with nested dataclass support.
+        
+        This method provides enhanced analysis that can handle nested dataclasses
+        and maintain parent context information.
+        
+        Args:
+            target: The target to analyze
+            parent_info: Optional parent parameter information for context
+            
+        Returns:
+            Dictionary of unified parameter information with nested support
+        """
+        base_params = UnifiedParameterAnalyzer.analyze(target)
+        
+        # For each parameter, check if it's a nested dataclass
+        enhanced_params = {}
+        for name, param_info in base_params.items():
+            enhanced_params[name] = param_info
+            
+            # If this parameter is a dataclass, mark it as having nested structure
+            if dataclasses.is_dataclass(param_info.param_type):
+                # Update source type to indicate nesting capability
+                enhanced_params[name] = UnifiedParameterInfo(
+                    name=param_info.name,
+                    param_type=param_info.param_type,
+                    default_value=param_info.default_value,
+                    is_required=param_info.is_required,
+                    description=param_info.description,
+                    source_type=f"{param_info.source_type}_nested"
+                )
+        
+        return enhanced_params
+
+
+# Backward compatibility aliases
+# These allow existing code to continue working while migration happens
+ParameterAnalyzer = UnifiedParameterAnalyzer
+analyze_parameters = UnifiedParameterAnalyzer.analyze

python_introspect-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: python-introspect
+Version: 0.1.0
+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.9
+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.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Dynamic: license-file
+
+# python-introspect
+
+**Pure Python introspection toolkit for function signatures, dataclasses, and type hints**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/trissim/python-introspect/actions/workflows/ci.yml/badge.svg)](https://github.com/trissim/python-introspect/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/python-introspect.svg)](https://badge.fury.io/py/python-introspect)
+
+## Features
+
+- 🔍 **Function/Method Signature Analysis** - Extract parameter info from any callable
+- 📦 **Dataclass Field Extraction** - Analyze dataclass fields and types
+- 📝 **Docstring Parsing** - Extract and parse docstrings (Google, NumPy, Sphinx styles)
+- 🏷️ **Type Hint Resolution** - Resolve complex type hints and annotations
+- 🎯 **Unified API** - Single interface for all parameter sources
+- 🚀 **Pure Python** - No external dependencies, pure stdlib
+
+## Installation
+
+```bash
+pip install python-introspect
+```
+
+## Quick Start
+
+```python
+from python_introspect import SignatureAnalyzer
+
+def example_function(name: str, age: int = 25, *, active: bool = True):
+    """
+    Example function with parameters.
+    
+    Args:
+        name: The person's name
+        age: The person's age
+        active: Whether the person is active
+    """
+    pass
+
+# Analyze the function
+analyzer = SignatureAnalyzer()
+params = analyzer.analyze_function(example_function)
+
+for param in params:
+    print(f"{param.name}: {param.annotation} = {param.default}")
+```
+
+## Use Cases
+
+- **Form Generation** - Generate UI forms from function signatures
+- **API Documentation** - Auto-generate API docs from code
+- **Configuration Validation** - Validate config against function parameters
+- **Dynamic UI** - Build dynamic UIs based on function signatures
+- **Parameter Analysis** - Analyze and validate function parameters
+
+## Documentation
+
+Full documentation available at: https://github.com/trissim/python-introspect
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/trissim/python-introspect.git
+cd python-introspect
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=python_introspect --cov-report=term --cov-report=html
+
+# Run linting and formatting checks
+ruff check src/ tests/
+black --check src/ tests/
+mypy src/python_introspect/
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Credits
+
+Developed by Tristan Simas as part of the OpenHCS project.

python_introspect-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+python_introspect/__init__.py,sha256=4b7Hho24-R0BwWnllBcn_oIi1Im2wlJfWyd_56kYRIc,1069
+python_introspect/exceptions.py,sha256=TG8Vo2JdArBbL8hlHmfmt31LtEKtGAuFEh2Rh07DQHs,488
+python_introspect/signature_analyzer.py,sha256=bjEnkVpsBm8wdEzpuVfki95azLf_ylbLAlRigXzZT08,51072
+python_introspect/unified_parameter_analyzer.py,sha256=npsl7FMyUSg4JjV56PMOHQzqo2z0ZldvR7ZTSgAvQjE,12156
+python_introspect-0.1.0.dist-info/licenses/LICENSE,sha256=xagEoeTAj1WT64RmyR3E6HH-eTGdgXN6gqPMUUt7L_Y,1070
+python_introspect-0.1.0.dist-info/METADATA,sha256=2ahrEP_hkwqkjePXy3--4ZUIcQPhCUUtporTZXGCPas,4372
+python_introspect-0.1.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+python_introspect-0.1.0.dist-info/top_level.txt,sha256=TZq9Yj1LeXI7A96PDqf7ZbWGSB1zLlQDww0esC91bwY,18
+python_introspect-0.1.0.dist-info/RECORD,,

python_introspect-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_introspect-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tristan Simas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_introspect-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+python_introspect