Skip to content

Components API Reference

This page provides detailed API documentation for the Components module in SPOC.

Components Class

spoc.components.Components(*types)

Registry for named component‐types and their validation logic.

This class provides a registry for different types of components and manages their registration, validation, and metadata handling.

Examples:

>>> components = Components("command", "model")
>>> @components.register("command", config={"foo": "bar"})
>>> class Cmd:
>>>     pass

Parameters:

  • *types (str, default: () ) –

    Variable number of component type names to register initially

add_type(name, default_meta=None)

Declare a new component type, optionally with default metadata.

Parameters:

  • name (str) –

    Name of the component type to add.

  • default_meta (dict[str, Any] | None, default: None ) –

    Optional default metadata for this component type.

register(type_name, obj=None, *, config=None)

Decorator to mark something as a component of type_name.

Parameters:

  • type_name (str) –

    The component type to register as

  • obj (Any, default: None ) –

    Optional object to directly decorate

  • config (dict[str, Any] | None, default: None ) –

    Optional configuration dictionary for the component

Returns:

  • Any –

    A decorator function that registers an object as this component type

  • Any –

    or the decorated object if obj is directly provided

Raises:

  • KeyError –

    If the component type was not previously declared

is_spoc(obj)

Check whether obj has been marked as a spoc object.

Parameters:

  • obj (Any) –

    The object to check

Returns:

  • bool –

    True if the object has been decorated with the @component decorator

is_component(type_name, obj)

Validate that obj is a component of the declared type_name.

Parameters:

  • type_name (str) –

    The component type to check against

  • obj (Any) –

    The object to validate

Returns:

  • bool –

    True if the object is a component of the specified type

Raises:

  • KeyError –

    If the component type was not previously declared

get_info(obj)

Get the Component(Info) for a given object.

Parameters:

  • obj (Any) –

    The object to get component info for

Returns:

  • Internal | None –

    Internal metadata object if available, otherwise None

builder(the_object)

Build a Component object from a decorated object.

Parameters:

  • the_object (Any) –

    A component-decorated object

Returns:

  • Component –

    A Component instance with metadata extracted from the object

Raises:

  • AttributeError –

    If the object doesn't have required attributes

case_style(text, mode='snake') staticmethod

Convert a string to the given case style.

Parameters:

  • text (str) –

    The text to convert

  • mode (Literal['snake', 'camel', 'pascal', 'kebab'], default: 'snake' ) –

    The case style to convert to

Returns:

  • str –

    The converted string in the requested case style

Component Decorator

spoc.components.component(obj=None, *, config=None, metadata=None)

Mark a class or function as a "component" by attaching ComponentInfo.

This decorator attaches metadata to an object to identify it as a component in the SPOC framework. Can be used as either a simple decorator or a decorator factory with parameters.

Parameters:

  • obj (Any, default: None ) –

    The object to decorate (when used as @component)

  • config (dict[str, Any] | None, default: None ) –

    Optional configuration dictionary for the component

  • metadata (dict[str, Any] | None, default: None ) –

    Optional metadata dictionary for the component

Returns:

  • Any –

    The decorated object or a decorator function

Examples:

>>> @component(config={"key": "value"}, metadata={"type": "command"})
>>> class MyComponent:
>>>     pass
>>>
>>> # Or as direct call
>>> my_func = component(my_func, config={"timeout": 30})

Component Data Classes

spoc.components.Component(type, uri, app, name, object, internal) dataclass

Holds metadata and configuration for a registered component and the component that uses it.

Attributes:

  • type (str) –

    Component type identifier

  • uri (str) –

    Unique resource identifier for the component

  • app (str) –

    Application name the component belongs to

  • name (str) –

    Component name

  • object (Any) –

    The actual component object

  • internal (Internal) –

    Internal metadata container

spoc.components.Internal(config, metadata) dataclass

Holds metadata and configuration for a registered component.

Attributes:

  • config (dict[str, Any]) –

    Component configuration dictionary

  • metadata (dict[str, Any]) –

    Component metadata dictionary

Helper Functions

spoc.components.is_spoc(obj)

Check whether obj has been marked as a spoc object.

Parameters:

  • obj (Any) –

    The object to check

Returns:

  • bool –

    True if the object has been decorated with the @component decorator

spoc.components.is_component(obj, metadata)

Check whether obj has been marked as a component with the given metadata.

Parameters:

  • obj (Any) –

    The object to check

  • metadata (dict[str, Any]) –

    The metadata to match against

Returns:

  • bool –

    True if the object has been decorated with matching metadata