Validation

Exceptions

class sloth.mmcif.validator.ValidationError

Bases: Exception

Exception raised for validation errors.

__init__(message, path='', severity=ValidationSeverity.ERROR)

Initialize validation error.

Parameters:

• message (str) – Error message

• path (str) – Path where the error occurred (e.g., JSON path, category name)

• severity (ValidationSeverity) – Validation error severity

class sloth.mmcif.validator.ValidationSeverity

Bases: Enum

Severity levels for validation errors.

ERROR = 1

WARNING = 2

INFO = 3

Validator Plugin

class sloth.mmcif.validator.ValidatorPlugin

Bases: Plugin

Plugin for per-category validation with cross-checker support.

Multiple validators can be registered for the same category — they will all run in registration order.

__init__()

register_validator(category_name, validator_function)

Register a validator callable for a category name.

Multiple validators for the same category are allowed.

Return type:

None

Parameters:

• category_name (str)

• validator_function (Callable)

register_cross_checker(category_pair, cross_checker_function)

Register a cross-checker callable for a pair of category names.

Return type:

None

Parameters:

• category_pair (Tuple[str, str])

• cross_checker_function (Callable)

get_validators(category_name)

Return all validators for category_name.

Return type:

List[Callable]

Parameters:

category_name (str)

get_cross_checkers(category_pair)

Return all cross-checkers for category_pair.

Return type:

List[Callable]

Parameters:

category_pair (Tuple[str, str])

create_wrapper(target)

Return a PluginWrapper (or subclass) bound to target.

Return type:

CategoryValidator

execute(target, *args, **kwargs)

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

Return type:

Any

class sloth.mmcif.validator.CategoryValidator

Bases: PluginWrapper

Chainable wrapper for category validation with cross-checking.

against(other_category)

Execute cross-validation against other_category.

Return type:

CategoryValidator

Parameters:

other_category (Category)

Plugin System

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:

• "category" – available on Category objects

• "block" – available on DataBlock objects

• "container" – available on MMCIFDataContainer objects

VALID_SCOPES = {'block', 'category', 'container'}

__init__()

register(name, plugin, scope='category')

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 (str) – "category", "block", or "container".

Return type:

None

get_wrapper(name, target, scope)

Return a bound PluginWrapper for name, or None.

Return type:

Optional[PluginWrapper]

Parameters:

• name (str)

• scope (str)

has_plugin(name, scope)

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

Return type:

bool

Parameters:

• name (str)

• scope (str)

list_plugins(scope=None)

Return registered plugin names, optionally filtered by scope.

Return type:

List[str]

Parameters:

scope (str | 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