ff

cmdlet/get_metadata.py

@@ -43,7 +43,18 @@ class Get_Metadata(Cmdlet):
 
     @staticmethod
     def _extract_imported_ts(meta: Dict[str, Any]) -> Optional[int]:
-        """Extract an imported timestamp from metadata if available."""
+        """Extract an imported timestamp from metadata if available.
+        
+        Attempts to parse imported timestamp from metadata dict in multiple formats:
+        - Numeric Unix timestamp (int/float)
+        - ISO format string (e.g., "2024-01-15T10:30:00")
+        
+        Args:
+            meta: Metadata dictionary from backend (e.g., from get_metadata())
+            
+        Returns:
+            Unix timestamp as integer if found, None otherwise
+        """
         if not isinstance(meta, dict):
             return None
 
@@ -65,7 +76,17 @@ class Get_Metadata(Cmdlet):
 
     @staticmethod
     def _format_imported(ts: Optional[int]) -> str:
-        """Format timestamp as readable string."""
+        """Format Unix timestamp as human-readable date string (UTC).
+        
+        Converts Unix timestamp to YYYY-MM-DD HH:MM:SS format.
+        Used for displaying file import dates to users.
+        
+        Args:
+            ts: Unix timestamp (integer) or None
+            
+        Returns:
+            Formatted date string (e.g., "2024-01-15 10:30:00") or empty string if invalid
+        """
         if not ts:
             return ""
         try:
@@ -91,7 +112,30 @@ class Get_Metadata(Cmdlet):
         ext: Optional[str] = None,
     ) -> Dict[str,
               Any]:
-        """Build a table row dict with metadata fields."""
+        """Build a normalized metadata row dict for display and piping.
+        
+        Converts raw metadata fields into a standardized row format suitable for:
+        - Display in result tables
+        - Piping to downstream cmdlets
+        - JSON serialization
+        
+        Args:
+            title: File or resource title
+            store: Backend store name (e.g., "hydrus", "local")
+            path: File path or resource identifier
+            mime: MIME type (e.g., "image/jpeg", "video/mp4")
+            size_bytes: File size in bytes
+            dur_seconds: Duration in seconds (for video/audio)
+            imported_ts: Unix timestamp when item was imported
+            url: List of known URLs associated with file
+            hash_value: File hash (SHA256 or other)
+            pages: Number of pages (for PDFs)
+            tag: List of tags applied to file
+            ext: File extension (e.g., "jpg", "mp4")
+            
+        Returns:
+            Dictionary with normalized metadata fields and display columns
+        """
         size_mb = None
         size_int: Optional[int] = None
         if size_bytes is not None:
@@ -151,7 +195,15 @@ class Get_Metadata(Cmdlet):
 
     @staticmethod
     def _add_table_body_row(table: Table, row: Dict[str, Any]) -> None:
-        """Add a single row to the ResultTable using the prepared columns."""
+        """Add a single metadata row to the result table.
+        
+        Extracts column values from row dict and adds to result table using
+        standard column ordering (Hash, MIME, Size, Duration/Pages).
+        
+        Args:
+            table: Result table to add row to
+            row: Metadata row dict (from _build_table_row)
+        """
         columns = row.get("columns") if isinstance(row, dict) else None
         lookup: Dict[str,
                      Any] = {}
@@ -173,7 +225,25 @@ class Get_Metadata(Cmdlet):
             row_obj.add_column("Duration(s)", "")
 
     def run(self, result: Any, args: Sequence[str], config: Dict[str, Any]) -> int:
-        """Main execution entry point."""
+        """Execute get-metadata cmdlet - retrieve and display file metadata.
+        
+        Queries a storage backend (Hydrus, local, etc.) for file metadata using hash.
+        Extracts tags embedded in metadata response (avoiding duplicate API calls).
+        Displays metadata in rich detail panel and result table.
+        Allows piping (@N) to other cmdlets for chaining operations.
+        
+        Optimizations:
+        - Extracts tags from metadata response (no separate get_tag() call)
+        - Single HTTP request to backends per file
+        
+        Args:
+            result: Piped input (dict with optional hash/store/title/tag fields)
+            args: Command line arguments ([-query "hash:..."] [-store backend])
+            config: Application configuration dict
+            
+        Returns:
+            0 on success, 1 on error (no metadata found, backend unavailable, etc.)
+        """
         # Parse arguments
         parsed = parse_cmdlet_args(args, self)