SLOTH Documentation

Lazy by design. Fast by default.

SLOTH (Structural Loader with On-demand Traversal Handling) is a high-performance mmCIF parser for structural biology workflows. Built on the C++ gemmi backend, SLOTH performs eager parsing and lazy object construction — efficient for both large-scale pipelines and interactive exploration.

Key features:

• High-speed parsing via the gemmi C++ backend

• Lazy construction of row and item objects for memory efficiency

• Pythonic dot-notation access to mmCIF data

• Pluggable validation system with cross-category support

• JSON export/import with automatic relationship resolution

from sloth import MMCIFHandler

handler = MMCIFHandler()
mmcif = handler.read("1abc.cif")

print(mmcif.data_1ABC._struct.title[0])
print(mmcif.data_1ABC._atom_site.Cartn_x[0])

Getting Started

User Guide

• Installation
  • From TestPyPI
  • From Source
  • Requirements
• Quick Start
  • Parsing an mmCIF File
  • Selective Parsing
  • Writing mmCIF Files
  • Quick JSON Export
  • Quick JSON Import
• Usage Guide
  • Access Patterns
  • Data Creation
  • Safety Features
  • Deleting Data
• Validation
  • Quick Start
  • Validator Classes
  • Single-Category Validation
  • Cross-Category Validation
  • Custom Rules with Factories
  • Validation Severity
  • Extending MMCIFValidator
• Import & Export
  • JSON Export
  • JSON Import
  • Round-trip Verification
  • Advanced Export Options
• 🦥 SLOTH Cookbook
  • Structural Loader with On-demand Traversal Handling
  • Table of Contents
  • 1. Setup and Installation
  • 2. Import Required Libraries
  • 3. Understanding SLOTH’s Core Components
  • 4. Parsing mmCIF Files with Embedded Data
  • 5. Exploring Data Structures with Dot Notation
  • 6. Demonstrating 2D Slicing
  • 7. Validating mmCIF Data
  • 8. Modifying mmCIF Data
  • 9. Creating Sample Data - Manual Approach
  • 10. Creating Sample Data - Programmatic Approach
  • 11. Creating Sample Data - Auto-Creation with Dot Notation ✨
  • 12. Exporting to Nested JSON
  • 13. Importing from JSON
  • 14. Round-Trip Validation
  • 15. Writing Modified mmCIF Files
  • 16. Complete Workflow Example
  • Summary

API Reference

• MMCIFHandler — Main Entry Point
  • MMCIFHandler
• Data Models
  • Enumerations
  • Abstract Base Classes
  • Top-level Container
  • Data Block
  • Category
  • Row
  • Item
  • Lazy Loading Internals
• MMCIFParser — File Parsing
  • MMCIFParser
• MMCIFWriter — File Writing
  • MMCIFWriter
• JSONExporter — JSON Export
  • JSONExporter
• JSONImporter — JSON Import
  • JSONImporter
• Serializer & Relationship Resolution
  • Cache Management
  • Dictionary Parsing
  • Mapping Generation
  • Relationship Resolution
  • Ownership Analysis
  • Nesting
• Plugin System
  • Core Classes
  • Model-Level Registration
  • Validation as a Plugin Example
• Validator
  • Exceptions & Enums
  • Validation Report
  • Validator Plugin
  • Multi-Level Validators
  • Validator Classes
  • Single-Category Rule Factories
  • Cross-Category Rule Factories
• Base Classes
  • BaseParser
  • BaseWriter
  • BaseImporter
  • BaseExporter

Project

• Changelog
• Contributing

Indices and tables

• Index

• Module Index

• Search Page