sub2pod 0.3.0__tar.gz → 0.3.2__tar.gz

{sub2pod-0.3.0 → sub2pod-0.3.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: sub2pod
-Version: 0.3.0
+Version: 0.3.2
 Summary: Convert ytdl-sub output directories into podcast RSS feeds.
 Author: Marvin8
 Author-email: Marvin8 <marvin8@tuta.io>
 License: AGPL-3.0-or-later
-Requires-Dist: cyclopts~=4.18.0
+Requires-Dist: cyclopts~=4.21.0
 Requires-Dist: lxml~=6.1.1
 Requires-Python: >=3.12
 Project-URL: Issues, https://codeberg.org/marvin8/sub2pod/issues
@@ -15,10 +15,17 @@ Description-Content-Type: text/markdown
 
 # sub2pod
 
-[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENCE)
+[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENSE.md)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
-[![Woodpecker CI](https://ci.codeberg.org/api/badges/marvin8/sub2pod/status.svg)](https://ci.codeberg.org/marvin8/sub2pod)
+[![Docs](https://img.shields.io/badge/docs-sub2pod.marvin8.zone-blue)](https://sub2pod.marvin8.zone/latest/)
+[![CI](https://codeberg.org/marvin8/sub2pod/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/marvin8/sub2pod/actions)
+[![Downloads](https://img.shields.io/pepy/dt/sub2pod)](https://pepy.tech/project/sub2pod)
+[![gitleaks](https://img.shields.io/badge/gitleaks-checked-green)](https://github.com/gitleaks/gitleaks)
+[![pysentry](https://img.shields.io/badge/pysentry-checked-green)](https://pysentry.com)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![complexipy](https://img.shields.io/badge/complexipy-checked-blue)](https://github.com/rohaquinlop/complexipy)
 [![Codestyle: Ruff](https://img.shields.io/badge/codestyle-ruff-green)](https://docs.astral.sh/ruff/)
+[![AI-DECLARATION: copilot](https://img.shields.io/badge/%E4%B7%BC%20AI--DECLARATION-copilot-fee2e2?labelColor=fee2e2)](https://ai-declaration.md)
 
 Convert [ytdl-sub](https://github.com/jmbannon/ytdl-sub) output directories into
 standards-compliant podcast RSS feeds. Point it at a directory full of downloaded

{sub2pod-0.3.0 → sub2pod-0.3.2}/README.md

@@ -1,9 +1,16 @@
 # sub2pod
 
-[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENCE)
+[![Licence: AGPL-3.0-or-later](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENSE.md)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
-[![Woodpecker CI](https://ci.codeberg.org/api/badges/marvin8/sub2pod/status.svg)](https://ci.codeberg.org/marvin8/sub2pod)
+[![Docs](https://img.shields.io/badge/docs-sub2pod.marvin8.zone-blue)](https://sub2pod.marvin8.zone/latest/)
+[![CI](https://codeberg.org/marvin8/sub2pod/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/marvin8/sub2pod/actions)
+[![Downloads](https://img.shields.io/pepy/dt/sub2pod)](https://pepy.tech/project/sub2pod)
+[![gitleaks](https://img.shields.io/badge/gitleaks-checked-green)](https://github.com/gitleaks/gitleaks)
+[![pysentry](https://img.shields.io/badge/pysentry-checked-green)](https://pysentry.com)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![complexipy](https://img.shields.io/badge/complexipy-checked-blue)](https://github.com/rohaquinlop/complexipy)
 [![Codestyle: Ruff](https://img.shields.io/badge/codestyle-ruff-green)](https://docs.astral.sh/ruff/)
+[![AI-DECLARATION: copilot](https://img.shields.io/badge/%E4%B7%BC%20AI--DECLARATION-copilot-fee2e2?labelColor=fee2e2)](https://ai-declaration.md)
 
 Convert [ytdl-sub](https://github.com/jmbannon/ytdl-sub) output directories into
 standards-compliant podcast RSS feeds. Point it at a directory full of downloaded

{sub2pod-0.3.0 → sub2pod-0.3.2}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.10.0,<0.12.0"]
+requires = ["uv_build>=0.11.0,<0.12.0"]
 build-backend = "uv_build"
 
 [project]
 name = "sub2pod"
-version = "0.3.0"
+version = "0.3.2"
 authors = [
     { name = "Marvin8", email = "marvin8@tuta.io" },
 ]
@@ -13,23 +13,25 @@ readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }
 requires-python = ">=3.12"
 dependencies = [
-    "cyclopts~=4.18.0",
+    "cyclopts~=4.21.0",
     "lxml~=6.1.1",
 ]
 
 [dependency-groups]
 dev = [
     "bump-my-version~=1.4.1",
-    "complexipy~=5.6.1",
+    "complexipy~=6.0.1",
     "deptry~=0.25.1",
-    "git-cliff~=2.13.1",
     "nox-uv~=0.8.0",
-    "prek~=0.4.5",
-    "pysentry-rs~=0.4.6",
-    "ruff~=0.15.18",
-    "tryke~=0.0.29",
-    "ty~=0.0.51",
-    "uv~=0.11.22",
+    "prek~=0.4.9",
+    "pysentry-rs~=0.4.7",
+    "ruff~=0.15.21",
+    "tryke~=0.0.30",
+    "ty~=0.0.59",
+    "uv~=0.11.28",
+    "mkdocs~=1.6.1",
+    "mkdocs-material~=9.7.6",
+    "mike~=2.2.0",
 ]
 
 [project.scripts]
@@ -40,15 +42,6 @@ Issues = "https://codeberg.org/marvin8/sub2pod/issues"
 Source = "https://codeberg.org/marvin8/sub2pod"
 Changelog = "https://codeberg.org/marvin8/sub2pod/raw/branch/main/CHANGELOG.md"
 
-[tool.ruff]
-line-length = 88
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-
-[tool.ruff.lint.isort]
-force-single-line = true
-
 [tool.tryke]
 src = ["src", "."]
 
@@ -58,7 +51,7 @@ tag = true
 tag_name = "{new_version}"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
-message = ":wrench: bump: version {current_version} → {new_version}"
+message = ":bookmark: bump: version {current_version} → {new_version}"
 pre_commit_hooks = ["uv sync", "git add uv.lock"]
 
 [[tool.bumpversion.files]]
@@ -66,12 +59,13 @@ filename = "pyproject.toml"
 search = 'version = "{current_version}"'
 replace = 'version = "{new_version}"'
 
+[tool.uv]
+constraint-dependencies = [
+    "pydantic-settings>=2.14.2",   # GHSA-4xgf-cpjx-pc3j
+]
+
 [tool.zaojun]
 cache = true
 groups = true
 min-age = 7
 check-licenses = true
-
-[[tool.zaojun.license-ignore]]
-package = "git-cliff"
-reason = "Manually checked, it is licensed as Apache-2.0 OR MIT"

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/__init__.py

@@ -1,3 +1,5 @@
+"""Convert ytdl-sub output directories into podcast RSS feeds."""
+
 from importlib.metadata import version
 
 __version__ = version("sub2pod")

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/cli.py

@@ -1,3 +1,5 @@
+"""CLI entry point — walks a parent directory and generates podcast feeds."""
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 from pathlib import Path
 
@@ -21,12 +23,17 @@ def main(
     dry_run: bool = False,
     verbose: bool = False,
 ) -> None:
+    """Walk *parent_dir* for channel directories and generate ``feed.xml`` and ``opml.xml``.
+
+    Args:
+        parent_dir: Directory containing one or more ytdl-sub channel subdirectories.
+        base_url: Public base URL where audio files will be served (e.g. ``https://pod.example.com``).
+        dry_run: Print output file paths without writing anything.
+        verbose: Log channel names and episode titles to stdout.
+
+    """
     print(f"sub2pod {__version__}")
-    channel_dirs = sorted(
-        child
-        for child in parent_dir.iterdir()
-        if child.is_dir() and (child / "tvshow.nfo").exists()
-    )
+    channel_dirs = sorted(child for child in parent_dir.iterdir() if child.is_dir() and (child / "tvshow.nfo").exists())
     channels: list[tuple[ChannelInfo, Path]] = []
     for channel_dir in channel_dirs:
         channel_info = parse_channel_nfo(channel_dir / "tvshow.nfo")

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/discovery.py

@@ -1,4 +1,7 @@
+"""Episode discovery — find audio files and sidecar metadata in a channel directory."""
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
+import logging
 from dataclasses import dataclass
 from datetime import date
 from pathlib import Path
@@ -7,11 +10,24 @@ from sub2pod.nfo import EpisodeInfo
 from sub2pod.nfo import parse_episode_filename
 from sub2pod.nfo import parse_episode_nfo
 
+_logger = logging.getLogger(__name__)
+
 _AUDIO_SUFFIXES = frozenset({".opus", ".mp3", ".m4a"})
 
 
 @dataclass
 class Episode:
+    """A single podcast episode discovered from the filesystem.
+
+    Attributes:
+        audio_path: Absolute path to the audio file.
+        date: Publication date parsed from the filename prefix.
+        title: Episode title parsed from the filename or overridden by NFO sidecar.
+        info: Parsed NFO metadata, or ``None`` if no sidecar exists or parsing fails.
+        thumbnail_path: Path to a ``-thumb.jpg`` sidecar image, or ``None``.
+
+    """
+
     audio_path: Path
     date: date
     title: str
@@ -20,6 +36,21 @@ class Episode:
 
 
 def discover_episodes(channel_dir: Path) -> list[Episode]:
+    """Scan *channel_dir* for date-prefixed audio files and return them newest-first.
+
+    Audio files must match the ``YYYY-MM-DD - Title.ext`` naming convention.
+    Optional ``.nfo`` sidecars are parsed for richer metadata; a malformed
+    sidecar is logged at warning level and the episode falls back to
+    filename-only data.
+
+    Args:
+        channel_dir: A ytdl-sub channel output directory containing audio files
+            and optional ``.nfo`` / ``-thumb.jpg`` sidecars.
+
+    Returns:
+        Episodes sorted newest-first by date. Empty list if no audio files found.
+
+    """
     episodes: list[Episode] = []
     for audio_path in channel_dir.iterdir():
         if not audio_path.is_file() or audio_path.suffix.lower() not in _AUDIO_SUFFIXES:
@@ -34,7 +65,7 @@ def discover_episodes(channel_dir: Path) -> list[Episode]:
             try:
                 info = parse_episode_nfo(nfo_path)
             except Exception:
-                pass
+                _logger.warning("Failed to parse episode NFO: %s", nfo_path, exc_info=True)
         thumbnail_candidate = audio_path.with_suffix(".jpg")
         thumbnail_path = thumbnail_candidate if thumbnail_candidate.exists() else None
         episodes.append(

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/feed.py

@@ -1,3 +1,5 @@
+"""RSS 2.0 + iTunes namespace feed builder — generates ``feed.xml`` from channel data."""
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 from datetime import UTC
 from datetime import date
@@ -23,6 +25,16 @@ _ARTWORK_CANDIDATES = ("poster.jpg", "fanart.jpg")
 
 
 def find_channel_artwork(channel_dir: Path) -> Path | None:
+    """Return the path to ``poster.jpg`` or ``fanart.jpg`` in *channel_dir*, or ``None``.
+
+    Args:
+        channel_dir: Directory to search for artwork files.
+
+    Returns:
+        Path to the first existing artwork file (``poster.jpg`` preferred),
+        or ``None`` if neither exists.
+
+    """
     for candidate in _ARTWORK_CANDIDATES:
         artwork_path = channel_dir / candidate
         if artwork_path.exists():
@@ -31,6 +43,18 @@ def find_channel_artwork(channel_dir: Path) -> Path | None:
 
 
 def mime_type_for_audio_file(audio_path: Path) -> str:
+    """Map an audio file suffix to an RFC 4281 MIME type.
+
+    Args:
+        audio_path: Path to an audio file (only the suffix is inspected).
+
+    Returns:
+        MIME type string (e.g. ``"audio/mpeg"`` for ``.mp3``).
+
+    Raises:
+        ValueError: If the suffix is not a recognised audio format.
+
+    """
     suffix = audio_path.suffix.lower()
     mime_type = _MIME_TYPE_BY_SUFFIX.get(suffix)
     if mime_type is None:
@@ -39,6 +63,15 @@ def mime_type_for_audio_file(audio_path: Path) -> str:
 
 
 def format_pub_date(episode_date: date) -> str:
+    """Format *episode_date* as an RFC 2822 date string at midnight UTC.
+
+    Args:
+        episode_date: The episode's publication date (date only, no time).
+
+    Returns:
+        RFC 2822-formatted string like ``"Fri, 15 Mar 2024 00:00:00 +0000"``.
+
+    """
     midnight_utc = datetime(
         episode_date.year,
         episode_date.month,
@@ -49,6 +82,15 @@ def format_pub_date(episode_date: date) -> str:
 
 
 def format_itunes_duration(runtime_minutes: int) -> str:
+    """Convert *runtime_minutes* to an iTunes duration string (``HH:MM:SS``).
+
+    Args:
+        runtime_minutes: Episode duration in whole minutes.
+
+    Returns:
+        iTunes duration string like ``"01:02:00"`` for 62 minutes.
+
+    """
     total_seconds = runtime_minutes * 60
     hours = total_seconds // 3600
     remaining_seconds = total_seconds % 3600
@@ -58,6 +100,17 @@ def format_itunes_duration(runtime_minutes: int) -> str:
 
 
 def build_enclosure_url(base_url: str, channel_dir: Path, audio_path: Path) -> str:
+    """Build a percent-encoded public URL for an enclosure file.
+
+    Args:
+        base_url: Public base URL (trailing slash normalised).
+        channel_dir: The channel directory (its name is URL-encoded).
+        audio_path: Path to the media file (its filename is URL-encoded).
+
+    Returns:
+        Full public URL like ``"https://pod.example.com/My%20Show/ep.mp3"``.
+
+    """
     encoded_channel = quote(channel_dir.name, safe="")
     encoded_filename = quote(audio_path.name, safe="")
     return f"{base_url.rstrip('/')}/{encoded_channel}/{encoded_filename}"
@@ -70,6 +123,16 @@ def _populate_channel_metadata(
     base_url: str,
     episodes: list[Episode],
 ) -> None:
+    """Add title, link, description, language, artwork, category, and pubDate to a channel element.
+
+    Args:
+        channel_element: The ``<channel>`` XML element to populate.
+        channel_info: Parsed ``tvshow.nfo`` metadata.
+        channel_dir: Channel directory (for artwork discovery).
+        base_url: Public base URL for artwork link.
+        episodes: Episode list (first episode's date used for ``pubDate``).
+
+    """
     etree.SubElement(channel_element, "title").text = channel_info.title
     etree.SubElement(channel_element, "link").text = base_url
     etree.SubElement(channel_element, "description").text = channel_info.title
@@ -77,10 +140,7 @@ def _populate_channel_metadata(
 
     artwork_path = find_channel_artwork(channel_dir)
     if artwork_path is not None:
-        artwork_url = (
-            f"{base_url.rstrip('/')}/{quote(channel_dir.name, safe='')}"
-            f"/{quote(artwork_path.name, safe='')}"
-        )
+        artwork_url = f"{base_url.rstrip('/')}/{quote(channel_dir.name, safe='')}/{quote(artwork_path.name, safe='')}"
         itunes_image = etree.SubElement(channel_element, f"{_ITUNES}image")
         itunes_image.set("href", artwork_url)
 
@@ -89,9 +149,7 @@ def _populate_channel_metadata(
         itunes_category.set("text", channel_info.genre)
 
     if episodes:
-        etree.SubElement(channel_element, "pubDate").text = format_pub_date(
-            episodes[0].date
-        )
+        etree.SubElement(channel_element, "pubDate").text = format_pub_date(episodes[0].date)
 
 
 def _append_episode_item(
@@ -100,6 +158,15 @@ def _append_episode_item(
     channel_dir: Path,
     base_url: str,
 ) -> None:
+    """Append an ``<item>`` element with title, description, enclosure, pubDate, and optional metadata.
+
+    Args:
+        channel_element: The ``<channel>`` XML element to append the item to.
+        episode: Discovered episode with optional info and thumbnail.
+        channel_dir: Channel directory (for enclosure URL building).
+        base_url: Public base URL for enclosure and image links.
+
+    """
     item_element = etree.SubElement(channel_element, "item")
 
     episode_title = episode.info.title if episode.info is not None else episode.title
@@ -108,11 +175,7 @@ def _append_episode_item(
     if episode.info is not None and episode.info.plot is not None:
         etree.SubElement(item_element, "description").text = episode.info.plot
 
-    pub_date = (
-        episode.info.aired
-        if (episode.info is not None and episode.info.aired is not None)
-        else episode.date
-    )
+    pub_date = episode.info.aired if (episode.info is not None and episode.info.aired is not None) else episode.date
     etree.SubElement(item_element, "pubDate").text = format_pub_date(pub_date)
 
     enclosure_url = build_enclosure_url(base_url, channel_dir, episode.audio_path)
@@ -146,17 +209,25 @@ def build_feed_xml(
     episodes: list[Episode],
     base_url: str,
 ) -> bytes:
+    """Build a complete RSS 2.0 + iTunes podcast feed as UTF-8 XML bytes.
+
+    Args:
+        channel_dir: Channel directory (used for artwork discovery and URL building).
+        channel_info: Parsed ``tvshow.nfo`` metadata (title, genre).
+        episodes: Episodes to include, sorted newest-first.
+        base_url: Public base URL for enclosure and artwork links.
+
+    Returns:
+        UTF-8 encoded XML string with XML declaration.
+
+    """
     nsmap = {"itunes": _ITUNES_NS}
     root = etree.Element("rss", attrib={"version": "2.0"}, nsmap=nsmap)
     channel_element = etree.SubElement(root, "channel")
-    _populate_channel_metadata(
-        channel_element, channel_info, channel_dir, base_url, episodes
-    )
+    _populate_channel_metadata(channel_element, channel_info, channel_dir, base_url, episodes)
     for episode in episodes:
         _append_episode_item(channel_element, episode, channel_dir, base_url)
-    return etree.tostring(
-        root, xml_declaration=True, encoding="UTF-8", pretty_print=True
-    )
+    return etree.tostring(root, xml_declaration=True, encoding="UTF-8", pretty_print=True)
 
 
 def write_feed(
@@ -165,6 +236,18 @@ def write_feed(
     episodes: list[Episode],
     base_url: str,
 ) -> Path:
+    """Build the feed and write it to ``channel_dir/feed.xml``, returning the path.
+
+    Args:
+        channel_dir: Channel directory where ``feed.xml`` will be written.
+        channel_info: Parsed ``tvshow.nfo`` metadata.
+        episodes: Episodes to include, sorted newest-first.
+        base_url: Public base URL for enclosure and artwork links.
+
+    Returns:
+        Path to the written ``feed.xml`` file.
+
+    """
     feed_path = channel_dir / "feed.xml"
     feed_path.write_bytes(build_feed_xml(channel_dir, channel_info, episodes, base_url))
     return feed_path

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/nfo.py

@@ -1,3 +1,5 @@
+"""Kodi NFO parser — extracts channel and episode metadata from XML sidecars."""
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 import re
 from dataclasses import dataclass
@@ -9,12 +11,31 @@ from lxml import etree  # ty: ignore[unresolved-import]
 
 @dataclass
 class ChannelInfo:
+    """Metadata parsed from a ``tvshow.nfo`` file.
+
+    Attributes:
+        title: Show title.
+        genre: Category string, or ``None`` if absent.
+
+    """
+
     title: str
     genre: str | None
 
 
 @dataclass
 class EpisodeInfo:
+    """Metadata parsed from a per-episode ``.nfo`` sidecar.
+
+    Attributes:
+        title: Episode title.
+        plot: Episode description / show notes.
+        aired: Original air date, or ``None``.
+        runtime: Duration in minutes, or ``None``.
+        original_url: Source webpage URL (e.g. YouTube), or ``None``.
+
+    """
+
     title: str
     plot: str | None
     aired: date | None
@@ -23,6 +44,16 @@ class EpisodeInfo:
 
 
 def parse_channel_nfo(nfo_path: Path) -> ChannelInfo:
+    """Parse a Kodi ``tvshow.nfo`` file and return channel metadata.
+
+    Args:
+        nfo_path: Path to a ``tvshow.nfo`` XML file.
+
+    Returns:
+        Parsed channel metadata. Title defaults to ``""`` if absent;
+        genre is ``None`` if absent.
+
+    """
     root = etree.parse(nfo_path).getroot()
     return ChannelInfo(
         title=root.findtext("title") or "",
@@ -31,6 +62,20 @@ def parse_channel_nfo(nfo_path: Path) -> ChannelInfo:
 
 
 def parse_episode_nfo(nfo_path: Path) -> EpisodeInfo:
+    """Parse a per-episode Kodi ``.nfo`` sidecar and return episode metadata.
+
+    Gracefully handles missing or malformed ``aired`` / ``runtime`` values
+    by returning ``None`` for those fields. Supports both Kodi-style
+    (``<aired>``, ``<plot>``) and ytdl-sub-style (``<upload_date>``,
+    ``<description>``) element names.
+
+    Args:
+        nfo_path: Path to an episode ``.nfo`` XML sidecar.
+
+    Returns:
+        Parsed episode metadata. All optional fields may be ``None``.
+
+    """
     root = etree.parse(nfo_path).getroot()
     aired_text = root.findtext("aired") or root.findtext("upload_date")
     runtime_text = root.findtext("runtime")
@@ -61,6 +106,16 @@ EPISODE_FILENAME_PATTERN = re.compile(r"^(\d{4}-\d{2}-\d{2}) - (.+)\.[^.]+$")
 
 
 def parse_episode_filename(filename: str) -> tuple[date, str] | None:
+    """Extract a date and title from a ``YYYY-MM-DD - Title.ext`` filename.
+
+    Args:
+        filename: A filename like ``"2024-03-15 - My Episode.opus"``.
+
+    Returns:
+        A ``(date, title)`` tuple, or ``None`` if the filename does not match
+        the expected pattern or contains an invalid calendar date.
+
+    """
     match = EPISODE_FILENAME_PATTERN.match(filename)
     if not match:
         return None

{sub2pod-0.3.0 → sub2pod-0.3.2}/src/sub2pod/opml.py

@@ -1,3 +1,5 @@
+"""OPML builder — generates an ``opml.xml`` index listing all channel feeds."""
+
 # SPDX-License-Identifier: AGPL-3.0-or-later
 from pathlib import Path
 from urllib.parse import quote
@@ -11,6 +13,17 @@ def build_opml_xml(
     channels: list[tuple[ChannelInfo, Path]],
     base_url: str,
 ) -> bytes:
+    """Build an OPML 2.0 document listing each channel's ``feed.xml`` URL as an outline.
+
+    Args:
+        channels: List of ``(ChannelInfo, channel_dir)`` tuples.
+        base_url: Public base URL (trailing slash normalised) for constructing
+            ``xmlUrl`` attributes.
+
+    Returns:
+        UTF-8 encoded OPML 2.0 XML with XML declaration.
+
+    """
     root = etree.Element("opml", attrib={"version": "2.0"})
     head = etree.SubElement(root, "head")
     etree.SubElement(head, "title").text = "Podcasts"
@@ -22,9 +35,7 @@ def build_opml_xml(
         outline.set("text", channel_info.title)
         outline.set("title", channel_info.title)
         outline.set("xmlUrl", feed_url)
-    return etree.tostring(
-        root, xml_declaration=True, encoding="UTF-8", pretty_print=True
-    )
+    return etree.tostring(root, xml_declaration=True, encoding="UTF-8", pretty_print=True)
 
 
 def write_opml(
@@ -32,6 +43,17 @@ def write_opml(
     channels: list[tuple[ChannelInfo, Path]],
     base_url: str,
 ) -> Path:
+    """Build the OPML and write it to ``parent_dir/opml.xml``, returning the path.
+
+    Args:
+        parent_dir: Root directory where ``opml.xml`` will be written.
+        channels: List of ``(ChannelInfo, channel_dir)`` tuples.
+        base_url: Public base URL for constructing ``xmlUrl`` attributes.
+
+    Returns:
+        Path to the written ``opml.xml`` file.
+
+    """
     opml_path = parent_dir / "opml.xml"
     opml_path.write_bytes(build_opml_xml(channels, base_url))
     return opml_path