Serializer & Relationship Resolution

This module provides the internal machinery for resolving mmCIF dictionary relationships and building nested JSON structures.

Cache Management

class sloth.mmcif.serializer.CacheManager[source]

Bases: object

Unified cache manager that combines global in-memory caching with optional disk persistence.

__init__(cache_dir=None, enable_disk_cache=True)[source]

Parameters:

cache_dir (str | None)
enable_disk_cache (bool)

get(cache_type, key)[source]

Get from global cache first, then fallback to disk if enabled

Return type:

Optional[Any]

Parameters:

cache_type (str)
key (str)

set(cache_type, key, value)[source]

Store in global cache and optionally on disk

Return type:

None

Parameters:

cache_type (str)
key (str)
value (Any)

static clear_global_caches()[source]: Clear all global caches

sloth.mmcif.serializer.get_cache_manager(cache_dir=None)[source]

Get or create the default cache manager

Return type:: CacheManager
Parameters:: cache_dir (str | None)

Dictionary Parsing

class sloth.mmcif.serializer.DictionaryParser[source]

Bases: object

Parses mmCIF dictionary files

__init__(cache_manager, quiet=False)[source]

Parameters:

cache_manager (CacheManager)
quiet (bool)

parse(source)[source]

Parse dictionary from path (renamed from ‘source’ to ‘dict_path’ for clarity)

Return type:: Dict[str, Any]
Parameters:: source (str | Path)

Mapping Generation

class sloth.mmcif.serializer.MappingGenerator[source]

Bases: object

Generates mapping rules from mmCIF dictionary metadata

__init__(dict_parser, cache_manager, quiet=False)[source]

Parameters:

dict_parser (DictionaryParser)
cache_manager (CacheManager)
quiet (bool)

get_mapping_rules()[source]

Return type:: Dict[str, Any]

Relationship Resolution

class sloth.mmcif.serializer.RelationshipResolver[source]

Bases: object

Resolves entity relationships for nested JSON output from mmCIF data

__init__(mapping_generator)[source]

Parameters:: mapping_generator (MappingGenerator)

set_denormalize(value)[source]

Enable/disable full denormalization mode

Parameters:: value (bool)

property mapping_rules: Dict[str, Any]: Cached access to mapping rules

resolve_relationships(mmcif_data)[source]

Resolve relationships directly from mmCIF data to create nested JSON

Return type:: Dict[str, Any]
Parameters:: mmcif_data (MMCIFDataContainer)

class sloth.mmcif.serializer.RelationshipMetadata[source]

Bases: object

Formal relationship metadata extracted from dictionary

__init__(child_cat, child_field, parent_cat, parent_field, relationship_type=RelationshipType.UNKNOWN)[source]

Parameters:

child_cat (str)
child_field (str)
parent_cat (str)
parent_field (str)
relationship_type (RelationshipType)

class sloth.mmcif.serializer.RelationshipConstraint[source]

Bases: object

Represents a formal constraint on relationships

__init__(metadata, is_validated=False)[source]

Parameters:

metadata (RelationshipMetadata)
is_validated (bool)

validate(data)[source]

Validate constraint against actual data

Return type:: bool
Parameters:: data (Dict[str, Any])

Ownership Analysis

class sloth.mmcif.serializer.OwnershipAnalyzer[source]

Bases: object

Analyzes relationships to determine ownership using structural algorithms.

Rule Hierarchy (applied in order): 1. PK extension (CORE STRUCTURAL - child PK extends parent PK) 2. Single-FK child (CORE STRUCTURAL - detail table with one FK) 3. Strong FK dependency (STRUCTURAL/SEMANTIC - mandatory FK + name tokens) 4. Explicit constraint type (dictionary metadata)

__init__(mapping_generator)[source]

Parameters:: mapping_generator (MappingGenerator)

filter_ownership_relationships(fk_map, data)[source]

Filter FK map to separate ownership vs reference relationships.

Returns:

(ownership_fk_map, reference_fk_map) - ownership_fk_map: Compositional relationships (child owned by parent) - reference_fk_map: Referential/lookup relationships (child references parent)

Return type:

tuple

Parameters:

fk_map (Dict)
data (Dict)

Nesting

class sloth.mmcif.serializer.NestingBuilder[source]

Bases: object

Builds nested structure from flat data using relationships

build_nested_structure(flat, fk_map, primary_keys, reference_fk_map=None)[source]

Build nested structure from flat data.

Parameters:

flat (Dict[str, Any]) – Flat data dictionary
fk_map (Dict) – Ownership FK relationships (standard nesting: child in parent)
primary_keys (Dict[str, Any]) – Primary key definitions
reference_fk_map (Optional[Dict]) – Reference/lookup relationships (for denormalization: parent in child)

Return type:

Dict[str, Any]