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

Docstrings generation was requested by @Zzackllack.

* #8 (comment)

The following files were modified:

* `app/api/qbittorrent/torrents.py`
* `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/naming.py`
* `app/utils/probe_quality.py`
* `app/utils/title_resolver.py`
* `tests/test_torznab_utils.py`

Author: coderabbitai[bot]

app/api/qbittorrent/torrents.py

@@ -37,7 +37,24 @@ def torrents_add(
     paused: Optional[bool] = Form(default=False),
     tags: Optional[str] = Form(default=None),
 ):
-    """Sonarr posts magnet URL(s) here. We accept the first one."""
+    """
+    Accept a Sonarr POST of magnet URL(s), schedule the download for the first magnet, and record a ClientTask.
+    
+    Parses the first magnet line from `urls`, extracts metadata (slug, season, episode, language, site, name, and torrent hash), schedules a download job, and upserts a ClientTask with the job and save path. If `savepath` is not provided, the configured download directory is used; if a public save path is configured it is stored as the task's save path.
+    
+    Parameters:
+        urls (str): One or more magnet URLs separated by newlines; only the first line is processed.
+        savepath (Optional[str]): Optional explicit save directory for the torrent. If omitted, the configured DOWNLOAD_DIR is used; a configured QBIT_PUBLIC_SAVE_PATH will be preferred when stored.
+        category (Optional[str]): Optional category to record with the task.
+        paused (Optional[bool]): If true, the created task is marked as queued instead of downloading.
+        tags (Optional[str]): Optional tags provided by the caller (accepted but not otherwise interpreted here).
+    
+    Returns:
+        PlainTextResponse: A plain-text response with the body "Ok." on success.
+    
+    Raises:
+        HTTPException: Raised with status 400 when `urls` is empty or missing.
+    """
     logger.info(f"Received request to add torrent(s): {urls}")
     if not urls:
         logger.warning("No URLs provided in torrents_add.")
@@ -333,4 +350,4 @@ def torrents_delete(
             logger.warning(f"Exception during file deletion for hash {h}: {e}")
         delete_client_task(session, h)
         logger.success(f"Deleted client task for hash {h}")
-    return PlainTextResponse("Ok.")
+    return PlainTextResponse("Ok.")

app/api/torznab/api.py

@@ -37,6 +37,32 @@ def torznab_api(
     limit: int = Query(default=50),
     session: Session = Depends(get_session),
 ) -> Response:
+    """
+    Handle torznab-compatible API requests and return the corresponding XML response.
+    
+    Supports three request modes determined by `t`:
+    - "caps": return the server capabilities XML.
+    - "search": perform a generic/preview search and return an RSS feed with zero or more synthetic or discovered items.
+    - "tvsearch": search for a specific TV episode (requires `q` and `season`; `ep` defaults to 1 if omitted) and return an RSS feed of available releases.
+    
+    Parameters:
+        request: FastAPI Request object for the incoming HTTP request.
+        t (str): One of "caps", "search", or "tvsearch", selecting the API mode.
+        apikey (Optional[str]): API key for access control; presence/validity is required.
+        q (Optional[str]): Query string identifying a series or search terms.
+        season (Optional[int]): Season number for TV episode searches; required for "tvsearch".
+        ep (Optional[int]): Episode number for TV episode searches; defaults to 1 for previews when omitted.
+        cat (Optional[str]): Category filter (passed through but not required).
+        offset (int): Result offset for paging.
+        limit (int): Maximum number of RSS items to include.
+        session: Database session (provided via dependency injection; omitted from docs for common DI services).
+    
+    Returns:
+        Response: A FastAPI Response containing XML:
+          - application/xml; charset=utf-8 for "caps"
+          - application/rss+xml; charset=utf-8 for "search" and "tvsearch"
+          - HTTP 400 is raised for unknown `t` values; empty RSS feeds are returned when required parameters or slug resolution are missing.
+    """
     logger.info(
         "Torznab request: t={}, q={}, season={}, ep={}, cat={}, offset={}, limit={}, apikey={}".format(
             t, q, season, ep, cat, offset, limit, "<set>" if apikey else "<none>"
@@ -362,4 +388,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

@@ -66,17 +66,31 @@ def _caps_xml() -> str:
 
 
 def _normalize_tokens(s: str) -> List[str]:
+    """
+    Split a string into lowercase alphanumeric tokens.
+    
+    Non-alphanumeric characters are treated as token separators; letters are lowercased and digits are preserved.
+    
+    Parameters:
+        s (str): Input string to tokenize.
+    
+    Returns:
+        List[str]: A list of lowercase alphanumeric tokens extracted from the input.
+    """
     logger.debug(f"Normalizing tokens for string: '{s}'")
     return "".join(ch.lower() if ch.isalnum() else " " for ch in s).split()
 
 
 def _slug_from_query(q: str, site: Optional[str] = None) -> Optional[Tuple[str, str]]:
-    """Map free-text query -> (site, slug) using main and alternative titles.
+    """
+    Resolve a free-text query to the best-matching site and canonical slug.
     
-    If site is specified, only searches that site. Otherwise searches all enabled sites.
-    Returns (site, slug) tuple or None.
+    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.
     
-    Import from the title_resolver module for the actual implementation.
+    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.
     """
     logger.debug(f"Resolving slug from query: '{q}', site filter: {site}")
     from app.utils.title_resolver import slug_from_query
@@ -95,6 +109,16 @@ def _slug_from_query(q: str, site: Optional[str] = None) -> Optional[Tuple[str,
 
 
 def _add_torznab_attr(item: ET.Element, name: str, value: str) -> None:
+    """
+    Add a torznab `attr` subelement to an RSS item.
+    
+    Creates a `torznab:attr` element (namespace http://torznab.com/schemas/2015/feed) as a child of `item` and sets its `name` and `value` attributes.
+    
+    Parameters:
+        item (xml.etree.ElementTree.Element): The RSS `<item>` element to which the torznab attribute will be added.
+        name (str): The `name` attribute to set on the torznab `attr` element.
+        value (str): The `value` attribute to set on the torznab `attr` element.
+    """
     attr = ET.SubElement(item, "{http://torznab.com/schemas/2015/feed}attr")
     attr.set("name", name)
     attr.set("value", value)
@@ -177,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

@@ -92,6 +92,22 @@ def build_episode(
     episode: Optional[int] = None,
     site: str = "aniworld.to",
 ) -> Episode:
+    """
+    Construct an Episode from a direct link or from slug, season, and episode with the given 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").
+    
+    Returns:
+        Episode: An Episode constructed from `link` (if present) or from `slug`, `season`, and `episode`.
+    
+    Raises:
+        ValueError: If neither `link` nor the combination of `slug`, `season`, and `episode` are provided.
+    """
     logger.info(
         f"Building episode: link={link}, slug={slug}, season={season}, episode={episode}, site={site}"
     )
@@ -307,6 +323,31 @@ def download_episode(
     stop_event: Optional[threading.Event] = None,
     site: str = "aniworld.to",
 ) -> Path:
+    """
+    Download an episode to the specified directory, resolving a direct stream URL with provider fallback and proxy-aware retry logic.
+    
+    This function builds an Episode from the provided identifiers, attempts to resolve a direct download URL (optionally preferring a provider), downloads the media via yt-dlp with progress callbacks and cancellation support, and renames the downloaded file into the repository's release naming schema. If extraction or download fails, controlled fallback attempts are performed (no-proxy re-resolution and alternate providers) before failing.
+    
+    Parameters:
+        link (Optional[str]): Direct episode page URL; if provided, used instead of slug/season/episode.
+        slug (Optional[str]): Series identifier used to construct an Episode when `link` is not given.
+        season (Optional[int]): Season number to construct an Episode when `link` is not given.
+        episode (Optional[int]): Episode number to construct an Episode when `link` is not given.
+        provider (Optional[Provider]): Preferred provider name to try first when resolving a direct URL.
+        language (str): Desired language label (will be normalized); used when resolving available streams.
+        dest_dir (Path): Destination directory where the temporary download will be written.
+        title_hint (Optional[str]): Hint for the temporary output filename; if omitted and slug/season/episode are given, a default is generated.
+        cookiefile (Optional[Path]): Path to a cookies file passed to yt-dlp, if required by the provider/site.
+        progress_cb (Optional[ProgressCb]): Optional callback that receives yt-dlp progress dictionaries.
+        stop_event (Optional[threading.Event]): Optional event that, when set, requests download cancellation.
+        site (str): Site identifier to use when constructing the Episode (defaults to "aniworld.to").
+    
+    Returns:
+        Path: Final path to the renamed release file.
+    
+    Raises:
+        DownloadError: When URL resolution or download ultimately fails after all fallback attempts.
+    """
     language = _normalize_language(language)
     logger.info(
         f"Starting download_episode: link={link}, slug={slug}, season={season}, episode={episode}, provider={provider}, language={language}, dest_dir={dest_dir}, site={site}"
@@ -448,4 +489,4 @@ def download_episode(
         site=site,
     )
     logger.success(f"Final file path: {final_path}")
-    return final_path
+    return final_path

app/core/scheduler.py

@@ -113,6 +113,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.
+    
+    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)
+            - '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:
             site = req.get("site", "aniworld.to")
@@ -188,4 +206,4 @@ def cancel_job(job_id: str) -> None:
         return
     fut, ev = item
     ev.set()
-    fut.cancel()
+    fut.cancel()

app/db/models.py

@@ -253,6 +253,25 @@ def upsert_availability(
     extra: Optional[dict] = None,
     site: str = "aniworld.to",
 ) -> EpisodeAvailability:
+    """
+    Create or update the cached availability record for a specific episode/language on a site and persist the result.
+    
+    Parameters:
+        session (Session): Database session used to read and persist the record.
+        slug (str): Series identifier.
+        season (int): Season number.
+        episode (int): Episode number.
+        language (str): Language code for the availability entry.
+        available (bool): Whether the episode is available.
+        height (Optional[int]): Video height in pixels, or `None` if unknown.
+        vcodec (Optional[str]): Video codec identifier, or `None` if unknown.
+        provider (Optional[str]): Provider name/source, or `None` if unknown.
+        extra (Optional[dict]): Optional auxiliary metadata for the record.
+        site (str): Site identifier to scope the availability entry.
+    
+    Returns:
+        EpisodeAvailability: The persisted availability record reflecting the created or updated state.
+    """
     logger.debug(f"Upserting availability for {slug} S{season}E{episode} {language} on {site}")
     rec = session.get(EpisodeAvailability, (slug, season, episode, language, site))
     if rec is None:
@@ -295,6 +314,15 @@ def upsert_availability(
 def get_availability(
     session: Session, *, slug: str, season: int, episode: int, language: str, site: str = "aniworld.to"
 ) -> 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.
+    """
     logger.debug(f"Fetching availability for {slug} S{season}E{episode} {language} on {site}")
     rec = session.get(EpisodeAvailability, (slug, season, episode, language, site))
     if rec:
@@ -307,6 +335,18 @@ def get_availability(
 def list_available_languages_cached(
     session: Session, *, slug: str, season: int, episode: int, site: str = "aniworld.to"
 ) -> List[str]:
+    """
+    List languages with fresh cached availability for a specific episode on a site.
+    
+    Parameters:
+        slug (str): Episode/series identifier used to look up availability.
+        season (int): Season number of the episode.
+        episode (int): Episode number within the season.
+        site (str): Site identifier to scope the availability records (defaults to "aniworld.to").
+    
+    Returns:
+        List[str]: Languages that have a cached availability record considered fresh.
+    """
     logger.debug(f"Listing available cached languages for {slug} S{season}E{episode} on {site}")
     rows = session.exec(
         select(EpisodeAvailability).where(
@@ -349,6 +389,16 @@ def upsert_client_task(
     state: str = "queued",
     site: str = "aniworld.to",
 ) -> ClientTask:
+    """
+    Create or update a ClientTask record for the given torrent/file hash.
+    
+    Parameters:
+        hash (str): Unique identifier for the client task (primary key).
+        site (str): Site identifier to store on the record; defaults to "aniworld.to".
+    
+    Returns:
+        ClientTask: The inserted or updated ClientTask instance refreshed from the database.
+    """
     logger.debug(f"Upserting client task for hash {hash} on site {site}")
     rec = session.get(ClientTask, hash)
     if rec is None:
@@ -408,4 +458,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

@@ -32,8 +32,19 @@ def build_magnet(
     site: str = "aniworld.to",
 ) -> str:
     """
-    Synthetischer Magnet mit notwendiger Payload für den Shim.
-    Now includes site parameter to distinguish between aniworld.to and s.to content.
+    Constructs a site-aware magnet URI containing metadata required by the Shim.
+    
+    Parameters:
+        title (str): Display name to include as the magnet's `dn` parameter.
+        slug (str): Content identifier used in the site-prefixed slug parameter.
+        season (int): Season number included as the site-prefixed `s` parameter.
+        episode (int): Episode number included as the site-prefixed `e` parameter.
+        language (str): Language code included as the site-prefixed `lang` parameter.
+        provider (str | None): Optional provider identifier included as the site-prefixed `provider` parameter when provided.
+        site (str): Source site; selects the parameter prefix — `"aw"` when `"aniworld.to"`, `"sto"` otherwise.
+    
+    Returns:
+        magnet_uri (str): A magnet URI that includes `xt`, `dn`, and site-prefixed metadata (slug, s, e, lang, site, and optionally provider).
     """
     logger.debug(
         f"Building magnet for title='{title}', slug='{slug}', season={season}, episode={episode}, language='{language}', provider='{provider}', site='{site}'"
@@ -75,8 +86,21 @@ def build_magnet(
 
 def parse_magnet(magnet: str) -> Dict[str, str]:
     """
-    Extrahiert unsere Payload (aw_* or sto_*), dn, xt.
-    Now supports both aniworld (aw_*) and s.to (sto_*) prefixes.
+    Parse a magnet URI and extract its payload parameters.
+    
+    Supports payloads using either the "aw_" (aniworld) or "sto_" (s.to) prefix; defaults to "aw_" if no prefix is detected.
+    
+    Parameters:
+        magnet (str): A magnet URI beginning with "magnet:?". Query parameters are parsed and flattened to single string values.
+    
+    Returns:
+        Dict[str, str]: A mapping of parameter names to their single string value. The returned dict will include at minimum:
+            - "dn" (display name)
+            - "xt" (exact topic, e.g., "urn:btih:...")
+            - "{prefix}_slug", "{prefix}_s", "{prefix}_e", "{prefix}_lang" where "{prefix}" is "aw" or "sto".
+    
+    Raises:
+        ValueError: If the input does not start with "magnet:?" or if any required parameter is missing.
     """
     logger.debug(f"Parsing magnet URI: {magnet}")
     if not magnet.startswith("magnet:?"):
@@ -112,4 +136,4 @@ def parse_magnet(magnet: str) -> Dict[str, str]:
             raise ValueError(f"missing magnet param: {req}")
 
     logger.success(f"Magnet parsed successfully: {flat}")
-    return flat
+    return flat