API Reference

This section contains the complete API reference for python-introspect.

python_introspect package

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.)

class python_introspect.SignatureAnalyzer

Bases: object

Universal analyzer for extracting parameter information from any target.

static analyze(target: Callable | Type | object, skip_first_param: bool | None = None) → Dict[str, ParameterInfo]

Extract parameter information from any target: function, constructor, dataclass, or instance.

Parameters:

• target – Function, constructor, dataclass type, or dataclass instance

• skip_first_param – Whether to skip the first parameter (after self/cls). If None, auto-detects based on context: - False for step constructors (all params are configuration) - True for image processing functions (first param is image data)

Returns:

Dict mapping parameter names to ParameterInfo

static extract_field_documentation(dataclass_type: type, field_name: str) → str | None

Extract documentation for a specific field from a dataclass.

This method tries multiple approaches to find documentation for a specific field: 1. Inline field documentation (AST parsing) 2. Field type documentation (for nested dataclasses) 3. Docstring parameters 4. Field metadata

Parameters:

• dataclass_type – The dataclass type containing the field

• field_name – Name of the field to get documentation for

Returns:

Field documentation string, or None if not found

static extract_field_documentation_from_context(field_name: str, context_types: list[type]) → str | None

Extract field documentation by searching through multiple dataclass types.

This method is useful when you don’t know exactly which dataclass contains a field, but you have a list of candidate types to search through.

Parameters:

• field_name – Name of the field to get documentation for

• context_types – List of dataclass types to search through

Returns:

Field documentation string, or None if not found

class python_introspect.ParameterInfo(name: str, param_type: type, default_value: Any, is_required: bool, description: str | None = None)

Bases: NamedTuple

Information about a parameter.

name: str

Alias for field number 0

param_type: type

Alias for field number 1

default_value: Any

Alias for field number 2

is_required: bool

Alias for field number 3

description: str | None

Alias for field number 4

class python_introspect.DocstringInfo(summary: str | None = None, description: str | None = None, parameters: Dict[str, str] | None = None, returns: str | None = None, examples: str | None = None)

Bases: NamedTuple

Information extracted from a docstring.

summary: str | None

Alias for field number 0

description: str | None

Alias for field number 1

parameters: Dict[str, str] | None

Alias for field number 2

returns: str | None

Alias for field number 3

examples: str | None

Alias for field number 4

property parameters_dict: Dict[str, str]

Get parameters as a dict, never None.

class python_introspect.DocstringExtractor

Bases: object

Extract structured information from docstrings.

static extract(target: Callable | type) → DocstringInfo

Extract docstring information from function or class.

Parameters:

target – Function, method, or class to extract docstring from

Returns:

DocstringInfo with parsed docstring components

python_introspect.register_namespace_provider(provider: Callable[[], Dict[str, Any]]) → None

Register a namespace provider for forward reference resolution.

The provider function should return a dict of names to types/values that will be available during get_type_hints() resolution.

Example

register_namespace_provider(lambda: {‘MyClass’: MyClass, ‘MyEnum’: MyEnum})

python_introspect.register_type_resolver(resolver: Callable[[type], type | None]) → None

Register a type resolver for lazy/proxy type unwrapping.

The resolver function should return the resolved type if it can handle the input type, or None to defer to other resolvers.

Example

def resolve_lazy(t):

if t.__name__.startswith(‘Lazy’):

return get_base_type(t)

return None

register_type_resolver(resolve_lazy)

class python_introspect.UnifiedParameterAnalyzer

Bases: object

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.

static analyze(target: Callable | Type | object, exclude_params: list | None = None) → Dict[str, UnifiedParameterInfo]

Analyze parameters from any source.

Parameters:

• 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’])

static analyze_nested(target: 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.

Parameters:

• target – The target to analyze

• parent_info – Optional parent parameter information for context

Returns:

Dictionary of unified parameter information with nested support

class python_introspect.UnifiedParameterInfo(name: str, param_type: Type, default_value: Any, is_required: bool, description: str | None = None, source_type: str = 'unknown')

Bases: object

Unified parameter information that works for all parameter sources.

name: str

param_type: Type

default_value: Any

is_required: bool

description: str | None = None

source_type: str = 'unknown'

classmethod from_parameter_info(param_info: ParameterInfo, source_type: str = 'function') → UnifiedParameterInfo

Convert from existing ParameterInfo to unified format.

__init__(name: str, param_type: Type, default_value: Any, is_required: bool, description: str | None = None, source_type: str = 'unknown') → None

exception python_introspect.IntrospectionError

Bases: Exception

Base exception for introspection errors.

exception python_introspect.SignatureAnalysisError

Bases: IntrospectionError

Exception raised when signature analysis fails.

exception python_introspect.DocstringParsingError

Bases: IntrospectionError

Exception raised when docstring parsing fails.

exception python_introspect.TypeResolutionError

Bases: IntrospectionError

Exception raised when type resolution fails.

class python_introspect.Enableable(enabled: bool = True)

Bases: ABC

Mixin indicating an object participates in enabled semantics.

enabled: bool = True

__init__(enabled: bool = True) → None

python_introspect.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.

python_introspect.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.

Submodules

python_introspect.signature_analyzer

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.

python_introspect.signature_analyzer.register_namespace_provider(provider: Callable[[], Dict[str, Any]]) → None

Register a namespace provider for forward reference resolution.

The provider function should return a dict of names to types/values that will be available during get_type_hints() resolution.

Example

register_namespace_provider(lambda: {‘MyClass’: MyClass, ‘MyEnum’: MyEnum})

python_introspect.signature_analyzer.register_type_resolver(resolver: Callable[[type], type | None]) → None

Register a type resolver for lazy/proxy type unwrapping.

The resolver function should return the resolved type if it can handle the input type, or None to defer to other resolvers.

Example

def resolve_lazy(t):

if t.__name__.startswith(‘Lazy’):

return get_base_type(t)

return None

register_type_resolver(resolve_lazy)

class python_introspect.signature_analyzer.AnalysisConstants(INIT_METHOD_SUFFIX: str = '.__init__', SELF_PARAM: str = 'self', CLS_PARAM: str = 'cls', DUNDER_PREFIX: str = '__', DUNDER_SUFFIX: str = '__')

Bases: object

Constants for signature analysis to eliminate magic strings.

INIT_METHOD_SUFFIX: str = '.__init__'

SELF_PARAM: str = 'self'

CLS_PARAM: str = 'cls'

DUNDER_PREFIX: str = '__'

DUNDER_SUFFIX: str = '__'

__init__(INIT_METHOD_SUFFIX: str = '.__init__', SELF_PARAM: str = 'self', CLS_PARAM: str = 'cls', DUNDER_PREFIX: str = '__', DUNDER_SUFFIX: str = '__') → None

class python_introspect.signature_analyzer.ParameterInfo(name: str, param_type: type, default_value: Any, is_required: bool, description: str | None = None)

Bases: NamedTuple

Information about a parameter.

name: str

Alias for field number 0

param_type: type

Alias for field number 1

default_value: Any

Alias for field number 2

is_required: bool

Alias for field number 3

description: str | None

Alias for field number 4

class python_introspect.signature_analyzer.DocstringInfo(summary: str | None = None, description: str | None = None, parameters: Dict[str, str] | None = None, returns: str | None = None, examples: str | None = None)

Bases: NamedTuple

Information extracted from a docstring.

summary: str | None

Alias for field number 0

description: str | None

Alias for field number 1

parameters: Dict[str, str] | None

Alias for field number 2

returns: str | None

Alias for field number 3

examples: str | None

Alias for field number 4

property parameters_dict: Dict[str, str]

Get parameters as a dict, never None.

class python_introspect.signature_analyzer.DocstringExtractor

Bases: object

Extract structured information from docstrings.

static extract(target: Callable | type) → DocstringInfo

Extract docstring information from function or class.

Parameters:

target – Function, method, or class to extract docstring from

Returns:

DocstringInfo with parsed docstring components

class python_introspect.signature_analyzer.SignatureAnalyzer

Bases: object

Universal analyzer for extracting parameter information from any target.

static analyze(target: Callable | Type | object, skip_first_param: bool | None = None) → Dict[str, ParameterInfo]

Extract parameter information from any target: function, constructor, dataclass, or instance.

Parameters:

• target – Function, constructor, dataclass type, or dataclass instance

• skip_first_param – Whether to skip the first parameter (after self/cls). If None, auto-detects based on context: - False for step constructors (all params are configuration) - True for image processing functions (first param is image data)

Returns:

Dict mapping parameter names to ParameterInfo

static extract_field_documentation(dataclass_type: type, field_name: str) → str | None

Extract documentation for a specific field from a dataclass.

This method tries multiple approaches to find documentation for a specific field: 1. Inline field documentation (AST parsing) 2. Field type documentation (for nested dataclasses) 3. Docstring parameters 4. Field metadata

Parameters:

• dataclass_type – The dataclass type containing the field

• field_name – Name of the field to get documentation for

Returns:

Field documentation string, or None if not found

static extract_field_documentation_from_context(field_name: str, context_types: list[type]) → str | None

Extract field documentation by searching through multiple dataclass types.

This method is useful when you don’t know exactly which dataclass contains a field, but you have a list of candidate types to search through.

Parameters:

• field_name – Name of the field to get documentation for

• context_types – List of dataclass types to search through

Returns:

Field documentation string, or None if not found

python_introspect.unified_parameter_analyzer

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.

class python_introspect.unified_parameter_analyzer.UnifiedParameterInfo(name: str, param_type: Type, default_value: Any, is_required: bool, description: str | None = None, source_type: str = 'unknown')

Bases: object

Unified parameter information that works for all parameter sources.

name: str

param_type: Type

default_value: Any

is_required: bool

description: str | None = None

source_type: str = 'unknown'

classmethod from_parameter_info(param_info: ParameterInfo, source_type: str = 'function') → UnifiedParameterInfo

Convert from existing ParameterInfo to unified format.

__init__(name: str, param_type: Type, default_value: Any, is_required: bool, description: str | None = None, source_type: str = 'unknown') → None

class python_introspect.unified_parameter_analyzer.UnifiedParameterAnalyzer

Bases: object

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.

static analyze(target: Callable | Type | object, exclude_params: list | None = None) → Dict[str, UnifiedParameterInfo]

Analyze parameters from any source.

Parameters:

• 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’])

static analyze_nested(target: 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.

Parameters:

• target – The target to analyze

• parent_info – Optional parent parameter information for context

Returns:

Dictionary of unified parameter information with nested support

python_introspect.unified_parameter_analyzer.ParameterAnalyzer

alias of UnifiedParameterAnalyzer

python_introspect.unified_parameter_analyzer.analyze_parameters(target: Callable | Type | object, exclude_params: list | None = None) → Dict[str, UnifiedParameterInfo]

Analyze parameters from any source.

Parameters:

• 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’])

python_introspect.exceptions

Exceptions for python-introspect.

exception python_introspect.exceptions.IntrospectionError

Bases: Exception

Base exception for introspection errors.

exception python_introspect.exceptions.SignatureAnalysisError

Bases: IntrospectionError

Exception raised when signature analysis fails.

exception python_introspect.exceptions.DocstringParsingError

Bases: IntrospectionError

Exception raised when docstring parsing fails.

exception python_introspect.exceptions.TypeResolutionError

Bases: IntrospectionError

Exception raised when type resolution fails.