Validator

Exceptions & Enums

class sloth.mmcif.validator.ValidationError[source]

Bases: Exception

Exception raised for validation errors.

__init__(message, path='', severity=ValidationSeverity.ERROR)[source]

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[source]

Bases: Enum

Severity levels for validation errors.

ERROR = 1

WARNING = 2

INFO = 3

Validation Report

class sloth.mmcif.validator.ValidationReport[source]

Bases: object

Collects validation errors from a recursive validation pass.

Returned by DataBlockValidator.execute(), ContainerValidator.execute(), and ValidatorPlugin.validate().

__init__()[source]

add(error)[source]

Append a single ValidationError.

Return type:: None
Parameters:: error (ValidationError)

extend(other)[source]

Merge all issues from other into this report.

Return type:: None
Parameters:: other (ValidationReport)

property all_issues: List[ValidationError]: Every collected issue regardless of severity.

property errors: List[ValidationError]: Only ValidationSeverity.ERROR issues.

property warnings: List[ValidationError]: Only ValidationSeverity.WARNING issues.

property is_valid: bool: True when no ERROR-level issues are present.

raise_on_error()[source]

Raise ValidationError if any errors are present.

Return type:: None

Validator Plugin

class sloth.mmcif.validator.ValidatorPlugin[source]

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.

Use validate() for a standalone convenience entry-point that accepts any level of the data hierarchy and returns a ValidationReport.

__init__()[source]

register_validator(category_name, validator_function)[source]

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)[source]

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

Return type:

None

Parameters:

category_pair (Tuple[str, str])
cross_checker_function (Callable)

merge(other)[source]

Return a new ValidatorPlugin whose rules are self + other.

Rules from other run after rules from self for each category / cross-checker pair. Neither the receiver nor the argument is mutated.

Return type:: ValidatorPlugin
Parameters:: other (ValidatorPlugin)

get_validators(category_name)[source]

Return all validators for category_name.

Return type:: List[Callable]
Parameters:: category_name (str)

get_cross_checkers(category_pair)[source]

Return all cross-checkers for category_pair.

Return type:: List[Callable]
Parameters:: category_pair (Tuple[str, str])

create_wrapper(target)[source]

Return a PluginWrapper (or subclass) bound to target.

Return type:: CategoryValidator

execute(target, *args, **kwargs)[source]

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

Return type:: Any

validate(data)[source]

Validate data and return a ValidationReport.

Accepts any level of the hierarchy:

Category — runs per-category validators only.
DataBlock — runs per-category validators and cross-checkers for all categories in the block.
MMCIFDataContainer — validates each block in turn.

Parameters:: data (Union[Category, DataBlock, MMCIFDataContainer]) – The data object to validate.
Return type:: ValidationReport
Returns:: A ValidationReport with all collected issues.

class sloth.mmcif.validator.CategoryValidator[source]

Bases: PluginWrapper

Chainable wrapper for category validation with cross-checking.

against(other_category)[source]

Execute cross-validation against other_category.

Return type:: CategoryValidator
Parameters:: other_category (Category)

Multi-Level Validators

class sloth.mmcif.validator.DataBlockValidator[source]

Bases: Plugin

Validates every category in a DataBlock.

Runs all per-category validators and cross-checkers registered on the wrapped ValidatorPlugin, collecting errors into a ValidationReport rather than raising on the first failure.

__init__(category_validator)[source]

Parameters:: category_validator (ValidatorPlugin)

create_wrapper(target)[source]

Return a PluginWrapper (or subclass) bound to target.

Return type:: BlockValidationWrapper
Parameters:: target (DataBlock)

execute(target, *args, **kwargs)[source]

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

Return type:: ValidationReport
Parameters:: target (DataBlock)

class sloth.mmcif.validator.BlockValidationWrapper[source]

Bases: PluginWrapper

Chainable wrapper for block-level validation.

property report: ValidationReport | None: Shortcut for result — the ValidationReport.

property is_valid: bool | None: True when validation passed (no errors). None if not yet run.

class sloth.mmcif.validator.ContainerValidator[source]

Bases: Plugin

Validates every block in an MMCIFDataContainer.

Delegates to a DataBlockValidator for each block and merges all results into a single ValidationReport.

__init__(block_validator)[source]

Parameters:: block_validator (DataBlockValidator)

create_wrapper(target)[source]

Return a PluginWrapper (or subclass) bound to target.

Return type:: ContainerValidationWrapper
Parameters:: target (MMCIFDataContainer)

execute(target, *args, **kwargs)[source]

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

Return type:: ValidationReport
Parameters:: target (MMCIFDataContainer)

class sloth.mmcif.validator.ContainerValidationWrapper[source]

Bases: PluginWrapper

Chainable wrapper for container-level validation.

property report: ValidationReport | None: Shortcut for result — the ValidationReport.

property is_valid: bool | None: True when validation passed (no errors). None if not yet run.

Validator Classes

class sloth.mmcif.validator.SchemaValidator[source]

Bases: ValidatorPlugin

Validator auto-generated from an mmCIF dictionary.

Parses a .dic file via SLOTH’s DictionaryParser, retains the schema metadata, and registers validators from it:

mandatory items — from _item.mandatory_code
enumeration — from _item_enumeration.value
type regex — from _item_type_list.construct
foreign-key integrity — single-key relationships
composite-key integrity — multi-key relationships
parent/child category presence — parent must exist when child does

Parameters:

dict_path (str, optional) – Path to an mmCIF dictionary. Defaults to the bundled mmcif_pdbx_v50.dic.
quiet (bool) – Suppress progress messages from the dictionary parser (default True).
Usage:: –
from sloth.mmcif.validator import SchemaValidator

v = SchemaValidator() # schema-only rules report = v.validate(block) # validate a DataBlock

__init__(dict_path=None, *, quiet=True)[source]

Parameters:

dict_path (str | None)
quiet (bool)

class sloth.mmcif.validator.MMCIFValidator[source]

Bases: SchemaValidator

Full wwPDB validator = dictionary schema + deposition business rules.

Inherits all schema-level checks from SchemaValidator, then registers wwPDB-specific rules from the declarative tables below.

Parameters:

dict_path (str, optional) – Path to an mmCIF dictionary. Defaults to the bundled mmcif_pdbx_v50.dic.
quiet (bool) – Suppress dictionary parser progress messages (default True).
Usage:: –
from sloth.mmcif.validator import MMCIFValidator

v = MMCIFValidator() # full wwPDB + dictionary rules report = v.validate(container) # validate an entire container

__init__(dict_path=None, *, quiet=True)[source]

Parameters:

dict_path (str | None)
quiet (bool)

Single-Category Rule Factories

sloth.mmcif.validator.mandatory_items(items, exclude=(), severity=ValidationSeverity.ERROR)[source]

Items that must be non-null when the category is present.

Return type:

Callable[[Category], None]

Parameters:

items (Sequence[str])
exclude (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.one_of_following(items, severity=ValidationSeverity.ERROR)[source]

At least one of items must be non-null.

Return type:

Callable[[Category], None]

Parameters:

items (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.value_length(item, min_len=None, max_len=None, severity=ValidationSeverity.WARNING)[source]

String length bounds for an item.

Return type:

Callable[[Category], None]

Parameters:

item (str)
min_len (int | None)
max_len (int | None)
severity (ValidationSeverity)

sloth.mmcif.validator.value_range(item, min_val=None, max_val=None, severity=ValidationSeverity.WARNING)[source]

Numeric bounds for an item.

Return type:

Callable[[Category], None]

Parameters:

item (str)
min_val (float | None)
max_val (float | None)
severity (ValidationSeverity)

sloth.mmcif.validator.conditional_mandatory(required_items, when_item, when_values, severity=ValidationSeverity.ERROR)[source]

Items that must be non-null when when_item has one of when_values.

Return type:

Callable[[Category], None]

Parameters:

required_items (Sequence[str])
when_item (str)
when_values (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.regex_check(item, pattern, error_text='', severity=ValidationSeverity.ERROR)[source]

Values of item must match pattern.

Return type:

Callable[[Category], None]

Parameters:

item (str)
pattern (str)
error_text (str)
severity (ValidationSeverity)

sloth.mmcif.validator.ordering_check(item_a, item_b, op='<', severity=ValidationSeverity.WARNING)[source]

Numeric ordering: item_a op item_b (per row).

Parameters:

op (str) – One of "<", "<=", ">", ">=".
item_a (str)
item_b (str)
severity (ValidationSeverity)

Return type:

Callable[[Category], None]

sloth.mmcif.validator.allowed_pairs(item_a, item_b, valid_mapping, severity=ValidationSeverity.ERROR)[source]

Restrict allowed (item_a, item_b) value combinations per row.

valid_mapping maps each value of item_a to the sequence of allowed values in item_b.

Return type:

Callable[[Category], None]

Parameters:

item_a (str)
item_b (str)
valid_mapping (Mapping[str, Sequence[str]])
severity (ValidationSeverity)

sloth.mmcif.validator.min_rows(n, severity=ValidationSeverity.ERROR)[source]

Category must contain at least n rows.

Return type:

Callable[[Category], None]

Parameters:

n (int)
severity (ValidationSeverity)

sloth.mmcif.validator.enumeration_check(item, allowed_values, severity=ValidationSeverity.ERROR)[source]

Values of item must be in allowed_values.

Mirrors the dictionary _item_enumeration validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category], None]

Parameters:

item (str)
allowed_values (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.type_check(item, type_pattern, type_name='', severity=ValidationSeverity.ERROR)[source]

Values of item must match the data-type regex type_pattern.

Mirrors the dictionary _item_type_list.construct validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category], None]

Parameters:

item (str)
type_pattern (str)
type_name (str)
severity (ValidationSeverity)

Cross-Category Rule Factories

sloth.mmcif.validator.foreign_key(child_item, parent_item, severity=ValidationSeverity.ERROR)[source]

Cross-checker: every non-null value of child_item in cat_a must exist in parent_item of cat_b.

Mirrors the FK integrity check from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

child_item (str)
parent_item (str)
severity (ValidationSeverity)

sloth.mmcif.validator.parent_child(severity=ValidationSeverity.ERROR)[source]

Cross-checker: if child category (cat_a) is present, parent category (cat_b) must also be present and non-empty.

Mirrors the parent/child category validation from the PDBeurope/mmcif-validator.

Return type:: Callable[[Category, Category], None]
Parameters:: severity (ValidationSeverity)

sloth.mmcif.validator.composite_key(child_items, parent_items, severity=ValidationSeverity.ERROR)[source]

Cross-checker: each combination of child_items in cat_a must exist as a matching combination of parent_items in cat_b.

Mirrors the composite key validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

child_items (Sequence[str])
parent_items (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.oper_expression(expression_item='oper_expression', oper_list_item='id', severity=ValidationSeverity.ERROR)[source]

Cross-checker: validate that operation expression references in cat_a all resolve to valid IDs in cat_b (_pdbx_struct_oper_list).

Parses expressions like (1-60), (1,2,5), (X0)(1-5,11-15).

Mirrors the oper_expression validation from the PDBeurope/mmcif-validator.

Return type:

Callable[[Category, Category], None]

Parameters:

expression_item (str)
oper_list_item (str)
severity (ValidationSeverity)

sloth.mmcif.validator.cross_mandatory(required_items, severity=ValidationSeverity.ERROR)[source]

Cross-checker: required_items must exist in the second category.

Return type:

Callable[[Category, Category], None]

Parameters:

required_items (Sequence[str])
severity (ValidationSeverity)

sloth.mmcif.validator.cross_ordering(item_a, item_b, op='<', severity=ValidationSeverity.WARNING)[source]

Cross-checker: compare a value in cat_a against a value in cat_b.

Return type:

Callable[[Category, Category], None]

Parameters:

item_a (str)
item_b (str)
op (str)
severity (ValidationSeverity)