📝 Add docstrings to copilot/add-s-to-catalogue-support

Docstrings generation was requested by @Zzackllack.

* #8 (comment)

The following files were modified:

* `app/api/torznab/api.py`
* `app/api/torznab/utils.py`
* `app/core/downloader.py`
* `app/core/scheduler.py`
* `app/db/models.py`
* `app/utils/magnet.py`
* `app/utils/probe_quality.py`
* `app/utils/title_resolver.py`
* `tests/test_qbittorrent_torrents.py`
* `tests/test_torznab_utils.py`

Author: coderabbitai[bot]

app/api/torznab/api.py

@@ -28,8 +28,13 @@
 
 def _default_languages_for_site(site: str) -> List[str]:
     """
-    Return the default language preference ordering for a catalogue site.
-    Falls back to AniWorld defaults when a site-specific mapping is not found.
+    Get the default language preference ordering for a catalogue site.
+    
+    Parameters:
+        site (str): Catalogue site key to look up in CATALOG_SITE_CONFIGS.
+    
+    Returns:
+        List[str]: Language names in preference order. If the site has no valid mapping, returns the configured aniworld.to defaults (fallbacking to ["German Dub", "German Sub", "English Sub"] if that configuration is absent).
     """
     cfg = CATALOG_SITE_CONFIGS.get(site)
     if cfg:
@@ -408,4 +413,4 @@ def torznab_api(
 
     xml = ET.tostring(rss, encoding="utf-8", xml_declaration=True).decode("utf-8")
     logger.info(f"Returning RSS feed with {count} items.")
-    return Response(content=xml, media_type="application/rss+xml; charset=utf-8")
+    return Response(content=xml, media_type="application/rss+xml; charset=utf-8")

app/api/torznab/utils.py

@@ -84,13 +84,13 @@ def _normalize_tokens(s: str) -> List[str]:
 def _slug_from_query(q: str, site: Optional[str] = None) -> Optional[Tuple[str, str]]:
     """
     Resolve a free-text query to the best-matching site and canonical slug.
-
+    
     Parameters:
-        q (str): The free-text query to resolve (e.g., a title).
-        site (Optional[str]): If provided, restrict resolution to the specified site identifier.
-
+        q (str): The free-text title or query to resolve.
+        site (Optional[str]): Optional site identifier to restrict resolution to a specific site.
+    
     Returns:
-        Optional[Tuple[str, str]]: A tuple (site, slug) with the site identifier and resolved slug when a match is found, `None` if no match exists.
+        Optional[Tuple[str, str]]: `(site, slug)` with the site identifier and resolved canonical slug when a match is found, `None` otherwise.
     """
     logger.debug(f"Resolving slug from query: '{q}', site filter: {site}")
     from app.utils.title_resolver import slug_from_query  # type: ignore
@@ -201,4 +201,4 @@ def _build_item(
 
     _add_torznab_attr(item, "seeders", str(seeders))
     _add_torznab_attr(item, "peers", str(peers))
-    _add_torznab_attr(item, "leechers", str(leechers))
+    _add_torznab_attr(item, "leechers", str(leechers))

app/core/downloader.py

@@ -95,20 +95,20 @@ def build_episode(
     site: str = "aniworld.to",
 ) -> Episode:
     """
-    Construct an Episode from a direct link or from slug, season, and episode with the given site.
-
+    Construct an Episode from either a direct link or a slug/season/episode triple for the specified site.
+    
     Parameters:
-        link (Optional[str]): Direct episode URL. If provided, it is used and `slug/season/episode` are ignored.
-        slug (Optional[str]): Series identifier used with `season` and `episode` to build the Episode when `link` is not provided.
-        season (Optional[int]): Season number used with `slug` and `episode`.
-        episode (Optional[int]): Episode number used with `slug` and `season`.
-        site (str): Host site identifier included in the created Episode (default: "aniworld.to").
-
+        link (Optional[str]): Direct episode URL; used when provided and takes precedence over slug/season/episode.
+        slug (Optional[str]): Series identifier used with `season` and `episode` when `link` is not provided.
+        season (Optional[int]): Season number paired with `slug` and `episode`.
+        episode (Optional[int]): Episode number paired with `slug` and `season`.
+        site (str): Host site identifier to attach to the created Episode (default: "aniworld.to").
+    
     Returns:
-        Episode: An Episode constructed from `link` (if present) or from `slug`, `season`, and `episode`.
-
+        Episode: The constructed Episode using the provided inputs.
+    
     Raises:
-        ValueError: If neither `link` nor the combination of `slug`, `season`, and `episode` are provided.
+        ValueError: If neither `link` nor the combination of `slug`, `season`, and `episode` are supplied.
     """
     logger.info(
         f"Building episode: link={link}, slug={slug}, season={season}, episode={episode}, site={site}"
@@ -179,6 +179,21 @@ def get_direct_url_with_fallback(
     language: str,
 ) -> Tuple[str, str]:
 
+    """
+    Resolve a direct download URL for an episode, trying a preferred provider first and falling back to the configured provider order.
+    
+    Parameters:
+        ep (Episode): Episode object to resolve the direct link for.
+        preferred (Optional[str]): Provider name to try first; ignored if empty or None.
+        language (str): Desired language label; will be normalized before use.
+    
+    Returns:
+        tuple: (direct_url, provider_name) where `direct_url` is the resolved URL and `provider_name` is the provider that supplied it.
+    
+    Raises:
+        LanguageUnavailableError: If the requested language is not offered by the episode or a provider indicates the language is unavailable.
+        DownloadError: If no provider yields a direct URL after all fallbacks.
+    """
     language = _normalize_language(language)
     logger.info(
         f"Getting direct URL with fallback. Preferred: {preferred}, Language: {language}"
@@ -251,6 +266,23 @@ def _ydl_download(
     stop_event: Optional[threading.Event] = None,
     force_no_proxy: bool = False,
 ) -> Tuple[Path, Dict[str, Any]]:
+    """
+    Download a media resource via yt-dlp and return the downloaded file path and metadata.
+    
+    Uses yt-dlp to download the resource at `direct_url` into `dest_dir`, applying an optional filename hint, cookiefile, proxy configuration, progress callbacks, and cancellation via `stop_event`.
+    
+    Parameters:
+        direct_url (str): Direct media URL or playlist identifier to pass to yt-dlp.
+        dest_dir (Path): Directory where the download and temporary files will be stored; created if missing.
+        title_hint (Optional[str]): Hint for the output filename; sanitized and used in the output template if provided.
+        cookiefile (Optional[Path]): Path to a cookies file to supply to yt-dlp for authenticated requests.
+        progress_cb (Optional[callable]): Callback invoked with yt-dlp progress dictionaries as they arrive.
+        stop_event (Optional[threading.Event]): If set during download, the operation will be cancelled and raise DownloadError("Cancelled").
+        force_no_proxy (bool): When true, disable any configured proxy for this yt-dlp invocation.
+    
+    Returns:
+        Tuple[Path, Dict[str, Any]]: A tuple containing the final downloaded file path and the yt-dlp info dictionary.
+    """
     logger.info(
         f"Starting yt-dlp download: url={direct_url}, dest_dir={dest_dir}, title_hint={title_hint}"
     )
@@ -512,4 +544,4 @@ def download_episode(
         site=site,
     )
     logger.success(f"Final file path: {final_path}")
-    return final_path
+    return final_path

app/core/scheduler.py

@@ -114,22 +114,24 @@ def _cb(d: dict):
 
 def _run_download(job_id: str, req: dict, stop_event: threading.Event):
     """
-    Execute a download job: start the episode download, update the job record in the database with progress/result, and handle errors or cancellation.
-
+    Run a download task and record its progress and final state in the database.
+    
+    Executes the episode download described by `req`, updates the job row with lifecycle states
+    (e.g., "downloading", "completed", "failed", "cancelled"), writes final `result_path` on success,
+    and removes the job from the in-memory RUNNING registry when finished. If the download is cancelled
+    or an exception occurs, the job status and message are updated accordingly. An OSError caused by
+    an unwritable download directory sets the job to "failed" with a directory-specific message.
+    
     Parameters:
         job_id (str): Identifier of the job being run.
-        req (dict): Download request containing keys used by the downloader:
-            - 'slug', 'season', 'episode' (identifiers for the episode)
+        req (dict): Download request with keys used by the downloader. Recognized keys:
+            - 'slug', 'season', 'episode' (episode identifiers)
             - 'language' (optional)
             - 'provider' (optional)
             - 'title_hint' (optional)
             - 'link' (optional)
             - 'site' (optional, defaults to "aniworld.to")
         stop_event (threading.Event): Event that, when set, requests cancellation of the download.
-
-    Side effects:
-        - Updates the job row in the database with status, progress, messages, source site, and result path.
-        - Removes the job from the RUNNING registry when finished.
     """
     try:
         with Session(engine) as s:
@@ -182,8 +184,24 @@ def _run_download(job_id: str, req: dict, stop_event: threading.Event):
 
 def schedule_download(req: dict) -> str:
     """
-    req: {slug, season, episode, language, provider?, title_hint?, link?}
-    returns job_id
+    Schedule a background download job and return its job identifier.
+    
+    Parameters:
+        req (dict): Download request containing:
+            - slug (str): Content identifier.
+            - season (int | str): Season number or identifier.
+            - episode (int | str): Episode number or identifier.
+            - language (str): Desired audio/subtitle language.
+            - provider (str, optional): Provider to use.
+            - title_hint (str, optional): Suggested title for the download destination.
+            - link (str, optional): Direct link or reference.
+            - site (str, optional): Source site name; used as the job's source_site (defaults to "aniworld.to").
+    
+    Returns:
+        str: The created job's identifier.
+    
+    Raises:
+        RuntimeError: If the thread pool executor is unavailable after initialization.
     """
     init_executor()
     if EXECUTOR is None:
@@ -206,4 +224,4 @@ def cancel_job(job_id: str) -> None:
         return
     fut, ev = item
     ev.set()
-    fut.cancel()
+    fut.cancel()

app/db/models.py

@@ -209,6 +209,11 @@ def _migrate_episode_availability_table() -> None:
 
 
 def create_db_and_tables() -> None:
+    """
+    Ensure the application's SQLite database file and ORM tables exist, running any required schema migration first.
+    
+    Performs any necessary episode availability migration and creates tables defined on the module's private metadata, creating the database file if it does not already exist.
+    """
     logger.debug("Creating DB and tables if not exist.")
     try:
         _migrate_episode_availability_table()
@@ -244,6 +249,15 @@ def dispose_engine() -> None:
 
 # --- Jobs CRUD
 def create_job(session: Session, *, source_site: Optional[str] = None) -> Job:
+    """
+    Create and persist a new Job record in the database.
+    
+    Parameters:
+        source_site (Optional[str]): Optional source site identifier to associate with the job; if omitted the model's default is used.
+    
+    Returns:
+        Job: The created Job instance refreshed from the database (includes generated id and timestamps).
+    """
     logger.debug("Creating new job entry in DB.")
     try:
         job_kwargs: dict[str, Any] = {}
@@ -394,12 +408,12 @@ def get_availability(
 ) -> Optional[EpisodeAvailability]:
     """
     Retrieve the cached availability record for a specific episode identified by slug, season, episode, language, and site.
-
+    
     Parameters:
         site (str): Site identifier to query for (default "aniworld.to").
-
+    
     Returns:
-        EpisodeAvailability | None: The matching EpisodeAvailability if found, `None` otherwise.
+        EpisodeAvailability | None: `EpisodeAvailability` if a matching record exists, `None` otherwise.
     """
     logger.debug(
         f"Fetching availability for {slug} S{season}E{episode} {language} on {site}"
@@ -540,4 +554,4 @@ def delete_client_task(session: Session, hash: str) -> None:
         session.commit()
         logger.success(f"Deleted client task for hash {hash}")
     else:
-        logger.warning(f"Client task for hash {hash} not found, nothing to delete.")
+        logger.warning(f"Client task for hash {hash} not found, nothing to delete.")

app/utils/magnet.py

@@ -11,6 +11,15 @@
 
 
 def _site_prefix(site: str) -> str:
+    """
+    Determine the parameter prefix associated with a site.
+    
+    Parameters:
+        site (str): Hostname of the site (e.g., "aniworld.to" or "s.to").
+    
+    Returns:
+        str: "aw" for "aniworld.to", "sto" for "s.to", and "aw" for any other site (default). Logs a warning when defaulting.
+    """
     if site == "aniworld.to":
         return "aw"
     if site == "s.to":
@@ -20,6 +29,12 @@ def _site_prefix(site: str) -> str:
 
 
 def _hash_id(slug: str, season: int, episode: int, language: str) -> str:
+    """
+    Compute a deterministic SHA-1 identifier for the specified content.
+    
+    Returns:
+        A hexadecimal SHA-1 digest of the string "{slug}|{season}|{episode}|{language}" using UTF-8 encoding.
+    """
     logger.debug(
         f"Hashing ID with slug={slug}, season={season}, episode={episode}, language={language}"
     )
@@ -157,4 +172,4 @@ def parse_magnet(magnet: str) -> Dict[str, str]:
             raise ValueError(f"missing param: {req}")
 
     logger.success(f"Magnet parsed successfully: {flat}")
-    return flat
+    return flat

app/utils/probe_quality.py

@@ -18,7 +18,13 @@ def probe_episode_quality_once(
     direct_url: str, timeout: float = 6.0
 ) -> tuple[Optional[int], Optional[str], Dict[str, Any] | None]:
     """
-    Lädt KEINE Daten. Holt nur Info über Formate/Höhe/Codec.
+    Retrieve reported video height, video codec, and metadata from a direct media URL without downloading the media.
+    
+    Parameters:
+        timeout (float): Socket timeout in seconds used when probing the URL.
+    
+    Returns:
+        tuple: A three-item tuple (height, vcodec, info_dict) where `height` is the reported video height in pixels or `None` if unavailable, `vcodec` is the reported video codec string or `None` if unavailable, and `info_dict` is the extracted metadata dictionary from yt-dlp or `None` if extraction failed.
     """
     logger.debug(
         f"Probing episode quality for URL: {direct_url} with timeout={timeout}"
@@ -115,4 +121,4 @@ def probe_episode_quality(
             logger.warning(f"Provider '{prov}' failed: {e}")
             continue
     logger.error("No provider succeeded for this episode/language.")
-    return (False, None, None, None, None)
+    return (False, None, None, None, None)