dfdkflj

MODELS_REFACTOR_SUMMARY.md

@@ -0,0 +1,127 @@
+# 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
+```python
+@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
+```python
+pipe_obj = PipeObject(
+    source="hydrus",
+    identifier=file_hash,
+    file_hash=file_hash,
+    king_hash=king,
+    alt_hashes=[alt1, alt2]
+)
+```
+
+### New Code
+```python
+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.