Coverage for downtify/podcasts.py: 72%
511 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Podcast subscriptions: RSS feeds, episode downloads, and playback state.
3Podcasts are not Spotify tracks routed through YouTube — every episode is
4already a plain audio file sitting at an RSS ``<enclosure>`` URL, so the
5whole yt-dlp/matching pipeline in :mod:`downtify.downloader` is beside
6the point here. This module is the podcast equivalent of that file: it
7turns a link into episodes, downloads and tags them, and keeps a show in
8sync on a schedule.
10Three ways in, one destination (an RSS feed URL):
12* A direct RSS feed URL is fetched and parsed as-is.
13* A Spotify ``show`` or ``episode`` link only ever gives a name (the
14 embed page renders the show's latest episode; there is no "show"
15 entity to scrape — see :func:`downtify.spotify.fetch_embed_entity`).
16 That name is matched against the iTunes podcast directory
17 (:mod:`downtify.itunes`) to find the feed. A Spotify-exclusive show
18 has no public feed and is reported as such, not silently ignored.
19* Free-text search also goes through the iTunes podcast directory.
21Episodes are identified by RSS ``guid`` (falling back to the enclosure
22URL for feeds sloppy enough to omit one), so re-fetching a feed never
23loses track of what is already downloaded, and an episode the user
24deleted on purpose (``dismissed``) is never re-downloaded — unlike one
25a retention sweep pruned automatically, which is fair game again if the
26show's retention setting is later raised. See ``episode_plan`` for the
27exact retention rules.
29Scheduling reuses :mod:`downtify.monitor`'s watch table (kind
30``"podcast"``, keyed by feed URL) rather than a second background loop;
31this module only supplies what a podcast watch does when it's checked
32(:func:`sync_show`) and everything specific to podcasts (shows,
33episodes, tags, playback position) that the generic watch row knows
34nothing about.
35"""
37from __future__ import annotations
39import contextlib
40import html
41import re
42from collections.abc import Iterator
43from dataclasses import dataclass, field
44from datetime import datetime, timezone
45from html.parser import HTMLParser
46from pathlib import Path
47from typing import Any, Callable, Optional
49import feedparser
50import httpx
51from loguru import logger
52from mutagen.id3 import (
53 APIC,
54 COMM,
55 ID3,
56 TALB,
57 TCON,
58 TDRC,
59 TIT2,
60 TPE1,
61 TPE2,
62 TPOS,
63 TRCK,
64)
65from mutagen.mp3 import MP3
66from mutagen.mp4 import MP4, MP4Cover
67from mutagen.oggopus import OggOpus
68from mutagen.oggvorbis import OggVorbis
70from . import itunes
71from .db.config import Dialect
72from .db.core import Connection, Database, as_database
73from .db.dialect import insert_returning_id
74from .image_size import image_short_side
75from .library_catalog import PODCASTS_DIRNAME
76from .m3u import sanitize_playlist_name
77from .spotify import fetch_embed_entity, parse_spotify_url
79_FEED_TIMEOUT = 20
80_DOWNLOAD_TIMEOUT = httpx.Timeout(15, read=120)
81_CHUNK_SIZE = 1 << 16 # 64 KiB
83#: Enclosure MIME type -> file extension. Only audio; a video enclosure
84#: is dropped at parse time (video podcasts are a non-goal — see the
85#: module docstring in the feature docs).
86_AUDIO_EXT_BY_MIME = {
87 'audio/mpeg': 'mp3',
88 'audio/mp3': 'mp3',
89 'audio/mp4': 'm4a',
90 'audio/x-m4a': 'm4a',
91 'audio/aac': 'aac',
92 'audio/ogg': 'ogg',
93 'audio/opus': 'opus',
94 'audio/x-opus+ogg': 'opus',
95}
98class PodcastFeedNotFoundError(Exception):
99 """Raised when a Spotify show/episode has no public RSS feed.
101 Carries the show name Spotify gave us, so the caller can tell the
102 user plainly what wasn't found rather than reporting a generic
103 failure.
104 """
106 def __init__(self, show_name: str) -> None:
107 self.show_name = show_name
108 super().__init__(f'No public RSS feed found for {show_name!r}')
111def _now_iso() -> str:
112 return datetime.now(timezone.utc).isoformat()
115# ── HTML show notes → plain text ───────────────────────────────────
116class _TextExtractor(HTMLParser):
117 """Strips tags from podcast descriptions, which are near-always HTML.
119 Rendering that HTML would mean sanitizing it against XSS for no
120 real benefit (show notes are a paragraph or two, not a document) —
121 plain text is the deliberately simpler, safer choice. Block-level
122 tags become line breaks so paragraphs stay readable.
123 """
125 _BLOCK_TAGS = frozenset({
126 'p',
127 'br',
128 'div',
129 'li',
130 'ul',
131 'ol',
132 'h1',
133 'h2',
134 'h3',
135 'h4',
136 })
138 def __init__(self) -> None:
139 super().__init__(convert_charrefs=True)
140 self._parts: list[str] = []
142 def handle_starttag(self, tag: str, attrs: Any) -> None:
143 if tag in self._BLOCK_TAGS:
144 self._parts.append('\n')
146 def handle_endtag(self, tag: str) -> None:
147 if tag in self._BLOCK_TAGS:
148 self._parts.append('\n')
150 def handle_data(self, data: str) -> None:
151 self._parts.append(data)
153 def text(self) -> str:
154 joined = html.unescape(''.join(self._parts))
155 # Collapse the blank-line runs the tag-per-line pass above
156 # tends to produce, and trim trailing spaces on each line.
157 lines = [ln.strip() for ln in joined.splitlines()]
158 out: list[str] = []
159 for ln in lines:
160 if ln or (out and out[-1]):
161 out.append(ln)
162 return '\n'.join(out).strip()
165def strip_html(text: str) -> str:
166 """Plain-text rendering of a (possibly-HTML) show/episode description."""
168 if not text:
169 return ''
170 if '<' not in text:
171 return html.unescape(text).strip()
172 parser = _TextExtractor()
173 try:
174 parser.feed(text)
175 except Exception:
176 # Malformed markup: better a few stray tags than no description.
177 return re.sub(r'<[^>]+>', ' ', text).strip()
178 return parser.text()
181def _parse_itunes_duration(raw: Any) -> float:
182 """``itunes:duration`` as seconds: ``"1:02:03"``, ``"12:34"`` or ``"754"``."""
184 text = str(raw or '').strip()
185 if not text:
186 return 0.0
187 if ':' not in text:
188 try:
189 return float(text)
190 except ValueError:
191 return 0.0
192 parts = text.split(':')
193 try:
194 nums = [float(p) for p in parts]
195 except ValueError:
196 return 0.0
197 seconds = 0.0
198 for n in nums:
199 seconds = seconds * 60 + n
200 return seconds
203def _safe_int(raw: Any) -> Optional[int]:
204 try:
205 return int(str(raw).strip())
206 except (TypeError, ValueError):
207 return None
210# ── Parsed feed shape ───────────────────────────────────────────────
211@dataclass
212class EpisodeInfo:
213 guid: str
214 title: str
215 description: str
216 published_at: str # ISO 8601 UTC, or '' when unparseable
217 duration_seconds: float
218 season_number: Optional[int]
219 episode_number: Optional[int]
220 enclosure_url: str
221 enclosure_type: str
224@dataclass
225class ParsedFeed:
226 name: str
227 author: str
228 description: str
229 artwork_url: str
230 feed_url: str
231 episodes: list[EpisodeInfo] = field(default_factory=list)
234def _entry_enclosure(entry: Any) -> Optional[tuple[str, str]]:
235 fallback: Optional[tuple[str, str]] = None
236 for enc in entry.get('enclosures') or []:
237 url = str(enc.get('href') or '').strip()
238 mime = (
239 str(enc.get('type') or '')
240 .split(';', maxsplit=1)[0]
241 .strip()
242 .lower()
243 )
244 if not url:
245 continue
246 if mime.startswith('audio/'):
247 return url, mime
248 # Sloppy feeds can omit the type or label audio as generic binary.
249 # Keep their first candidate, but prefer explicit audio anywhere.
250 if fallback is None and mime in {'', 'application/octet-stream'}:
251 fallback = url, mime
252 return fallback
255def parse_feed_bytes(content: bytes, feed_url: str) -> ParsedFeed:
256 """Parse RSS/Atom bytes into a :class:`ParsedFeed`.
258 ``feedparser`` is deliberately used instead of a hand-rolled
259 ``xml.etree`` reader: real podcast feeds are routinely malformed
260 (unescaped ``&``, mismatched encodings, non-standard date formats),
261 and surviving that is feedparser's entire job — it sets a ``bozo``
262 flag rather than raising, and still returns whatever it could
263 recover. Explicit audio enclosures take precedence over untyped or
264 generic-binary fallbacks. Episodes with only non-audio attachments
265 are dropped rather than listed as unplayable.
266 """
268 parsed = feedparser.parse(content)
269 if parsed.bozo:
270 logger.info(
271 'Podcast feed {} parsed with warnings: {}',
272 feed_url,
273 parsed.get('bozo_exception'),
274 )
275 feed = parsed.feed
276 name = str(feed.get('title') or '').strip()
277 author = str(feed.get('author') or feed.get('itunes_author') or '').strip()
278 description = strip_html(
279 str(feed.get('subtitle') or feed.get('summary') or '')
280 )
281 image = feed.get('image') or {}
282 artwork_url = str(
283 (image.get('href') if isinstance(image, dict) else '') or ''
284 ).strip()
286 episodes: list[EpisodeInfo] = []
287 for entry in parsed.entries:
288 enclosure = _entry_enclosure(entry)
289 if enclosure is None:
290 continue
291 url, mime = enclosure
292 guid = str(entry.get('id') or entry.get('guid') or url).strip()
293 if not guid:
294 continue
295 published_at = ''
296 if entry.get('published_parsed'):
297 try:
298 published_at = datetime(
299 *entry.published_parsed[:6], tzinfo=timezone.utc
300 ).isoformat()
301 except (TypeError, ValueError):
302 published_at = ''
303 episodes.append(
304 EpisodeInfo(
305 guid=guid,
306 title=str(entry.get('title') or 'Untitled episode').strip(),
307 description=strip_html(str(entry.get('summary') or '')),
308 published_at=published_at,
309 duration_seconds=_parse_itunes_duration(
310 entry.get('itunes_duration')
311 ),
312 season_number=_safe_int(entry.get('itunes_season')),
313 episode_number=_safe_int(entry.get('itunes_episode')),
314 enclosure_url=url,
315 enclosure_type=mime,
316 )
317 )
318 return ParsedFeed(
319 name=name or feed_url,
320 author=author,
321 description=description,
322 artwork_url=artwork_url,
323 feed_url=feed_url,
324 episodes=episodes,
325 )
328def fetch_feed(feed_url: str) -> ParsedFeed:
329 """Fetch and parse a podcast RSS feed (blocking)."""
331 resp = httpx.get(
332 feed_url,
333 timeout=_FEED_TIMEOUT,
334 follow_redirects=True,
335 headers={
336 'User-Agent': 'Downtify/podcasts (+https://github.com/henriquesebastiao/downtify)'
337 },
338 )
339 resp.raise_for_status()
340 return parse_feed_bytes(resp.content, feed_url)
343# ── Resolving what the user pasted/typed ───────────────────────────
344def _normalize_for_match(text: str) -> str:
345 return re.sub(r'\s+', ' ', re.sub(r'[^\w\s]', '', text.casefold())).strip()
348def match_episode(
349 episodes: list[EpisodeInfo], title: str
350) -> Optional[EpisodeInfo]:
351 """Best-effort match of a Spotify episode title into a feed's episodes.
353 Titles rarely match byte-for-byte (Spotify sometimes drops a
354 numbering prefix a feed keeps, or vice versa), so this is a
355 normalized-substring match, the same tolerance
356 :mod:`downtify.itunes` uses for songs.
357 """
359 target = _normalize_for_match(title)
360 if not target:
361 return None
362 for ep in episodes:
363 candidate = _normalize_for_match(ep.title)
364 if candidate == target or target in candidate or candidate in target:
365 return ep
366 return None
369def resolve_spotify_podcast(url: str) -> tuple[ParsedFeed, Optional[str]]:
370 """Resolve a Spotify show/episode URL to its feed.
372 Returns ``(feed, matched_episode_guid)`` — the guid is set only for
373 an episode link whose title could be matched into the feed.
374 Raises :class:`PodcastFeedNotFoundError` when Spotify resolves a
375 name but iTunes has no public feed for it (the expected outcome for
376 a Spotify-exclusive show), and ``ValueError`` for anything else
377 that goes wrong reading the Spotify side.
378 """
380 parsed = parse_spotify_url(url)
381 if parsed is None or parsed[0] not in {'show', 'episode'}:
382 raise ValueError('Not a Spotify show or episode link')
383 kind, spotify_id = parsed
384 entity = fetch_embed_entity(kind, spotify_id)
385 show_name = str(entity.get('subtitle') or '').strip()
386 if not show_name:
387 raise ValueError('Could not read the show name from Spotify')
388 match = itunes.resolve_podcast_feed(show_name)
389 if match is None or not match.get('feed_url'):
390 raise PodcastFeedNotFoundError(show_name)
391 feed = fetch_feed(match['feed_url'])
392 if not feed.artwork_url and match.get('artwork_url'):
393 feed.artwork_url = itunes.artwork_url_at(match['artwork_url'], 1200)
394 matched_guid = None
395 if kind == 'episode':
396 episode_title = str(entity.get('name') or '').strip()
397 found = (
398 match_episode(feed.episodes, episode_title)
399 if episode_title
400 else None
401 )
402 matched_guid = found.guid if found else None
403 return feed, matched_guid
406def search_shows(query: str, limit: int = 10) -> list[dict[str, Any]]:
407 """iTunes podcast directory search, for the free-text search box."""
409 return [
410 {
411 'name': r.get('collectionName', ''),
412 'author': r.get('artistName', ''),
413 'feed_url': r.get('feedUrl', ''),
414 'artwork_url': r.get('artworkUrl600', ''),
415 }
416 for r in itunes.search_podcasts(query, limit=limit)
417 ]
420# ── Cover art: the largest of the feed's own image and iTunes' ─────
421def _fetch_image_bytes(url: str) -> Optional[bytes]:
422 if not url:
423 return None
424 try:
425 resp = httpx.get(url, timeout=_FEED_TIMEOUT, follow_redirects=True)
426 resp.raise_for_status()
427 return resp.content
428 except Exception:
429 logger.opt(exception=True).debug(
430 'Podcast artwork fetch failed: {}', url
431 )
432 return None
435def best_cover_bytes(
436 feed_artwork_url: str, itunes_artwork_url: str = ''
437) -> Optional[bytes]:
438 """The larger of the feed's own artwork and iTunes', by pixel size.
440 Same "largest available" idea as ``cover_sources.py`` uses for
441 music, just with two candidates instead of four — podcasts have no
442 Spotify or YouTube Music artwork to compare against.
443 """
445 candidates = []
446 for url in (
447 feed_artwork_url,
448 itunes.artwork_url_at(itunes_artwork_url, 1200)
449 if itunes_artwork_url
450 else '',
451 ):
452 if not url:
453 continue
454 data = _fetch_image_bytes(url)
455 if data:
456 candidates.append((image_short_side(data), data))
457 if not candidates:
458 return None
459 return max(candidates, key=lambda c: c[0])[1]
462# ── Tagging ──────────────────────────────────────────────────────────
463def embed_podcast_tags(
464 path: Path,
465 *,
466 title: str,
467 show_name: str,
468 author: str,
469 published_at: str,
470 description: str,
471 episode_number: Optional[int],
472 season_number: Optional[int],
473 cover_bytes: Optional[bytes],
474) -> None:
475 """Tag a downloaded episode: title, show as album, author as artist.
477 Episode/season map onto track/disc number — the same fields most
478 podcast apps and media servers already read for that purpose.
479 ``description`` goes in a comment field rather than a dedicated
480 podcast-only frame, so it round-trips through ordinary players too.
481 A container this doesn't recognize is left untagged (still a
482 perfectly playable file) rather than failing the download.
483 """
485 year = published_at[:4] if published_at[:4].isdigit() else ''
486 comment = description[:2000]
487 suffix = path.suffix.lower().lstrip('.')
488 try:
489 if suffix == 'mp3':
490 _tag_mp3_episode(
491 path,
492 title,
493 show_name,
494 author,
495 year,
496 comment,
497 episode_number,
498 season_number,
499 cover_bytes,
500 )
501 elif suffix in {'m4a', 'mp4', 'aac'}:
502 _tag_mp4_episode(
503 path,
504 title,
505 show_name,
506 author,
507 year,
508 comment,
509 episode_number,
510 season_number,
511 cover_bytes,
512 )
513 elif suffix == 'ogg':
514 _tag_vorbis_episode(
515 OggVorbis(str(path)),
516 title,
517 show_name,
518 author,
519 year,
520 comment,
521 episode_number,
522 season_number,
523 )
524 elif suffix == 'opus':
525 _tag_vorbis_episode(
526 OggOpus(str(path)),
527 title,
528 show_name,
529 author,
530 year,
531 comment,
532 episode_number,
533 season_number,
534 )
535 else:
536 logger.info('Podcast tagging: unsupported container {}', path.name)
537 except Exception:
538 logger.opt(exception=True).warning(
539 'Podcast tagging failed for {}', path
540 )
543def _tag_mp3_episode(
544 path: Path,
545 title: str,
546 album: str,
547 artist: str,
548 year: str,
549 comment: str,
550 episode: Optional[int],
551 season: Optional[int],
552 cover_bytes: Optional[bytes],
553) -> None:
554 audio = MP3(str(path), ID3=ID3)
555 if audio.tags is None:
556 audio.add_tags()
557 audio.tags.delall('APIC')
558 audio.tags.add(TIT2(encoding=3, text=title))
559 if artist:
560 audio.tags.add(TPE1(encoding=3, text=artist))
561 audio.tags.add(TPE2(encoding=3, text=artist))
562 if album:
563 audio.tags.add(TALB(encoding=3, text=album))
564 if year:
565 audio.tags.add(TDRC(encoding=3, text=year))
566 if episode is not None:
567 audio.tags.add(TRCK(encoding=3, text=str(episode)))
568 if season is not None:
569 audio.tags.add(TPOS(encoding=3, text=str(season)))
570 audio.tags.add(TCON(encoding=3, text='Podcast'))
571 if comment:
572 audio.tags.delall('COMM')
573 audio.tags.add(COMM(encoding=3, lang='eng', desc='', text=comment))
574 if cover_bytes:
575 audio.tags.add(
576 APIC(
577 encoding=3,
578 mime='image/jpeg',
579 type=3,
580 desc='Cover',
581 data=cover_bytes,
582 )
583 )
584 audio.save(v2_version=4)
587def _tag_mp4_episode(
588 path: Path,
589 title: str,
590 album: str,
591 artist: str,
592 year: str,
593 comment: str,
594 episode: Optional[int],
595 season: Optional[int],
596 cover_bytes: Optional[bytes],
597) -> None:
598 audio = MP4(str(path))
599 audio['\xa9nam'] = [title]
600 if artist:
601 audio['\xa9ART'] = [artist]
602 audio['aART'] = [artist]
603 if album:
604 audio['\xa9alb'] = [album]
605 if year:
606 audio['\xa9day'] = [year]
607 if episode is not None:
608 audio['\xa9ep'] = [str(episode)]
609 audio['trkn'] = [(episode, 0)]
610 if season is not None:
611 audio['disk'] = [(season, 0)]
612 audio['\xa9gen'] = ['Podcast']
613 audio['pcst'] = [True]
614 if comment:
615 audio['\xa9cmt'] = [comment]
616 if cover_bytes:
617 audio['covr'] = [
618 MP4Cover(cover_bytes, imageformat=MP4Cover.FORMAT_JPEG)
619 ]
620 audio.save()
623def _tag_vorbis_episode(
624 audio: Any,
625 title: str,
626 album: str,
627 artist: str,
628 year: str,
629 comment: str,
630 episode: Optional[int],
631 season: Optional[int],
632) -> None:
633 # No cover here: OggVorbis/OggOpus picture blocks need base64 METADATA_BLOCK_PICTURE
634 # handling music downloads don't need either (they already ship separate helpers
635 # in downloader.py); episodes still get every text tag, just not embedded art.
636 audio['title'] = [title]
637 if artist:
638 audio['artist'] = [artist]
639 if album:
640 audio['album'] = [album]
641 if year:
642 audio['date'] = [year]
643 if episode is not None:
644 audio['tracknumber'] = [str(episode)]
645 if season is not None:
646 audio['discnumber'] = [str(season)]
647 audio['genre'] = ['Podcast']
648 if comment:
649 audio['description'] = [comment]
650 audio.save()
653# ── Downloading an episode ──────────────────────────────────────────
654ProgressCallback = Callable[[float], None]
657def _extension_for(enclosure_type: str, enclosure_url: str) -> str:
658 ext = _AUDIO_EXT_BY_MIME.get(enclosure_type)
659 if ext:
660 return ext
661 suffix = (
662 Path(enclosure_url.split('?', maxsplit=1)[0])
663 .suffix.lower()
664 .lstrip('.')
665 )
666 return suffix if suffix and len(suffix) <= 4 else 'mp3'
669def episode_filename(episode: EpisodeInfo) -> str:
670 date_prefix = episode.published_at[:10] if episode.published_at else ''
671 ext = _extension_for(episode.enclosure_type, episode.enclosure_url)
672 base = sanitize_playlist_name(episode.title)
673 name = f'{date_prefix} - {base}' if date_prefix else base
674 return f'{name}.{ext}'
677def download_episode(
678 episode: EpisodeInfo,
679 *,
680 show_name: str,
681 author: str,
682 folder_name: str,
683 download_dir: Path,
684 cover_bytes: Optional[bytes],
685 progress: Optional[ProgressCallback] = None,
686) -> str:
687 """Download one episode's enclosure, tag it, return its library path.
689 Streamed straight to disk — episodes are already-compressed audio,
690 so unlike music there is no transcode step. Raises on a network or
691 filesystem failure; callers decide whether that fails just this
692 episode or the whole sync sweep.
693 """
695 show_dir = download_dir / PODCASTS_DIRNAME / folder_name
696 show_dir.mkdir(parents=True, exist_ok=True)
697 target = show_dir / episode_filename(episode)
699 total = 0
700 written = 0
701 with httpx.stream(
702 'GET',
703 episode.enclosure_url,
704 timeout=_DOWNLOAD_TIMEOUT,
705 follow_redirects=True,
706 ) as resp:
707 resp.raise_for_status()
708 total = int(resp.headers.get('content-length') or 0)
709 tmp = target.with_suffix(target.suffix + '.part')
710 with open(tmp, 'wb') as fh:
711 for chunk in resp.iter_bytes(_CHUNK_SIZE):
712 fh.write(chunk)
713 written += len(chunk)
714 if progress and total:
715 progress(min(99.0, written / total * 100))
716 tmp.replace(target)
718 embed_podcast_tags(
719 target,
720 title=episode.title,
721 show_name=show_name,
722 author=author,
723 published_at=episode.published_at,
724 description=episode.description,
725 episode_number=episode.episode_number,
726 season_number=episode.season_number,
727 cover_bytes=cover_bytes,
728 )
729 if progress:
730 progress(100.0)
731 return f'{PODCASTS_DIRNAME}/{folder_name}/{target.name}'
734# ── Storage ──────────────────────────────────────────────────────────
735def _show_dict(row: Any) -> dict[str, Any]:
736 keys = set(row.keys()) if hasattr(row, 'keys') else set()
737 return {
738 'id': row['id'],
739 'feed_url': row['feed_url'],
740 'name': row['name'],
741 'author': row['author'],
742 'description': row['description'],
743 'artwork_url': row['artwork_url'],
744 'source_url': row['source_url'],
745 'folder_name': row['folder_name'],
746 'retention': row['retention'],
747 'created_at': row['created_at'],
748 'user_id': int(row['user_id'] or 0) if 'user_id' in keys else 0,
749 }
752def _episode_dict(row: Any) -> dict[str, Any]:
753 return {
754 'id': row['id'],
755 'show_id': row['show_id'],
756 'guid': row['guid'],
757 'title': row['title'],
758 'description': row['description'],
759 'published_at': row['published_at'],
760 'duration_seconds': row['duration_seconds'],
761 'season_number': row['season_number'],
762 'episode_number': row['episode_number'],
763 'enclosure_url': row['enclosure_url'],
764 'enclosure_type': row['enclosure_type'],
765 'filename': row['filename'],
766 'downloaded_at': row['downloaded_at'],
767 'dismissed': bool(row['dismissed']),
768 'position_seconds': row['position_seconds'] or 0,
769 'played': bool(row['played'] or 0),
770 }
773class PodcastStore:
774 """Shows, episodes and per-episode playback position.
776 Lives in the same ``downtify_library.db`` as the other library
777 stores (``likes.py``, ``track_index.py``, ...). Scheduling — the
778 interval, enabled flag and last-checked time — is *not* kept here;
779 it lives in :class:`downtify.monitor.PlaylistMonitorDB`'s watch
780 table (kind ``"podcast"``, keyed by ``feed_url``), which already
781 does exactly that job for playlists and artists.
782 """
784 def __init__(self, path_or_db: str | Path | Database) -> None:
785 self.db = as_database(path_or_db, 'library')
786 if isinstance(path_or_db, Database):
787 self._path = str(self.db.path) if self.db.path else None
788 else:
789 self._path = str(path_or_db)
790 self._init_db()
792 @contextlib.contextmanager
793 def _connect(self) -> Iterator[Connection]:
794 with self.db.connect() as conn:
795 if conn.dialect is Dialect.SQLITE:
796 # Needed per-connection (SQLite doesn't persist it in the
797 # file); without it, deleting a show would silently orphan
798 # its episode and playback rows instead of cascading to
799 # them. PostgreSQL enforces the foreign keys natively.
800 conn.execute('PRAGMA foreign_keys = ON')
801 yield conn
803 def _init_db(self) -> None:
804 # On PostgreSQL the library_b migration already created the final
805 # schema; the DDL, ALTERs and rebuilds below are SQLite-only.
806 if self.db.dialect is not Dialect.SQLITE:
807 return
808 with self._connect() as conn:
809 conn.executescript("""
810 CREATE TABLE IF NOT EXISTS podcast_shows (
811 id INTEGER PRIMARY KEY AUTOINCREMENT,
812 feed_url TEXT NOT NULL,
813 name TEXT NOT NULL,
814 author TEXT NOT NULL DEFAULT '',
815 description TEXT NOT NULL DEFAULT '',
816 artwork_url TEXT NOT NULL DEFAULT '',
817 source_url TEXT NOT NULL DEFAULT '',
818 folder_name TEXT NOT NULL,
819 retention INTEGER NOT NULL DEFAULT 0,
820 created_at TEXT NOT NULL,
821 user_id INTEGER NOT NULL DEFAULT 0,
822 UNIQUE(feed_url, user_id)
823 );
824 CREATE TABLE IF NOT EXISTS podcast_episodes (
825 id INTEGER PRIMARY KEY AUTOINCREMENT,
826 show_id INTEGER NOT NULL,
827 guid TEXT NOT NULL,
828 title TEXT NOT NULL DEFAULT '',
829 description TEXT NOT NULL DEFAULT '',
830 published_at TEXT NOT NULL DEFAULT '',
831 duration_seconds REAL NOT NULL DEFAULT 0,
832 season_number INTEGER,
833 episode_number INTEGER,
834 enclosure_url TEXT NOT NULL DEFAULT '',
835 enclosure_type TEXT NOT NULL DEFAULT '',
836 filename TEXT,
837 downloaded_at TEXT,
838 dismissed INTEGER NOT NULL DEFAULT 0,
839 FOREIGN KEY (show_id) REFERENCES podcast_shows(id)
840 ON DELETE CASCADE,
841 UNIQUE(show_id, guid)
842 );
843 CREATE TABLE IF NOT EXISTS podcast_playback (
844 episode_id INTEGER NOT NULL,
845 user_id INTEGER NOT NULL DEFAULT 0,
846 position_seconds REAL NOT NULL DEFAULT 0,
847 played INTEGER NOT NULL DEFAULT 0,
848 updated_at TEXT NOT NULL,
849 PRIMARY KEY (episode_id, user_id),
850 FOREIGN KEY (episode_id) REFERENCES podcast_episodes(id)
851 ON DELETE CASCADE
852 );
853 """)
854 self._migrate(conn)
856 @staticmethod
857 def _migrate(conn: Any) -> None:
858 """One-time upgrades, in place, guarded by shape checks."""
860 columns = {
861 row[1] for row in conn.execute('PRAGMA table_info(podcast_shows)')
862 }
863 if 'user_id' not in columns:
864 conn.execute('PRAGMA foreign_keys = OFF')
865 try:
866 conn.execute("""
867 CREATE TABLE podcast_shows_new (
868 id INTEGER PRIMARY KEY AUTOINCREMENT,
869 feed_url TEXT NOT NULL,
870 name TEXT NOT NULL,
871 author TEXT NOT NULL DEFAULT '',
872 description TEXT NOT NULL DEFAULT '',
873 artwork_url TEXT NOT NULL DEFAULT '',
874 source_url TEXT NOT NULL DEFAULT '',
875 folder_name TEXT NOT NULL,
876 retention INTEGER NOT NULL DEFAULT 0,
877 created_at TEXT NOT NULL,
878 user_id INTEGER NOT NULL DEFAULT 0,
879 UNIQUE(feed_url, user_id)
880 )
881 """)
882 conn.execute("""
883 INSERT INTO podcast_shows_new
884 (id, feed_url, name, author, description, artwork_url,
885 source_url, folder_name, retention, created_at, user_id)
886 SELECT id, feed_url, name, author, description,
887 artwork_url, source_url, folder_name, retention,
888 created_at, 0
889 FROM podcast_shows ORDER BY id
890 """)
891 conn.execute('DROP TABLE podcast_shows')
892 conn.execute(
893 'ALTER TABLE podcast_shows_new RENAME TO podcast_shows'
894 )
895 finally:
896 conn.execute('PRAGMA foreign_keys = ON')
898 # ── shows ────────────────────────────────────────────────────
899 def add_show(
900 self,
901 feed_url: str,
902 name: str,
903 *,
904 author: str = '',
905 description: str = '',
906 artwork_url: str = '',
907 source_url: str = '',
908 retention: int = 0,
909 user_id: int = 0,
910 ) -> dict[str, Any]:
911 folder_name = sanitize_playlist_name(name)
912 with self._connect() as conn:
913 existing = {
914 r['folder_name']
915 for r in conn.execute(
916 'SELECT folder_name FROM podcast_shows'
917 ).fetchall()
918 }
919 if folder_name in existing:
920 # Two shows can share a sanitized name ("Radiolab" vs a
921 # differently-cased duplicate feed); keep folders unique
922 # rather than silently interleaving their episodes.
923 suffix = 2
924 while f'{folder_name} ({suffix})' in existing:
925 suffix += 1
926 folder_name = f'{folder_name} ({suffix})'
927 # ON CONFLICT DO NOTHING (rather than catching IntegrityError)
928 # keeps the PostgreSQL transaction usable after a duplicate.
929 cur = conn.execute(
930 """INSERT INTO podcast_shows
931 (feed_url, name, author, description, artwork_url,
932 source_url, folder_name, retention, created_at,
933 user_id)
934 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
935 ON CONFLICT DO NOTHING""",
936 (
937 feed_url,
938 name,
939 author,
940 description,
941 artwork_url,
942 source_url,
943 folder_name,
944 retention,
945 _now_iso(),
946 int(user_id or 0),
947 ),
948 )
949 if cur.rowcount == 0:
950 return self.get_show_by_feed_url(feed_url, user_id) or {}
951 row = conn.execute(
952 'SELECT * FROM podcast_shows WHERE feed_url = ? '
953 'AND user_id = ?',
954 (feed_url, int(user_id or 0)),
955 ).fetchone()
956 return _show_dict(row)
958 def get_show(self, show_id: int) -> Optional[dict[str, Any]]:
959 with self._connect() as conn:
960 row = conn.execute(
961 'SELECT * FROM podcast_shows WHERE id = ?', (show_id,)
962 ).fetchone()
963 return _show_dict(row) if row else None
965 def get_show_by_feed_url(
966 self, feed_url: str, user_id: Optional[int] = None
967 ) -> Optional[dict[str, Any]]:
968 with self._connect() as conn:
969 if user_id is None:
970 row = conn.execute(
971 'SELECT * FROM podcast_shows WHERE feed_url = ? '
972 'ORDER BY id LIMIT 1',
973 (feed_url,),
974 ).fetchone()
975 else:
976 row = conn.execute(
977 'SELECT * FROM podcast_shows WHERE feed_url = ? '
978 'AND user_id = ?',
979 (feed_url, int(user_id)),
980 ).fetchone()
981 return _show_dict(row) if row else None
983 def list_shows(
984 self, user_id: Optional[int] = None
985 ) -> list[dict[str, Any]]:
986 with self._connect() as conn:
987 if user_id is None:
988 rows = conn.execute(
989 'SELECT * FROM podcast_shows ORDER BY lower(name)'
990 ).fetchall()
991 else:
992 rows = conn.execute(
993 'SELECT * FROM podcast_shows WHERE user_id = ? '
994 'ORDER BY lower(name)',
995 (int(user_id),),
996 ).fetchall()
997 return [_show_dict(r) for r in rows]
999 def reassign_legacy(self, user_id: int) -> int:
1000 """Give pre-feature shows and progress rows to *user_id* (once)."""
1002 if not user_id:
1003 return 0
1004 with self._connect() as conn:
1005 shows = conn.execute(
1006 'UPDATE podcast_shows SET user_id = ? WHERE user_id = 0',
1007 (int(user_id),),
1008 ).rowcount
1009 progress = conn.execute(
1010 'UPDATE podcast_playback SET user_id = ? WHERE user_id = 0',
1011 (int(user_id),),
1012 ).rowcount
1013 return shows + progress
1015 def remove_user(self, user_id: int) -> None:
1016 """Drop a deleted account's shows (episodes cascade)."""
1018 with self._connect() as conn:
1019 conn.execute(
1020 'DELETE FROM podcast_shows WHERE user_id = ?',
1021 (int(user_id),),
1022 )
1024 def update_show(
1025 self, show_id: int, **fields: Any
1026 ) -> Optional[dict[str, Any]]:
1027 allowed = {
1028 'name',
1029 'author',
1030 'description',
1031 'artwork_url',
1032 'retention',
1033 }
1034 updates = {k: v for k, v in fields.items() if k in allowed}
1035 if not updates:
1036 return self.get_show(show_id)
1037 with self._connect() as conn:
1038 set_clause = ', '.join(f'{k} = ?' for k in updates)
1039 conn.execute(
1040 f'UPDATE podcast_shows SET {set_clause} WHERE id = ?',
1041 [*updates.values(), show_id],
1042 )
1043 return self.get_show(show_id)
1045 def delete_show(self, show_id: int) -> Optional[dict[str, Any]]:
1046 show = self.get_show(show_id)
1047 if show is None:
1048 return None
1049 with self._connect() as conn:
1050 conn.execute('DELETE FROM podcast_shows WHERE id = ?', (show_id,))
1051 return show
1053 # ── episodes ─────────────────────────────────────────────────
1054 def upsert_episodes(
1055 self, show_id: int, episodes: list[EpisodeInfo]
1056 ) -> list[dict[str, Any]]:
1057 """Insert episodes new to this show; leave existing rows untouched.
1059 Returns the newly-inserted rows. A guid already on file is
1060 never updated from the feed — otherwise a show correcting a
1061 typo in an old episode's title would look, from here, exactly
1062 like nothing happened, which is fine; but it also means a
1063 ``dismissed`` or already-downloaded row can never be silently
1064 resurrected by a later fetch.
1065 """
1067 inserted: list[dict[str, Any]] = []
1068 with self._connect() as conn:
1069 known = {
1070 r['guid']
1071 for r in conn.execute(
1072 'SELECT guid FROM podcast_episodes WHERE show_id = ?',
1073 (show_id,),
1074 ).fetchall()
1075 }
1076 for ep in episodes:
1077 if ep.guid in known:
1078 continue
1079 new_id = insert_returning_id(
1080 conn,
1081 """INSERT INTO podcast_episodes
1082 (show_id, guid, title, description, published_at,
1083 duration_seconds, season_number, episode_number,
1084 enclosure_url, enclosure_type)
1085 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
1086 (
1087 show_id,
1088 ep.guid,
1089 ep.title,
1090 ep.description,
1091 ep.published_at,
1092 ep.duration_seconds,
1093 ep.season_number,
1094 ep.episode_number,
1095 ep.enclosure_url,
1096 ep.enclosure_type,
1097 ),
1098 )
1099 row = conn.execute(
1100 """SELECT e.*, p.position_seconds, p.played
1101 FROM podcast_episodes e
1102 LEFT JOIN podcast_playback p ON p.episode_id = e.id
1103 WHERE e.id = ?""",
1104 (new_id,),
1105 ).fetchone()
1106 inserted.append(_episode_dict(row))
1107 known.add(ep.guid)
1108 return inserted
1110 def list_episodes(
1111 self, show_id: int, *, include_dismissed: bool = True, user_id: int = 0
1112 ) -> list[dict[str, Any]]:
1113 query = """
1114 SELECT e.*, p.position_seconds, p.played
1115 FROM podcast_episodes e
1116 LEFT JOIN podcast_playback p ON p.episode_id = e.id
1117 AND p.user_id = ?
1118 WHERE e.show_id = ?
1119 """
1120 if not include_dismissed:
1121 query += ' AND e.dismissed = 0'
1122 query += ' ORDER BY e.published_at DESC, e.id DESC'
1123 with self._connect() as conn:
1124 rows = conn.execute(query, (int(user_id or 0), show_id)).fetchall()
1125 return [_episode_dict(r) for r in rows]
1127 def get_episode(
1128 self, episode_id: int, user_id: int = 0
1129 ) -> Optional[dict[str, Any]]:
1130 with self._connect() as conn:
1131 row = conn.execute(
1132 """SELECT e.*, p.position_seconds, p.played
1133 FROM podcast_episodes e
1134 LEFT JOIN podcast_playback p ON p.episode_id = e.id
1135 AND p.user_id = ?
1136 WHERE e.id = ?""",
1137 (int(user_id or 0), episode_id),
1138 ).fetchone()
1139 return _episode_dict(row) if row else None
1141 def mark_downloaded(self, episode_id: int, filename: str) -> None:
1142 with self._connect() as conn:
1143 conn.execute(
1144 """UPDATE podcast_episodes
1145 SET filename = ?, downloaded_at = ?, dismissed = 0
1146 WHERE id = ?""",
1147 (filename, _now_iso(), episode_id),
1148 )
1150 def prune_download(self, episode_id: int, *, dismissed: bool) -> None:
1151 """Forget an episode's downloaded file.
1153 ``dismissed=True`` is a deliberate user delete: never
1154 auto-download it again. ``dismissed=False`` is an automatic
1155 retention prune: eligible to come back if retention is raised.
1156 """
1158 with self._connect() as conn:
1159 conn.execute(
1160 """UPDATE podcast_episodes
1161 SET filename = NULL, downloaded_at = NULL, dismissed = ?
1162 WHERE id = ?""",
1163 (1 if dismissed else 0, episode_id),
1164 )
1166 def set_playback(
1167 self,
1168 episode_id: int,
1169 *,
1170 position_seconds: Optional[float] = None,
1171 played: Optional[bool] = None,
1172 user_id: int = 0,
1173 ) -> None:
1174 uid = int(user_id or 0)
1175 with self._connect() as conn:
1176 row = conn.execute(
1177 'SELECT * FROM podcast_playback WHERE episode_id = ? '
1178 'AND user_id = ?',
1179 (episode_id, uid),
1180 ).fetchone()
1181 pos = row['position_seconds'] if row else 0.0
1182 was_played = bool(row['played']) if row else False
1183 if position_seconds is not None:
1184 pos = max(0.0, position_seconds)
1185 if played is not None:
1186 was_played = played
1187 conn.execute(
1188 """INSERT INTO podcast_playback
1189 (episode_id, user_id, position_seconds, played,
1190 updated_at)
1191 VALUES (?, ?, ?, ?, ?)
1192 ON CONFLICT(episode_id, user_id) DO UPDATE SET
1193 position_seconds = excluded.position_seconds,
1194 played = excluded.played,
1195 updated_at = excluded.updated_at""",
1196 (episode_id, uid, pos, int(was_played), _now_iso()),
1197 )
1199 def downloaded_episodes(self, show_id: int) -> list[dict[str, Any]]:
1200 """Downloaded, non-dismissed episodes, newest first."""
1202 return [
1203 e
1204 for e in self.list_episodes(show_id)
1205 if e['filename'] and not e['dismissed']
1206 ]
1209# ── Sync: fetch a feed, download what the retention policy wants ──
1210def episode_plan(
1211 store: PodcastStore,
1212 show: dict[str, Any],
1213 new_episodes: list[dict[str, Any]],
1214) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
1215 """``(to_download, to_prune)`` for a show, given its retention setting.
1217 Two distinct policies, matching how people actually describe this:
1219 * ``retention == 0`` — "download everything new": every episode
1220 the feed has ever published is fair game once seen, but the very
1221 first sync only grabs the single most recent one (a fresh
1222 subscribe isn't an invitation to pull a show's entire back
1223 catalog). Nothing is ever pruned.
1224 * ``retention == N`` — "keep the latest N": after this sync, the N
1225 most recently published episodes are downloaded and anything
1226 older that was downloaded is pruned — a rolling window, checked
1227 on every sync including the first.
1228 """
1230 retention = int(show['retention'] or 0)
1231 downloaded = store.downloaded_episodes(show['id'])
1232 if retention == 0:
1233 if downloaded or not new_episodes:
1234 # Steady state: whatever showed up since the last check.
1235 return new_episodes, []
1236 # First sync ever: just the newest episode.
1237 newest = max(new_episodes, key=lambda e: e['published_at'] or '')
1238 return [newest], []
1240 all_known = store.list_episodes(show['id'], include_dismissed=False)
1241 by_recency = sorted(
1242 all_known, key=lambda e: e['published_at'] or '', reverse=True
1243 )
1244 keep = by_recency[:retention]
1245 keep_ids = {e['id'] for e in keep}
1246 to_download = [e for e in keep if not e['filename']]
1247 to_prune = [e for e in downloaded if e['id'] not in keep_ids]
1248 return to_download, to_prune
1251def sync_show(
1252 store: PodcastStore,
1253 show: dict[str, Any],
1254 download_dir: Path,
1255 *,
1256 progress: Optional[Callable[[dict[str, Any]], None]] = None,
1257 should_continue: Optional[Callable[[], bool]] = None,
1258) -> int:
1259 """Fetch a show's feed and bring its downloads in line with retention.
1261 Returns the number of episodes downloaded. Safe to call for the
1262 first-ever sync (right after subscribing) and every scheduled one
1263 after — the only difference is what :func:`episode_plan` decides to
1264 do, not this function's own logic.
1265 """
1267 if should_continue is not None and not should_continue():
1268 return 0
1269 feed = fetch_feed(show['feed_url'])
1270 inserted = store.upsert_episodes(show['id'], feed.episodes)
1271 metadata_updates = {}
1272 if feed.description and feed.description != show['description']:
1273 metadata_updates['description'] = feed.description
1274 if feed.author and feed.author != show['author']:
1275 metadata_updates['author'] = feed.author
1276 if feed.artwork_url and feed.artwork_url != show['artwork_url']:
1277 metadata_updates['artwork_url'] = feed.artwork_url
1278 if metadata_updates:
1279 show = store.update_show(show['id'], **metadata_updates) or show
1281 if should_continue is not None and not should_continue():
1282 return 0
1283 to_download, to_prune = episode_plan(store, show, inserted)
1284 for ep in to_prune:
1285 full = download_dir / ep['filename']
1286 try:
1287 full.unlink(missing_ok=True)
1288 except OSError:
1289 logger.opt(exception=True).warning(
1290 'Could not remove pruned episode {}', full
1291 )
1292 store.prune_download(ep['id'], dismissed=False)
1294 if not to_download:
1295 return 0
1297 cover_bytes = best_cover_bytes(show['artwork_url'])
1298 downloaded = 0
1299 for ep_row in to_download:
1300 if should_continue is not None and not should_continue():
1301 break
1302 info = EpisodeInfo(
1303 guid=ep_row['guid'],
1304 title=ep_row['title'],
1305 description=ep_row['description'],
1306 published_at=ep_row['published_at'],
1307 duration_seconds=ep_row['duration_seconds'],
1308 season_number=ep_row['season_number'],
1309 episode_number=ep_row['episode_number'],
1310 enclosure_url=ep_row['enclosure_url'],
1311 enclosure_type=ep_row['enclosure_type'],
1312 )
1314 def _report(pct: float, _ep=ep_row) -> None:
1315 if progress:
1316 progress({
1317 'show': show['name'],
1318 'episode': _ep['title'],
1319 'progress': pct,
1320 })
1322 try:
1323 filename = download_episode(
1324 info,
1325 show_name=show['name'],
1326 author=show['author'],
1327 folder_name=show['folder_name'],
1328 download_dir=download_dir,
1329 cover_bytes=cover_bytes,
1330 progress=_report,
1331 )
1332 store.mark_downloaded(ep_row['id'], filename)
1333 downloaded += 1
1334 except Exception:
1335 logger.exception(
1336 'Podcast episode download failed: "{}" ({})',
1337 ep_row['title'],
1338 show['name'],
1339 )
1340 return downloaded