MMCIFHandler β€” Main Entry Point

The MMCIFHandler is the primary interface for reading, writing, exporting, and importing mmCIF data.

from sloth import MMCIFHandler

handler = MMCIFHandler()
mmcif = handler.read("1abc.cif")
class sloth.mmcif.handler.MMCIFHandler[source]

Bases: object

A class to handle reading and writing mmCIF files with high-performance gemmi backend.

__init__()[source]

Initialize the handler with gemmi backend for optimal performance.

property plugin_factory: PluginFactory

The underlying plugin factory (read-only, for advanced use).

register(name, plugin, *, scope)[source]

Register a plugin for dot-notation access.

Parameters:

  • name (str) – The attribute name (e.g. "validate", "statistics").

  • plugin – A Plugin instance or a plain callable.

  • scope (PluginScope) – A PluginScope member.

Return type:

None

Example:

from sloth.mmcif import PluginScope
from sloth.mmcif.validator import ValidatorPlugin
handler.register("validate", ValidatorPlugin(), scope=PluginScope.CATEGORY)

# Or a simple function plugin
handler.register("stats", lambda cat: cat.row_count, scope=PluginScope.CATEGORY)
read(filename, categories=None)[source]

Parse an mmCIF file and returns a data container using gemmi’s high-performance backend.

Parameters:

  • filename (str) – The name of the file to parse.

  • categories (Optional[List[str]]) – The categories to parse. If None, all categories are included.

Returns:

The data container with lazy-loaded items.

Return type:

MMCIFDataContainer

write(mmcif, filename=None)[source]

Writes a data container to a file using gemmi’s high-performance backend.

Parameters:

  • mmcif (MMCIFDataContainer) – The data container to write.

  • filename (Optional[str]) – Optional filename to write to. If not provided, uses pre-set file object.

Return type:

None

Returns:

None

export(mmcif, file_path=None, **kwargs)[source]

Export mmCIF data to JSON format.

Parameters:

  • mmcif (MMCIFDataContainer) – The data container to export

  • file_path (Optional[str]) – Path to save the file (optional)

  • kwargs – Additional options (e.g., indent, quiet)

Returns:

String representation if no file_path provided, otherwise None

Return type:

Optional[str]

load(file_path, **kwargs)[source]

Import mmCIF data from JSON format.

Parameters:

  • file_path (str) – Path to the JSON file to import

  • kwargs – Additional options

Returns:

An MMCIFDataContainer instance

Return type:

MMCIFDataContainer

validate(data, *, relaxed=False)[source]

Validate mmCIF data recursively and return a ValidationReport.

Works on any level of the hierarchy β€” a single Category, a DataBlock, or an entire MMCIFDataContainer.

The rules that run depend on the relaxed flag:

  • default (relaxed=False): the full MmcifValidator dictionary + wwPDB suite runs first, followed by any user-registered custom validators.

  • relaxed (relaxed=True): only user-registered validators run. If none have been registered the report will be empty.

Parameters:
Return type:

ValidationReport

Returns:

A ValidationReport with all collected issues.

Example:

handler = MMCIFHandler()
report = handler.validate(container)              # full suite
report = handler.validate(container, relaxed=True) # user rules only