Medios-Macina/MODELS_REFACTOR_SUMMARY.md

Models.py Refactoring Summary

Overview

Refactored models.py PipeObject class to align with the hash+store canonical pattern, removing all backwards compatibility and legacy code.

PipeObject Changes

Removed Legacy Fields

• ❌ source - Replaced with store (storage backend name)
• ❌ identifier - Replaced with hash (SHA-256 hash)
• ❌ file_hash - Replaced with hash (canonical field)
• ❌ remote_metadata - Removed (can go in metadata dict or extra)
• ❌ mpv_metadata - Removed (can go in metadata dict or extra)
• ❌ king_hash - Moved to relationships dict
• ❌ alt_hashes - Moved to relationships dict
• ❌ related_hashes - Moved to relationships dict
• ❌ parent_id - Renamed to parent_hash for consistency

New Canonical Fields

@dataclass(slots=True)
class PipeObject:
    hash: str              # SHA-256 hash (canonical identifier)
    store: str             # Storage backend name (e.g., 'default', 'hydrus', 'test')
    tags: List[str]
    title: Optional[str]
    source_url: Optional[str]
    duration: Optional[float]
    metadata: Dict[str, Any]
    warnings: List[str]
    file_path: Optional[str]
    relationships: Dict[str, Any]  # Contains king/alt/related
    is_temp: bool
    action: Optional[str]
    parent_hash: Optional[str]     # Renamed from parent_id
    extra: Dict[str, Any]

Updated Methods

Removed

• ❌ register_as_king(file_hash) - Replaced with add_relationship()
• ❌ add_alternate(alt_hash) - Replaced with add_relationship()
• ❌ add_related(related_hash) - Replaced with add_relationship()
• ❌ @property hash - Now a direct field
• ❌ as_dict() - Removed backwards compatibility alias
• ❌ to_serializable() - Removed backwards compatibility alias

Added/Updated

• ✅ add_relationship(rel_type, rel_hash) - Generic relationship management
• ✅ get_relationships() - Returns copy of relationships dict
• ✅ to_dict() - Updated to serialize new fields

Updated Files

cmdlets/_shared.py

• Updated coerce_to_pipe_object() to use hash+store pattern
• Now computes hash from file_path if not provided
• Extracts relationships dict instead of individual king/alt/related fields
• Removes all references to source/identifier/file_hash

cmdlets/add_file.py

• Updated _update_pipe_object_destination() signature to use hash/store
• Updated _resolve_source() to use pipe_obj.hash
• Updated _prepare_metadata() to use pipe_obj.hash
• Updated _resolve_file_hash() to check pipe_obj.hash
• Updated all call sites to pass hash/store instead of source/identifier/file_hash

cmdlets/add_tag.py & cmdlets/add_tags.py

• Updated to access res.hash instead of res.file_hash
• Updated dict access to use get('hash') instead of get('file_hash')

cmdlets/trim_file.py

• Updated to access item.hash instead of item.file_hash
• Updated dict access to use get('hash') only

metadata.py

• Updated IMDb, MusicBrainz, and OpenLibrary tag extraction to return dicts directly
• Removed PipeObject instantiation with old signature (source/identifier)
• Updated remote metadata function to return dict instead of using PipeObject

Benefits

1. Canonical Pattern: All file operations now use hash+store as the single source of truth
2. Simplified Model: Removed 9 legacy fields, consolidated into 2 canonical fields + relationships dict
3. Consistency: All cmdlets now use the same hash+store pattern for identification
4. Maintainability: One code path, no backwards compatibility burden
5. Type Safety: Direct fields instead of computed properties
6. Flexibility: Relationships dict allows for extensible relationship types

Migration Notes

Old Code

pipe_obj = PipeObject(
    source="hydrus",
    identifier=file_hash,
    file_hash=file_hash,
    king_hash=king,
    alt_hashes=[alt1, alt2]
)

New Code

pipe_obj = PipeObject(
    hash=file_hash,
    store="hydrus",
    relationships={
        "king": king,
        "alt": [alt1, alt2]
    }
)

Accessing Fields

Old	New
obj.file_hash	obj.hash
obj.source	obj.store
obj.identifier	obj.hash
obj.king_hash	obj.relationships.get("king")
obj.alt_hashes	obj.relationships.get("alt", [])
obj.parent_id	obj.parent_hash

Zero Backwards Compatibility

As requested, all backwards compatibility has been removed. Old code using the previous PipeObject signature will need to be updated to use hash+store.