Plugin System

Core Classes

class sloth.mmcif.plugins.PluginFactory

Bases: object

Instance-level plugin registry for extending dot-notation access.

Plugins are registered with a name (the attribute that will appear on the data object) and a scope that determines which hierarchy level exposes the plugin:

• PluginScope.CATEGORY – available on Category objects

• PluginScope.BLOCK – available on DataBlock objects

• PluginScope.CONTAINER – available on MMCIFDataContainer objects

__init__()

register(name, plugin, *, scope)

Register a plugin.

Parameters:

• name (str) – The dot-notation attribute name (e.g. "validate").

• plugin – A Plugin instance or a plain callable (auto-wrapped as FunctionPlugin).

• scope (PluginScope) – A PluginScope member.

Return type:

None

get_wrapper(name, target, scope)

Return a bound PluginWrapper for name, or None.

Return type:

Optional[PluginWrapper]

Parameters:

• name (str)

• scope (PluginScope)

has_plugin(name, scope)

Return True if a plugin is registered for (name, scope).

Return type:

bool

Parameters:

• name (str)

• scope (PluginScope)

get_plugin(name, scope)

Return the raw Plugin for (name, scope), or None.

Return type:

Optional[Plugin]

Parameters:

• name (str)

• scope (PluginScope)

list_plugins(scope=None)

Return registered plugin names, optionally filtered by scope.

Return type:

List[str]

Parameters:

scope (PluginScope | None)

class sloth.mmcif.plugins.Plugin

Bases: ABC

Abstract base class for plugins that extend dot-notation functionality.

abstract create_wrapper(target)

Return a PluginWrapper (or subclass) bound to target.

Return type:

PluginWrapper

abstract execute(target, *args, **kwargs)

Run the plugin logic on target. Called by PluginWrapper.__call__().

Return type:

Any

class sloth.mmcif.plugins.PluginWrapper

Bases: object

Chainable wrapper returned when a plugin is accessed via dot-notation.

Calling the wrapper executes the plugin and returns self so that additional methods (defined by subclasses) can be chained:

block._atom_site.validate().against(block._entity)
value = block._atom_site.statistics().result

__init__(target, plugin)

Parameters:

plugin (Plugin)

property result: Any

The return value of the last __call__() invocation.

class sloth.mmcif.plugins.FunctionPlugin

Bases: Plugin

Adapter that wraps a plain callable as a Plugin.

__init__(func)

Parameters:

func (Callable)

create_wrapper(target)

Return a PluginWrapper (or subclass) bound to target.

Return type:

PluginWrapper

execute(target, *args, **kwargs)

Run the plugin logic on target. Called by PluginWrapper.__call__().

Return type:

Any

Validation as a Plugin Example

See the validation implementation in:

• sloth.mmcif.validator for ValidatorPlugin and CategoryValidator

• sloth.mmcif.rules for concrete validator implementations