PyPI - unit3dprep - Versions diffs - 1.0.4__py3-none-any.whl - Mend

unit3dprep 1.0.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

unit3dprep/__init__.py +0 -0
unit3dprep/cli.py +256 -0
unit3dprep/core.py +556 -0
unit3dprep/i18n.py +151 -0
unit3dprep/media.py +278 -0
unit3dprep/upload.py +146 -0
unit3dprep/web/__init__.py +0 -0
unit3dprep/web/_env.py +40 -0
unit3dprep/web/api/__init__.py +1 -0
unit3dprep/web/api/auth.py +36 -0
unit3dprep/web/api/fs.py +64 -0
unit3dprep/web/api/library.py +503 -0
unit3dprep/web/api/logs.py +42 -0
unit3dprep/web/api/queue.py +54 -0
unit3dprep/web/api/quickupload.py +153 -0
unit3dprep/web/api/search.py +40 -0
unit3dprep/web/api/settings.py +77 -0
unit3dprep/web/api/tmdb.py +77 -0
unit3dprep/web/api/trackers.py +30 -0
unit3dprep/web/api/uploaded.py +26 -0
unit3dprep/web/api/version.py +754 -0
unit3dprep/web/api/webup.py +59 -0
unit3dprep/web/api/wizard.py +512 -0
unit3dprep/web/app.py +201 -0
unit3dprep/web/auth.py +41 -0
unit3dprep/web/clients.py +167 -0
unit3dprep/web/config.py +932 -0
unit3dprep/web/db.py +184 -0
unit3dprep/web/dist/assets/JetBrainsMono-Italic-VariableFont_wght-CZO9PUqx.ttf +0 -0
unit3dprep/web/dist/assets/JetBrainsMono-VariableFont_wght-BrlcHZ7m.ttf +0 -0
unit3dprep/web/dist/assets/SpaceGrotesk-VariableFont_wght-DIScfSlK.ttf +0 -0
unit3dprep/web/dist/assets/index-BizNr_oP.js +255 -0
unit3dprep/web/dist/assets/index-DChRHChM.css +1 -0
unit3dprep/web/dist/index.html +14 -0
unit3dprep/web/duplicate_check.py +92 -0
unit3dprep/web/lang_cache.py +118 -0
unit3dprep/web/logbuf.py +164 -0
unit3dprep/web/tmdb_cache.py +116 -0
unit3dprep/web/trackers.py +177 -0
unit3dprep/web/webup_client.py +190 -0
unit3dprep/web/webup_job_fix.py +231 -0
unit3dprep/web/webup_logclass.py +107 -0
unit3dprep/web/webup_orchestrator.py +796 -0
unit3dprep/web/webup_ws.py +141 -0
unit3dprep-1.0.4.dist-info/METADATA +819 -0
unit3dprep-1.0.4.dist-info/RECORD +50 -0
unit3dprep-1.0.4.dist-info/WHEEL +5 -0
unit3dprep-1.0.4.dist-info/entry_points.txt +3 -0
unit3dprep-1.0.4.dist-info/licenses/LICENSE +674 -0
unit3dprep-1.0.4.dist-info/top_level.txt +1 -0

unit3dprep/web/dist/assets/index-DChRHChM.css ADDED Viewed

@@ -0,0 +1 @@

+ @font-face{font-family:Space Grotesk;src:url(./SpaceGrotesk-VariableFont_wght-DIScfSlK.ttf) format("truetype");font-weight:100 900;font-style:normal;font-display:swap}@font-face{font-family:JetBrains Mono;src:url(./JetBrainsMono-VariableFont_wght-BrlcHZ7m.ttf) format("truetype");font-weight:100 900;font-style:normal;font-display:swap}@font-face{font-family:JetBrains Mono;src:url(./JetBrainsMono-Italic-VariableFont_wght-CZO9PUqx.ttf) format("truetype");font-weight:100 900;font-style:italic;font-display:swap}:root{--bg-base: #08090c;--bg-surface: #0f1117;--bg-card: #161b25;--bg-card-hover: #1c2232;--bg-overlay: rgba(0, 0, 0, .7);--border: #1e2536;--border-subtle: #141924;--border-focus: #3b82f6;--blue-dim: #1d3e7a;--blue: #3b82f6;--blue-bright: #60a5fa;--blue-muted: rgba(59, 130, 246, .15);--yellow-dim: #78450a;--yellow: #f5a623;--yellow-bright: #fbbf24;--yellow-muted: rgba(245, 166, 35, .15);--red-dim: #5b1a1a;--red: #f87171;--red-bright: #fca5a5;--red-muted: rgba(248, 113, 113, .15);--green-dim: #14442b;--green: #4ade80;--green-bright: #86efac;--green-muted: rgba(74, 222, 128, .15);--cyan-dim: #0c3a4a;--cyan: #22d3ee;--cyan-bright: #67e8f9;--cyan-muted: rgba(34, 211, 238, .15);--fg-1: #e2e8f0;--fg-2: #94a3b8;--fg-3: #475569;--fg-4: #2d3a4f;--space-1: 4px;--space-2: 8px;--space-3: 12px;--space-4: 16px;--space-5: 20px;--space-6: 24px;--space-8: 32px;--space-10: 40px;--space-12: 48px;--space-16: 64px;--radius-sm: 4px;--radius-md: 6px;--radius-lg: 8px;--radius-pill: 9999px;--font-display: "Space Grotesk", "Helvetica Neue", sans-serif;--font-body: "Space Grotesk", "Helvetica Neue", sans-serif;--font-mono: "JetBrains Mono", "Fira Code", "Courier New", monospace;--text-xs: 11px;--text-sm: 13px;--text-base: 14px;--text-md: 15px;--text-lg: 17px;--text-xl: 20px;--text-2xl: 24px;--text-3xl: 30px;--leading-tight: 1.2;--leading-snug: 1.35;--leading-normal: 1.5;--leading-relaxed: 1.65;--tracking-tight: -.02em;--tracking-wide: .05em;--tracking-wider: .08em}*{margin:0;padding:0;box-sizing:border-box}html,body,#root{height:100%}body{font-family:var(--font-body);font-size:var(--text-base);line-height:var(--leading-normal);color:var(--fg-1);background:var(--bg-base);-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}::-webkit-scrollbar{width:5px;height:5px}::-webkit-scrollbar-track{background:var(--bg-surface)}::-webkit-scrollbar-thumb{background:var(--border);border-radius:9999px}input,select,textarea{transition:border-color .15s;font-family:inherit}input:focus,select:focus,textarea:focus{border-color:var(--blue)!important;outline:none}button{font-family:inherit}a{color:var(--blue-bright);text-decoration:none}a:hover{color:var(--blue-bright)}code,pre,kbd{font-family:var(--font-mono);font-size:var(--text-sm)}@keyframes spin{0%{transform:rotate(0)}to{transform:rotate(360deg)}}@keyframes pulse{0%,to{opacity:1}50%{opacity:.4}}@keyframes blink{50%{opacity:0}}@keyframes u3d-slide-in{0%{transform:translate(-100%)}to{transform:translate(0)}}@keyframes u3d-fade-in{0%{opacity:0}to{opacity:1}}@media (max-width: 768px){.u3d-hide-mobile{display:none!important}.u3d-mobile-modal{width:100%!important;max-width:100%!important;height:100%!important;max-height:100%!important;border-radius:0!important}.u3d-mobile-fullbleed{padding-left:14px!important;padding-right:14px!important}}

unit3dprep/web/dist/index.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2064%2064%22%3E%3Crect%20width%3D%2264%22%20height%3D%2264%22%20rx%3D%2212%22%20fill%3D%22%230a0c12%22%2F%3E%3Crect%20x%3D%223%22%20y%3D%223%22%20width%3D%2258%22%20height%3D%2258%22%20rx%3D%229%22%20fill%3D%22none%22%20stroke%3D%22%233b82f6%22%20stroke-width%3D%222%22%2F%3E%3Ctext%20x%3D%2232%22%20y%3D%2245%22%20text-anchor%3D%22middle%22%20font-family%3D%22Arial%20Black%2Csans-serif%22%20font-size%3D%2228%22%20font-weight%3D%22900%22%20fill%3D%22%233b82f6%22%3E3D%3C%2Ftext%3E%3Ccircle%20cx%3D%2252%22%20cy%3D%2212%22%20r%3D%223%22%20fill%3D%22%2334d399%22%2F%3E%3C%2Fsvg%3E" />
+    <title>Unit3DPrep — Web UI</title>
+    <script type="module" crossorigin src="./assets/index-BizNr_oP.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-DChRHChM.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

unit3dprep/web/duplicate_check.py ADDED Viewed

@@ -0,0 +1,92 @@
+"""Pre-upload duplicate detection against the ITT Unit3D API.
+Webup 0.0.25 does not implement duplicate detection (`DUPLICATE_ON` /
+`SKIP_DUPLICATE` are commented `# Todo Not yet implemented` in its
+`config/settings.py`). The legacy `unit3dup` CLI used to query the
+tracker by TMDB id and refuse the upload when an existing torrent had
+the *exact* same file size in bytes — irrespective of name/encode/etc.
+We replicate that behaviour here as a pre-flight performed by the
+bridge before invoking webup.
+Triggered by the `W_DUPLICATE_CHECK` runtime setting (default ON).
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+import httpx
+log = logging.getLogger("unit3dprep.duplicate_check")
+_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+async def find_duplicate(
+    *,
+    tracker_url: str,
+    api_token: str,
+    tmdb_id: int | str | None,
+    size_bytes: int | None,
+) -> dict[str, Any] | None:
+    """Query the tracker for any existing torrent that matches `size_bytes`.
+    Returns a dict with the matched torrent details (suitable for showing
+    to the user) when a duplicate is found, or ``None`` otherwise.
+    Returns ``None`` (no false positives) when any of the inputs is
+    missing, the API call fails, or the response is unexpected. The
+    caller can always treat ``None`` as "no duplicate".
+    """
+    if not tracker_url or not api_token or not tmdb_id or not size_bytes:
+        return None
+    try:
+        size_int = int(size_bytes)
+        tmdb_int = int(tmdb_id)
+    except (TypeError, ValueError):
+        return None
+    if size_int <= 0 or tmdb_int <= 0:
+        return None
+    base = tracker_url.rstrip("/")
+    url = f"{base}/api/torrents/filter"
+    params = {"tmdbId": str(tmdb_int), "api_token": api_token, "perPage": "100"}
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT, follow_redirects=True) as client:
+            r = await client.get(url, params=params)
+            r.raise_for_status()
+            payload = r.json()
+    except (httpx.HTTPError, ValueError) as e:
+        log.warning("duplicate check failed (%s): %s", url, e)
+        return None
+    items = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(items, list):
+        return None
+    for entry in items:
+        if not isinstance(entry, dict):
+            continue
+        attrs = entry.get("attributes") or {}
+        existing_size = attrs.get("size")
+        try:
+            existing_size = int(existing_size) if existing_size is not None else None
+        except (TypeError, ValueError):
+            continue
+        if existing_size != size_int:
+            continue
+        return {
+            "id": entry.get("id") or attrs.get("id"),
+            "name": attrs.get("name"),
+            "size": existing_size,
+            "type": attrs.get("type"),
+            "resolution": attrs.get("resolution"),
+            "category": attrs.get("category"),
+            "uploader": attrs.get("uploader"),
+            "seeders": attrs.get("seeders"),
+            "leechers": attrs.get("leechers"),
+            "created_at": attrs.get("created_at"),
+            "details_link": attrs.get("details_link"),
+            "tmdb_id": tmdb_int,
+        }
+    return None

unit3dprep/web/lang_cache.py ADDED Viewed

@@ -0,0 +1,118 @@
+"""Audio language cache — JSON file store. Thread-safe. No sqlite3.
+Keys are source_path strings (unresolved for series/seasons, same convention as tmdb_cache).
+Schema per entry:
+  {
+    "langs": ["ITA", "ENG", ...],
+    "episode_langs": { "<str(filepath)>": ["ITA", "ENG"] },  # only for series/seasons
+    "scanned_at": "YYYY-MM-DD HH:MM:SS"
+  }
+"""
+import asyncio
+import json
+import os
+import threading
+import time
+from pathlib import Path
+_lock = threading.Lock()
+def _cache_path() -> Path:
+    default = str(Path.home() / ".unit3dprep_lang_cache.json")
+    try:
+        from . import config
+        return Path(config.runtime_setting("U3DP_LANG_CACHE_PATH", default=default))
+    except Exception:
+        from ._env import env as _env
+        return Path(_env("U3DP_LANG_CACHE_PATH", "ITA_LANG_CACHE_PATH", default) or default)
+CACHE_PATH = _cache_path()
+# ---------------------------------------------------------------------------
+# Sync helpers
+# ---------------------------------------------------------------------------
+def _load() -> dict:
+    path = _cache_path()
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+def _save(data: dict):
+    path = _cache_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+def _get_sync(source_path: str) -> dict | None:
+    with _lock:
+        return _load().get(source_path)
+def _set_sync(source_path: str, record: dict):
+    with _lock:
+        data = _load()
+        data[source_path] = record
+        _save(data)
+def _get_many_sync(source_paths: list) -> dict:
+    with _lock:
+        data = _load()
+    return {sp: data[sp] for sp in source_paths if sp in data}
+def _delete_sync(source_path: str):
+    with _lock:
+        data = _load()
+        data.pop(source_path, None)
+        _save(data)
+def _list_all_sync() -> dict:
+    with _lock:
+        return _load()
+# ---------------------------------------------------------------------------
+# Async wrappers
+# ---------------------------------------------------------------------------
+async def _run(fn, *args):
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, fn, *args)
+async def get_lang(source_path: str) -> dict | None:
+    return await _run(_get_sync, source_path)
+async def set_lang(source_path: str, langs: list, episode_langs: dict | None = None):
+    record: dict = {
+        "langs": langs,
+        "scanned_at": time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime()),
+    }
+    if episode_langs is not None:
+        record["episode_langs"] = episode_langs
+    await _run(_set_sync, source_path, record)
+async def get_many_langs(source_paths: list) -> dict:
+    return await _run(_get_many_sync, [str(sp) for sp in source_paths])
+async def delete_lang(source_path: str):
+    await _run(_delete_sync, source_path)
+async def list_all_langs() -> dict:
+    return await _run(_list_all_sync)

unit3dprep/web/logbuf.py ADDED Viewed

@@ -0,0 +1,164 @@
+"""In-memory log ring buffer with async subscribers for SSE tail.
+Captures records from the root logger (and any child loggers) and emits them
+to every subscriber's asyncio.Queue. New SSE clients receive the last
+`HISTORY` entries immediately then see live updates.
+Each entry carries:
+    ts     - "HH:MM:SS" (GMT)
+    kind   - "info" | "ok" | "warn" | "error" | "debug"
+    name   - raw logger name (e.g. "httpx", "unit3dup")
+    msg    - formatted message
+    source - user-facing category: app|http|upload|client|tracker|wizard|unit3dup|system
+    event  - optional slug for UI grouping (e.g. "upload.tmdb")
+    count  - present when consecutive duplicates were coalesced (>=2)
+"""
+from __future__ import annotations
+import asyncio
+import logging
+import time
+from collections import deque
+from typing import Any, Deque
+HISTORY = 500
+COALESCE_WINDOW = 2.0  # seconds
+_history: Deque[dict] = deque(maxlen=HISTORY)
+_subscribers: set[asyncio.Queue] = set()
+_main_loop: asyncio.AbstractEventLoop | None = None
+def _level_kind(level: int) -> str:
+    if level >= logging.ERROR:
+        return "error"
+    if level >= logging.WARNING:
+        return "warn"
+    if level >= logging.INFO:
+        return "info"
+    return "debug"
+def _infer_source(name: str) -> str:
+    n = (name or "").lower()
+    if n.startswith("httpx") or n.startswith("httpcore") or n.startswith("urllib3"):
+        return "http"
+    if n == "unit3dup":
+        return "unit3dup"
+    if n == "wizard":
+        return "wizard"
+    if n.startswith("uvicorn") or n.startswith("fastapi") or n.startswith("starlette"):
+        return "system"
+    if "tracker" in n:
+        return "tracker"
+    if "client" in n or "qbit" in n:
+        return "client"
+    if n.startswith("unit3dprep") or n.startswith("itatorrents"):
+        return "app"
+    return "app"
+def _push(entry: dict) -> None:
+    """Append to history (with coalescence) and broadcast to subscribers."""
+    now = time.time()
+    last = _history[-1] if _history else None
+    if (
+        last is not None
+        and last.get("source") == entry.get("source")
+        and last.get("event") == entry.get("event")
+        and last.get("msg") == entry.get("msg")
+        and last.get("kind") == entry.get("kind")
+        and (now - last.get("_t", 0)) <= COALESCE_WINDOW
+    ):
+        last["count"] = int(last.get("count", 1)) + 1
+        last["ts"] = entry["ts"]
+        last["_t"] = now
+        out = {k: v for k, v in last.items() if k != "_t"}
+        _broadcast(out)
+        return
+    entry["_t"] = now
+    _history.append(entry)
+    out = {k: v for k, v in entry.items() if k != "_t"}
+    _broadcast(out)
+def _broadcast(entry: dict) -> None:
+    if _main_loop is None:
+        return
+    for q in list(_subscribers):
+        try:
+            _main_loop.call_soon_threadsafe(q.put_nowait, entry)
+        except Exception:
+            pass
+class _RingHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            entry = {
+                "ts": time.strftime("%H:%M:%S", time.gmtime(record.created)),
+                "kind": _level_kind(record.levelno),
+                "name": record.name,
+                "msg": self.format(record),
+                "source": _infer_source(record.name),
+            }
+        except Exception:
+            return
+        _push(entry)
+def install(loop: asyncio.AbstractEventLoop) -> None:
+    """Attach the ring handler to the root logger. Call once at startup."""
+    global _main_loop
+    _main_loop = loop
+    h = _RingHandler()
+    h.setLevel(logging.INFO)
+    h.setFormatter(logging.Formatter("%(message)s"))
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        if isinstance(existing, _RingHandler):
+            break
+    else:
+        root.addHandler(h)
+    if root.level > logging.INFO or root.level == logging.NOTSET:
+        root.setLevel(logging.INFO)
+    # Silence noisy HTTP-client loggers: every qBittorrent poll logs a GET/POST
+    # at INFO on httpx, which floods the Logs tab. Surface only real problems.
+    for noisy in ("httpx", "httpcore", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+def history() -> list[dict]:
+    return [{k: v for k, v in e.items() if k != "_t"} for e in _history]
+def subscribe() -> asyncio.Queue:
+    q: asyncio.Queue = asyncio.Queue()
+    _subscribers.add(q)
+    return q
+def unsubscribe(q: asyncio.Queue) -> None:
+    _subscribers.discard(q)
+def emit(
+    kind: str,
+    msg: str,
+    name: str = "app",
+    *,
+    source: str | None = None,
+    event: str | None = None,
+) -> None:
+    """Manual emit helper for business events (upload started, etc.)."""
+    entry: dict[str, Any] = {
+        "ts": time.strftime("%H:%M:%S", time.gmtime()),
+        "kind": kind,
+        "name": name,
+        "msg": msg,
+        "source": source or _infer_source(name),
+    }
+    if event:
+        entry["event"] = event
+    _push(entry)

unit3dprep/web/tmdb_cache.py ADDED Viewed

@@ -0,0 +1,116 @@
+"""TMDB metadata cache — JSON file store. Thread-safe. No sqlite3.
+Keys are resolved absolute source_path strings.
+Schema per entry (all fields optional for backward compat — read with .get()):
+  { tmdb_id, tmdb_kind,
+    title,          # primary lang (TMDB_DEFAULT_LANG, default it-IT)
+    title_en,       # en-US title
+    original_title, # TMDB original_title / original_name
+    year, poster,
+    overview,       # primary lang
+    overview_en,    # en-US
+    fetched_at }
+"""
+import asyncio
+import json
+import os
+import threading
+import time
+from pathlib import Path
+_lock = threading.Lock()
+def _cache_path() -> Path:
+    default = str(Path.home() / ".unit3dprep_tmdb_cache.json")
+    try:
+        from . import config
+        return Path(config.runtime_setting("U3DP_TMDB_CACHE_PATH", default=default))
+    except Exception:
+        from ._env import env as _env
+        return Path(_env("U3DP_TMDB_CACHE_PATH", "ITA_TMDB_CACHE_PATH", default) or default)
+CACHE_PATH = _cache_path()
+# ---------------------------------------------------------------------------
+# Sync helpers
+# ---------------------------------------------------------------------------
+def _load() -> dict:
+    path = _cache_path()
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+def _save(data: dict):
+    path = _cache_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+def _get_sync(source_path: str) -> dict | None:
+    with _lock:
+        return _load().get(source_path)
+def _set_sync(source_path: str, record: dict):
+    with _lock:
+        data = _load()
+        data[source_path] = record
+        _save(data)
+def _get_many_sync(source_paths: list) -> dict:
+    with _lock:
+        data = _load()
+    return {sp: data[sp] for sp in source_paths if sp in data}
+def _delete_sync(source_path: str):
+    with _lock:
+        data = _load()
+        data.pop(source_path, None)
+        _save(data)
+def _list_all_sync() -> dict:
+    with _lock:
+        return _load()
+# ---------------------------------------------------------------------------
+# Async wrappers
+# ---------------------------------------------------------------------------
+async def _run(fn, *args):
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, fn, *args)
+async def get_cache(source_path: str) -> dict | None:
+    return await _run(_get_sync, source_path)
+async def set_cache(source_path: str, **fields):
+    record = {**fields, "fetched_at": time.strftime("%Y-%m-%d %H:%M:%S", time.gmtime())}
+    await _run(_set_sync, source_path, record)
+async def get_many(source_paths: list) -> dict:
+    return await _run(_get_many_sync, [str(sp) for sp in source_paths])
+async def delete_cache(source_path: str):
+    await _run(_delete_sync, source_path)
+async def list_all_cache() -> dict:
+    return await _run(_list_all_sync)

unit3dprep/web/trackers.py ADDED Viewed

@@ -0,0 +1,177 @@
+"""Tracker (Unit3D) API wrappers.
+v1 wires up ITT (Unit3D public API). PTT/SIS return 501 on search so the
+UI can render the tabs without crashing when the user hasn't filled in
+their credentials.
+"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, asdict
+from typing import Any
+import httpx
+@dataclass
+class SearchResult:
+    tracker: str
+    id: int
+    name: str
+    type: str          # Movie|Serie|Game|Doc
+    resolution: str    # 4K|1080p|720p|—
+    size: str          # human-readable
+    seeders: int
+    leechers: int
+    uploader: str
+    url: str           # details URL
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+class Tracker(ABC):
+    key: str = "generic"
+    label: str = "Generic"
+    @abstractmethod
+    async def status(self) -> bool: ...
+    @abstractmethod
+    async def search(self, query: str) -> list[SearchResult]: ...
+def _human_size(b: int) -> str:
+    for unit, size in [("TB", 1 << 40), ("GB", 1 << 30), ("MB", 1 << 20), ("KB", 1 << 10)]:
+        if b >= size:
+            return f"{b / size:.1f} {unit}"
+    return f"{b} B"
+def _resolution_for(attrs: dict[str, Any]) -> str:
+    res_id = attrs.get("resolution_id")
+    res_name = (attrs.get("resolution") or "").lower()
+    if "2160" in res_name or res_id == 1:
+        return "4K"
+    if "1080" in res_name:
+        return "1080p"
+    if "720" in res_name:
+        return "720p"
+    if "576" in res_name or "480" in res_name:
+        return "SD"
+    return "—"
+def _type_for(attrs: dict[str, Any]) -> str:
+    cat = (attrs.get("category") or "").lower()
+    if "tv" in cat or "serie" in cat:
+        return "Serie"
+    if "movie" in cat or "film" in cat:
+        return "Movie"
+    if "game" in cat:
+        return "Game"
+    if "doc" in cat or "book" in cat:
+        return "Doc"
+    return "Movie"
+class Unit3DTracker(Tracker):
+    """Generic Unit3D tracker. Subclass with site-specific key/label/url."""
+    base_url: str
+    api_key: str
+    def __init__(self, key: str, label: str, url: str, api_key: str):
+        self.key = key
+        self.label = label
+        self.base_url = url.rstrip("/")
+        self.api_key = api_key
+    @property
+    def configured(self) -> bool:
+        return bool(self.base_url) and bool(self.api_key) and self.api_key not in {"no_key", ""}
+    async def status(self) -> bool:
+        if not self.configured:
+            return False
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as c:
+                r = await c.get(self.base_url)
+                return r.status_code < 500
+        except Exception:
+            return False
+    async def search(self, query: str) -> list[SearchResult]:
+        if not self.api_key or self.api_key in {"no_key", ""}:
+            raise RuntimeError(f"{self.key} API key not configured")
+        params = {"api_token": self.api_key, "name": query, "perPage": 25}
+        async with httpx.AsyncClient(timeout=15.0) as c:
+            r = await c.get(f"{self.base_url}/api/torrents/filter", params=params)
+            r.raise_for_status()
+            payload = r.json()
+        out: list[SearchResult] = []
+        for entry in payload.get("data", [])[:25]:
+            attrs = entry.get("attributes") or entry
+            tid = int(entry.get("id") or attrs.get("id") or 0)
+            size_val = attrs.get("size")
+            try:
+                size_int = int(size_val)
+                size_h = _human_size(size_int)
+            except (TypeError, ValueError):
+                size_h = str(size_val or "—")
+            out.append(SearchResult(
+                tracker=self.key,
+                id=tid,
+                name=attrs.get("name") or "",
+                type=_type_for(attrs),
+                resolution=_resolution_for(attrs),
+                size=size_h,
+                seeders=int(attrs.get("seeders") or 0),
+                leechers=int(attrs.get("leechers") or 0),
+                uploader=attrs.get("uploader") or "",
+                url=f"{self.base_url}/torrents/{tid}",
+            ))
+        return out
+class _StubTracker(Tracker):
+    def __init__(self, key: str, label: str, url: str, api_key: str = ""):
+        self.key = key
+        self.label = label
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+    @property
+    def configured(self) -> bool:
+        return bool(self.url) and bool(self.api_key) and self.api_key not in {"no_key", ""}
+    async def status(self) -> bool:
+        if not self.configured:
+            return False
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as c:
+                r = await c.get(self.url)
+                return r.status_code < 500
+        except Exception:
+            return False
+    async def search(self, query: str) -> list[SearchResult]:
+        raise NotImplementedError(f"{self.key} search not implemented yet")
+def build_trackers(cfg: dict[str, Any]) -> dict[str, Tracker]:
+    """Instantiate all three trackers from the shared .env config."""
+    return {
+        "ITT": Unit3DTracker(
+            "ITT", "ITA Torrents",
+            cfg.get("ITT_URL", ""), cfg.get("ITT_APIKEY", ""),
+        ),
+        "PTT": _StubTracker(
+            "PTT", "Polish Torrent",
+            cfg.get("PTT_URL", ""), cfg.get("PTT_APIKEY", ""),
+        ),
+        "SIS": _StubTracker(
+            "SIS", "SIS",
+            cfg.get("SIS_URL", ""), cfg.get("SIS_APIKEY", ""),
+        ),
+    }