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__(strict=False)[source]

Initialize the handler with gemmi backend for optimal performance.

Parameters:

strict (bool) – If True, prevent silent auto-creation of categories and data blocks on attribute access (sets auto_create=False) and register the default wwPDB validation rules via MmcifValidator.

property plugin_factory: PluginFactory

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

register(name, plugin, *, scope='category')[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 (str) – "category", "block", or "container".

Return type:

None

Example:

from sloth.mmcif.validator import ValidatorPlugin
handler.register("validate", ValidatorPlugin())

# Or a simple function plugin
handler.register("stats", lambda cat: cat.row_count)
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