df

SYS/utils.py

@@ -1,10 +1,12 @@
 """General-purpose helpers used across the downlow CLI."""
+
 from __future__ import annotations
 
 import json
 import hashlib
 import subprocess
 import shutil
+
 try:
     import ffmpeg  # type: ignore
 except Exception:
@@ -28,12 +30,16 @@ except ImportError:
 
 CHUNK_SIZE = 1024 * 1024  # 1 MiB
 _format_logger = logging.getLogger(__name__)
+
+
 def ensure_directory(path: Path) -> None:
     """Ensure *path* exists as a directory."""
     try:
         path.mkdir(parents=True, exist_ok=True)
     except OSError as exc:  # pragma: no cover - surfaced to caller
         raise RuntimeError(f"Failed to create directory {path}: {exc}") from exc
+
+
 def unique_path(path: Path) -> Path:
     """Return a unique path by appending " (n)" if needed."""
     if not path.exists():
@@ -48,15 +54,18 @@ def unique_path(path: Path) -> Path:
             return candidate
         counter += 1
 
+
 def sanitize_metadata_value(value: Any) -> str | None:
     if value is None:
         return None
     if not isinstance(value, str):
         value = str(value)
-    value = value.replace('\x00', ' ').replace('\r', ' ').replace('\n', ' ').strip()
+    value = value.replace("\x00", " ").replace("\r", " ").replace("\n", " ").strip()
     if not value:
         return None
     return value
+
+
 def unique_preserve_order(values: Iterable[str]) -> list[str]:
     seen: set[str] = set()
     ordered: list[str] = []
@@ -65,21 +74,23 @@ def unique_preserve_order(values: Iterable[str]) -> list[str]:
             seen.add(value)
             ordered.append(value)
     return ordered
+
+
 def sha256_file(file_path: Path) -> str:
     """Return the SHA-256 hex digest of *path*."""
     hasher = hashlib.sha256()
-    with file_path.open('rb') as handle:
-        for chunk in iter(lambda: handle.read(CHUNK_SIZE), b''):
+    with file_path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(CHUNK_SIZE), b""):
             hasher.update(chunk)
     return hasher.hexdigest()
 
 
 def create_metadata_sidecar(file_path: Path, metadata: dict) -> None:
     """Create a .metadata sidecar file with JSON metadata.
-    
+
     The metadata dict should contain title. If not present, it will be derived from
     the filename. This ensures the .metadata file can be matched during batch import.
-    
+
     Args:
         file_path: Path to the exported file
         metadata: Dictionary of metadata to save
@@ -90,50 +101,50 @@ def create_metadata_sidecar(file_path: Path, metadata: dict) -> None:
     file_ext = file_path.suffix.lower()
     # Ensure metadata has a title field that matches the filename (without extension)
     # This allows the sidecar to be matched and imported properly during batch import
-    if 'title' not in metadata or not metadata.get('title'):
-        metadata['title'] = file_name
-    metadata['hash'] = sha256_file(file_path)
-    metadata['size'] = Path(file_path).stat().st_size
+    if "title" not in metadata or not metadata.get("title"):
+        metadata["title"] = file_name
+    metadata["hash"] = sha256_file(file_path)
+    metadata["size"] = Path(file_path).stat().st_size
     format_found = False
     for mime_type, ext_map in SYS.utils_constant.mime_maps.items():
         for key, info in ext_map.items():
             if info.get("ext") == file_ext:
-                metadata['type'] = mime_type
+                metadata["type"] = mime_type
                 format_found = True
                 break
         if format_found:
             break
     else:
-        metadata['type'] = 'unknown'
+        metadata["type"] = "unknown"
     metadata.update(ffprobe(str(file_path)))
 
-    
-    metadata_path = file_path.with_suffix(file_path.suffix + '.metadata')
+    metadata_path = file_path.with_suffix(file_path.suffix + ".metadata")
     try:
-        with open(metadata_path, 'w', encoding='utf-8') as f:
+        with open(metadata_path, "w", encoding="utf-8") as f:
             json.dump(metadata, f, ensure_ascii=False, indent=2)
     except OSError as exc:
         raise RuntimeError(f"Failed to write metadata sidecar {metadata_path}: {exc}") from exc
-    
+
+
 def create_tags_sidecar(file_path: Path, tags: set) -> None:
     """Create a .tag sidecar file with tags (one per line).
-    
+
     Args:
         file_path: Path to the exported file
         tags: Set of tag strings
     """
     if not tags:
         return
-    
-    tags_path = file_path.with_suffix(file_path.suffix + '.tag')
+
+    tags_path = file_path.with_suffix(file_path.suffix + ".tag")
     try:
-        with open(tags_path, 'w', encoding='utf-8') as f:
+        with open(tags_path, "w", encoding="utf-8") as f:
             for tag in sorted(tags):
                 f.write(f"{str(tag).strip().lower()}\n")
     except Exception as e:
         raise RuntimeError(f"Failed to create tags sidecar {tags_path}: {e}") from e
 
-        
+
 def ffprobe(file_path: str) -> dict:
     """Probe a media file and return a metadata dictionary.
 
@@ -157,7 +168,16 @@ def ffprobe(file_path: str) -> dict:
         if ffprobe_cmd:
             try:
                 proc = subprocess.run(
-                    [ffprobe_cmd, "-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", str(file_path)],
+                    [
+                        ffprobe_cmd,
+                        "-v",
+                        "quiet",
+                        "-print_format",
+                        "json",
+                        "-show_format",
+                        "-show_streams",
+                        str(file_path),
+                    ],
                     check=True,
                     capture_output=True,
                     text=True,
@@ -185,7 +205,9 @@ def ffprobe(file_path: str) -> dict:
         if codec_type == "audio":
             metadata["audio_codec"] = stream.get("codec_name")
             metadata["bitrate"] = int(stream.get("bit_rate", 0)) if "bit_rate" in stream else None
-            metadata["samplerate"] = int(stream.get("sample_rate", 0)) if "sample_rate" in stream else None
+            metadata["samplerate"] = (
+                int(stream.get("sample_rate", 0)) if "sample_rate" in stream else None
+            )
             metadata["channels"] = int(stream.get("channels", 0)) if "channels" in stream else None
         elif codec_type == "video":
             metadata["video_codec"] = stream.get("codec_name")
@@ -233,16 +255,16 @@ def jsonify(value: Any) -> Any:
 
 def format_bytes(bytes_value) -> str:
     """Format bytes to human-readable format (e.g., '1.5 MB', '250 KB').
-    
+
     Args:
         bytes_value: Size in bytes (int or float)
-        
+
     Returns:
         Formatted string like '1.5 MB' or '756 MB'
     """
     if bytes_value is None or bytes_value <= 0:
         return "0 B"
-    
+
     if isinstance(bytes_value, (int, float)):
         for unit in ("B", "KB", "MB", "GB", "TB"):
             if bytes_value < 1024:
@@ -256,33 +278,33 @@ def format_bytes(bytes_value) -> str:
 
 def format_duration(seconds) -> str:
     """Format duration in seconds to human-readable format (e.g., '1h 23m 5s', '5m 30s').
-    
+
     Args:
         seconds: Duration in seconds (int or float)
-        
+
     Returns:
         Formatted string like '1:23:45' or '5:30'
     """
-    if seconds is None or seconds == '':
+    if seconds is None or seconds == "":
         return "N/A"
-    
+
     if isinstance(seconds, str):
         try:
             seconds = float(seconds)
         except ValueError:
             return str(seconds)
-    
+
     if not isinstance(seconds, (int, float)):
         return str(seconds)
-    
+
     total_seconds = int(seconds)
     if total_seconds < 0:
         return "N/A"
-    
+
     hours = total_seconds // 3600
     minutes = (total_seconds % 3600) // 60
     secs = total_seconds % 60
-    
+
     if hours > 0:
         return f"{hours}:{minutes:02d}:{secs:02d}"
     elif minutes > 0:
@@ -293,53 +315,60 @@ def format_duration(seconds) -> str:
 
 def format_timestamp(timestamp_str) -> str:
     """Format ISO timestamp to readable format.
-    
+
     Args:
         timestamp_str: ISO format timestamp string or None
-        
+
     Returns:
         Formatted string like "2025-10-28 19:36:01" or original string if parsing fails
     """
     if not timestamp_str:
         return "N/A"
-    
+
     try:
         # Handle ISO format timestamps
         if isinstance(timestamp_str, str):
             # Try parsing ISO format
-            if 'T' in timestamp_str:
-                dt = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+            if "T" in timestamp_str:
+                dt = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
             else:
                 # Try other common formats
                 dt = datetime.fromisoformat(timestamp_str)
             return dt.strftime("%Y-%m-%d %H:%M:%S")
     except Exception as e:
         _format_logger.debug(f"Could not parse timestamp '{timestamp_str}': {e}")
-    
+
     return str(timestamp_str)
 
 
 def format_metadata_value(key: str, value) -> str:
     """Format a metadata value based on its key for display.
-    
+
     This is the central formatting rule for all metadata display.
-    
+
     Args:
         key: Metadata field name
         value: Value to format
-        
+
     Returns:
         Formatted string for display
     """
-    if value is None or value == '':
+    if value is None or value == "":
         return "N/A"
-    
+
     # Apply field-specific formatting
-    if key in ('size', 'file_size'):
+    if key in ("size", "file_size"):
         return format_bytes(value)
-    elif key in ('duration', 'length'):
+    elif key in ("duration", "length"):
         return format_duration(value)
-    elif key in ('time_modified', 'time_imported', 'created_at', 'updated_at', 'indexed_at', 'timestamp'):
+    elif key in (
+        "time_modified",
+        "time_imported",
+        "created_at",
+        "updated_at",
+        "indexed_at",
+        "timestamp",
+    ):
         return format_timestamp(value)
     else:
         return str(value)
@@ -353,50 +382,50 @@ def format_metadata_value(key: str, value) -> str:
 
 def extract_link_from_args(args: Iterable[str]) -> Any | None:
     """Extract HTTP/HTTPS URL from command arguments.
-    
+
     Args:
         args: Command arguments
-        
+
     Returns:
         URL string if found, None otherwise
     """
     args_list = list(args) if not isinstance(args, (list, tuple)) else args
     if not args_list or len(args_list) == 0:
         return None
-    
+
     potential_link = str(args_list[0])
-    if potential_link.startswith(('http://', 'https://')):
+    if potential_link.startswith(("http://", "https://")):
         return potential_link
-    
+
     return None
 
 
 def extract_link_from_result(result: Any) -> Any | None:
     """Extract URL from a result object (dict or object with attributes).
-    
+
     Args:
         result: Result object from pipeline (dict or object)
-        
+
     Returns:
         URL string if found, None otherwise
     """
     if isinstance(result, dict):
-        return result.get('url') or result.get('link') or result.get('href')
-    
+        return result.get("url") or result.get("link") or result.get("href")
+
     return (
-        getattr(result, 'url', None) or 
-        getattr(result, 'link', None) or 
-        getattr(result, 'href', None)
+        getattr(result, "url", None)
+        or getattr(result, "link", None)
+        or getattr(result, "href", None)
     )
 
 
 def extract_link(result: Any, args: Iterable[str]) -> Any | None:
     """Extract link from args or result (args take priority).
-    
+
     Args:
         result: Pipeline result object
         args: Command arguments
-        
+
     Returns:
         URL string if found, None otherwise
     """
@@ -404,34 +433,34 @@ def extract_link(result: Any, args: Iterable[str]) -> Any | None:
     link = extract_link_from_args(args)
     if link:
         return link
-    
+
     # Fall back to result
     return extract_link_from_result(result)
 
 
 def get_api_key(config: dict[str, Any], service: str, key_path: str) -> str | None:
     """Get API key from config with fallback support.
-    
+
     Args:
         config: Configuration dictionary
         service: Service name for logging
         key_path: Dot-notation path to key (e.g., "Debrid.All-debrid")
-        
+
     Returns:
         API key if found and not empty, None otherwise
     """
     try:
-        parts = key_path.split('.')
+        parts = key_path.split(".")
         value = config
         for part in parts:
             if isinstance(value, dict):
                 value = value.get(part)
             else:
                 return None
-        
+
         if isinstance(value, str):
             return value.strip() or None
-        
+
         return None
     except Exception:
         return None
@@ -439,18 +468,18 @@ def get_api_key(config: dict[str, Any], service: str, key_path: str) -> str | No
 
 def add_direct_link_to_result(result: Any, direct_link: str, original_link: str) -> None:
     """Add direct link information to result object.
-    
+
     Args:
         result: Result object to modify (dict or object)
         direct_link: The unlocked/direct URL
         original_link: The original restricted URL
     """
     if isinstance(result, dict):
-        result['direct_link'] = direct_link
-        result['original_link'] = original_link
+        result["direct_link"] = direct_link
+        result["original_link"] = original_link
     else:
-        setattr(result, 'direct_link', direct_link)
-        setattr(result, 'original_link', original_link)
+        setattr(result, "direct_link", direct_link)
+        setattr(result, "original_link", original_link)
 
 
 # ============================================================================
@@ -529,4 +558,4 @@ def resolve_url_policy(config: dict[str, Any], url: str) -> UrlPolicy:
             for tag in rule["extra_tags"]:
                 if tag not in resolved.extra_tags:
                     resolved.extra_tags.append(tag)
-    return resolved
+    return resolved