Changelog

v0.8.1 (2026-04-09)

Fix README: replace stale handler.validate() examples with MMCIFValidator().validate() API.

Breaking changes

handler.register() and handler.validate() have been removed. Registration now lives on model instances: category.register("validate", vp), block.register("validate", bv), container.register("validate", cv).
PluginScope enum has been removed. Scope is inferred from which model class register() is called on.
PluginFactory no longer accepts a scope parameter — plugins are stored in a flat name → Plugin mapping.
Renames: DictionaryValidator → SchemaValidator, MmcifValidator → MMCIFValidator, BlockValidator → DataBlockValidator.

New features

Model-level plugin registration — register(name, plugin) is now a method on Category, DataBlock, and MMCIFDataContainer (inherited from DataContainer).
Standalone ``validate()`` — call MMCIFValidator().validate(data) directly without any handler involvement. Accepts a Category, DataBlock, or MMCIFDataContainer.
Plugin wiring (register(), _lookup_plugin()) is now defined once in the DataContainer base class.

Breaking changes

Attribute access on non-existent categories / blocks now returns a lightweight pending proxy (_PendingCategory / _PendingDataBlock) that auto-commits on write and raises AttributeError with fuzzy suggestions on read.
sloth.mmcif.rules module merged into sloth.mmcif.validator. All rule factories and validator classes now live in a single module.

New features

Multi-level validation — ValidatorPlugin, DataBlockValidator, and ContainerValidator validate a Category, DataBlock, or MMCIFDataContainer and return a ValidationReport with .errors, .warnings, .is_valid, and .raise_on_error() helpers.
Schema-aware warnings — assigning an unknown item to a known category (or creating an unknown category) emits a SchemaWarning with “Did you mean …?” suggestions drawn from the bundled mmCIF dictionary.
Fuzzy matching in error messages — AttributeError on Category, DataBlock, and MMCIFDataContainer includes difflib.get_close_matches suggestions.
Tab completion — __dir__() on all three model classes exposes item names, category names, block names, and registered plugin names for IPython / Jupyter tab completion.
``ValidationSeverity`` enum — ERROR, WARNING, INFO severity levels accepted by every rule factory.
``ValidationReport`` — accumulator for ValidationError instances with filtering by severity.
``DataBlockValidator`` / ``ContainerValidator`` — plugins that run all per-category validators + cross-category checkers across an entire block or container.
``DataSourceFormat`` enum moved to defaults.

Bug fixes

DictionaryParser: fix multiline value detection (now handles continuation lines whose first token is a bare value, not a key).
DictionaryParser: fix multi-loop storage so that successive loop_ blocks in the same save frame no longer overwrite each other.
DictionaryParser: deterministic graph-based nesting resolves composite primary-key categories that previously caused non-deterministic parent/child ordering.

Chores

Hoist non-conditional inline imports to module level across source and test files.
Centralise all enums (DataSourceFormat, ValidationSeverity) in sloth.mmcif.defaults.
CI: weekly GitHub Actions workflow to auto-update the bundled mmCIF dictionary from wwPDB.

Validation rules module (sloth.mmcif.rules):
- SchemaValidator: auto-generates checks from the bundled mmCIF dictionary via DictionaryParser (mandatory items, enumerations, type-regex patterns, FK/composite-key integrity, parent/child presence)
- MMCIFValidator: extends SchemaValidator with wwPDB deposition business rules expressed as declarative class-level data tables
- 18 composable rule factory functions for custom validation
ValidatorPlugin supports multiple validators per category (list-based)
Generic plugin system: PluginFactory, Plugin, PluginWrapper, FunctionPlugin
Streamlined registration: handler.register("_cat", func) for validators, tuples for cross-checkers
Delete support: del block._category, block.delete("_category"), same for items
Update docs, cookbook, and API reference for new plugin API