API Reference

Complete API documentation for SmartSeeds.

extract_kwargs

smartseeds.extract_kwargs(_adapter=None, _dictkwargs=None, **extraction_specs)[source]

A decorator that extracts **kwargs into sub-families by prefix.

This decorator allows methods to accept kwargs with prefixes (e.g., logging_level, cache_ttl) and automatically groups them into separate kwargs dictionaries (e.g., logging_kwargs, cache_kwargs).

Parameters:

_adapter (str | None) – Optional name of a method on self that will pre-process kwargs. The adapter method receives kwargs dict and can modify it in-place.
_dictkwargs (dict[str, Any] | None) – Optional dict to use instead of **extraction_specs. Useful for dynamic extraction specifications.
**extraction_specs (Any) – Extraction specifications where keys are prefix names. Values can be: - True: Extract and remove (pop=True) - dict: Custom options (slice_prefix, pop, is_list)

Return type:

Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

Returns:

Decorated function that extracts kwargs by prefix.

Example

>>> @extract_kwargs(palette=True, dialog=True, default=True)
... def my_method(self, pane, table=None,
...              palette_kwargs=None, dialog_kwargs=None, default_kwargs=None,
...              **kwargs):
...     pass
...
>>> # Call with prefixed parameters
>>> obj.my_method(palette_height='200px', palette_width='300px',
...              dialog_height='250px')
>>> # palette_kwargs={'height': '200px', 'width': '300px'}
>>> # dialog_kwargs={'height': '250px'}

Notes

The decorated function MUST have {prefix}_kwargs parameters for each prefix
Reserved keyword ‘class’ is automatically renamed to ‘_class’
Works with both class methods (with self) and standalone functions
Maintains 100% compatibility with original Genropy implementation

Function Signature

def extract_kwargs(
    _adapter: Optional[str] = None,
    _dictkwargs: Optional[Dict[str, Any]] = None,
    **extraction_specs: Any
) -> Callable[[F], F]

Parameters

_adapter : Optional[str]

Name of a method on self that will be called to pre-process kwargs before extraction. The adapter method receives the kwargs dict and can modify it in-place.

_dictkwargs : Optional[Dict[str, Any]]

Optional dictionary of extraction specifications. When provided, this is used instead of **extraction_specs. Useful for dynamic extraction specifications.

extraction_specs : Any

Keyword arguments where keys are prefix names and values specify extraction behavior:

True: Extract parameters with this prefix and remove them from source (pop=True)
dict: Custom extraction options (pop, slice_prefix, is_list)

Returns

Callable[[F], F]: Decorated function that performs kwargs extraction

Examples

See extract_kwargs Guide for detailed examples.

SmartOptions

class smartseeds.SmartOptions(incoming=None, defaults=None, *, ignore_none=False, ignore_empty=False, filter_fn=None)[source]

Convenience namespace for option management.

Parameters:

incoming (Mapping[str, Any] | None) – Mapping with runtime kwargs.
defaults (Mapping[str, Any] | None) – Mapping with baseline options.
ignore_none (bool) – Skip incoming entries where the value is None.
ignore_empty (bool) – Skip empty strings/collections from incoming entries.

__init__(incoming=None, defaults=None, *, ignore_none=False, ignore_empty=False, filter_fn=None)[source]

as_dict()[source]

Return a copy of current options.

Return type:: dict[str, Any]

Class Signature

class SmartOptions(SimpleNamespace):
    def __init__(
        self,
        incoming: Optional[Mapping[str, Any]] = None,
        defaults: Optional[Mapping[str, Any]] = None,
        *,
        ignore_none: bool = False,
        ignore_empty: bool = False,
        filter_fn: Optional[Callable[[str, Any], bool]] = None,
    )

Parameters

incoming : Optional[Mapping[str, Any]]: Mapping with runtime kwargs. Values override defaults after filtering. Can be None.
defaults : Optional[Mapping[str, Any]]: Mapping with baseline options. Can be None.
ignore_none : bool: When True, skip incoming entries where the value is None. Default: False.
ignore_empty : bool: When True, skip empty strings/collections from incoming entries. Default: False. Empty values include: "", [], (), {}, set(), etc.
filter_fn : Optional[Callable[[str, Any], bool]]: Optional custom filter function receiving (key, value) and returning True if the pair should be kept. Applied before ignore_none and ignore_empty.

Methods

as_dict() → Dict[str, Any]: Return a copy of current options as a dictionary.

Examples

See SmartOptions Guide for detailed examples.

safe_is_instance

smartseeds.safe_is_instance(obj, class_full_name)[source]

Return True if obj is an instance of the class identified by class_full_name or any of its subclasses — without importing the class.

Parameters:

obj (Any) – The object to check.
class_full_name (str) – The fully qualified class name, e.g. "mypkg.models.BaseNode".

Return type:

bool

Function Signature

def safe_is_instance(obj: Any, class_name: str) -> bool

Parameters

obj : Any: Object to check
class_name : str: Fully qualified class name (e.g., “builtins.int”, “package.module.ClassName”)

Returns

bool: True if obj is an instance of the class, False otherwise

Examples

See safe_is_instance Guide for detailed examples.

ASCII Table

render_ascii_table

smartseeds.ascii_table.render_ascii_table(data, max_width=None)[source]

Function Signature

def render_ascii_table(data: dict, max_width: Optional[int] = None) -> str

Parameters

data : dict

Table structure containing:

headers: List of column definitions (name, type, format, align, hierarchy)
rows: List of row data (list of values)
title (optional): Table title
max_width (optional): Maximum table width in characters

max_width : Optional[int]

Override max_width from data dict. Default: use data’s max_width or 120

Returns

str: Formatted ASCII table with borders and alignment

render_markdown_table

smartseeds.ascii_table.render_markdown_table(data)[source]

Function Signature

def render_markdown_table(data: dict) -> str

Parameters

data : dict: Table structure (same format as render_ascii_table)

Returns

str: Markdown-formatted table

Examples

See ASCII Table Guide for detailed examples.

Helper Functions

filtered_dict

def filtered_dict(
    data: Optional[Mapping[str, Any]],
    filter_fn: Optional[Callable[[str, Any], bool]] = None,
) -> Dict[str, Any]

Return a dict filtered through filter_fn.

Parameters:

data: Source mapping (can be None)
filter_fn: Optional filter callable (key, value) → bool

Returns: Filtered dictionary

make_opts

def make_opts(
    incoming: Optional[Mapping[str, Any]],
    defaults: Optional[Mapping[str, Any]] = None,
    *,
    filter_fn: Optional[Callable[[str, Any], bool]] = None,
    ignore_none: bool = False,
    ignore_empty: bool = False,
) -> SimpleNamespace

Merge incoming kwargs with defaults and return a SimpleNamespace.

Similar to SmartOptions but returns a plain SimpleNamespace without the as_dict() method.

dictExtract (Internal)

Internal utility function used by extract_kwargs. Not part of the public API.

def dictExtract(
    mydict: dict,
    prefix: str,
    pop: bool = False,
    slice_prefix: bool = True,
    is_list: bool = False
) -> dict

Returns a dict of items with keys starting with prefix.

Type Definitions

F = TypeVar('F', bound=Callable[..., Any])

Type variable for decorated function preservation.

API Reference

extract_kwargs

Function Signature

Parameters

Returns

Examples

SmartOptions

Class Signature

Parameters

Methods

Examples

safe_is_instance

Function Signature

Parameters

Returns

Examples

ASCII Table

render_ascii_table

Function Signature

Parameters

Returns

render_markdown_table

Function Signature

Parameters

Returns

Examples

Helper Functions

filtered_dict

make_opts

dictExtract (Internal)

Type Definitions

See Also