plexdo 1.1.18__py3-none-any.whl

plexdo/commands/libraries.py

@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Library listing and whole-library export commands."""
+
+from typing import Any, Dict, List, Optional
+import argparse
+import sys
+import textwrap
+
+from plexapi.server import PlexServer
+from plexapi.video import Episode
+
+from plexdo.cache import write_cache
+from plexdo.console import output, output_format
+from plexdo.constants import LOG
+from plexdo.gallery import write_gallery_html
+from plexdo.m3u import write_m3u
+from plexdo.paths import add_prefix_argument, mapper_for
+from plexdo.photos import collect_library_items, collect_photos
+from plexdo.records import cache_row, loaded_fields, release_date, season_records, summary_row
+from plexdo.sections import resolve_section
+from plexdo.sorting import apply_sort
+from plexdo.throttle import paced
+from plexdo.titles import display_title, fetch_show, non_special_episodes
+
+
+def cmd_list_libraries(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List all Plex libraries."""
+    rows = [
+        {
+            "id": int(lib.key),
+            "type": lib.type,
+            "title": lib.title,
+        }
+        for lib in plex.library.sections()
+    ]
+    write_cache("libraries", rows)
+    output(rows, args)
+
+
+def _detailed_row(item: Any, with_seasons: bool) -> Dict[str, Any]:
+    """Every listed field for one item, plus its seasons for a show."""
+    record = loaded_fields(item)
+    record["releaseDate"] = release_date(item)
+    if with_seasons:
+        record["seasons"] = season_records(item)
+    return record
+
+
+def cmd_list_titles(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List titles in a library, with optional album filter for photo libraries.
+
+    Table output stays compact; a machine-readable format carries every field
+    the listing returned, and for a show library also nests each show's
+    episodes under a seasons object.
+    """
+    library_id = args.library_id
+    section = resolve_section(plex, library_id)
+
+    album: Optional[str] = getattr(args, "album", None)
+    if album and section.type != "photo":
+        LOG.warning("--album is only applicable to photo libraries; ignoring.")
+        album = None
+
+    if section.type == "photo":
+        items = collect_photos(section, album, args)
+    else:
+        items = list(section.all())
+
+    # The completion cache only ever needs the key and the title, whatever
+    # the caller asked to see.
+    write_cache(f"titles.{library_id}", [cache_row(item) for item in items])
+
+    if output_format(args) == "table":
+        output([summary_row(item) for item in items], args)
+        return
+
+    with_seasons = section.type == "show"
+    if with_seasons:
+        LOG.info(
+            "Collecting seasons and episodes for %d show(s); this walks the "
+            "whole library.", len(items),
+        )
+    if with_seasons:
+        rows = [_detailed_row(item, True) for item in paced(items, args, "shows")]
+    else:
+        rows = [_detailed_row(item, False) for item in items]
+    output(rows, args)
+
+
+def cmd_list_show(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List all episodes in a show, optionally exporting an M3U."""
+    rating_key = int(args.rating_key)
+    show = fetch_show(plex, rating_key)
+    episodes: List[Episode] = non_special_episodes(show)
+
+    rows = [
+        {
+            "index": i + 1,
+            "ratingKey": int(ep.ratingKey),
+            "season": ep.seasonNumber,
+            "episode": ep.index,
+            "title": display_title(ep),
+        }
+        for i, ep in enumerate(episodes)
+    ]
+    output(rows, args)
+
+    if args.m3u:
+        write_m3u(episodes, args.m3u, mapper_for(plex, args))  # type: ignore[arg-type]
+
+
+def cmd_export_titles(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Export an entire library to an M3U file."""
+    section = resolve_section(plex, args.library_id)
+
+    LOG.info(
+        "Collecting items from library '%s' (type=%s)", section.title, section.type
+    )
+    album: Optional[str] = getattr(args, "album", None)
+    if album and section.type != "photo":
+        LOG.warning("--album is only applicable to photo libraries; ignoring.")
+        album = None
+
+    items = collect_library_items(section, album, args)
+
+    if not items:
+        sys.exit(f"Library '{section.title}' contains no items.")
+
+    sorted_items = apply_sort(items, args.sort)
+    gallery_title = f"{section.title} - {album}" if album else section.title
+    LOG.info(
+        "Exporting %d item(s) sorted by '%s' to %s",
+        len(sorted_items), args.sort, args.output_path,
+    )
+    if section.type == "photo":
+        write_gallery_html(
+            sorted_items, args.output_path, gallery_title, mapper_for(plex, args)
+        )
+    else:
+        write_m3u(sorted_items, args.output_path, mapper_for(plex, args))
+        print(f"Exported {len(sorted_items)} items to: {args.output_path}")
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the library-related subparsers."""
+    sub.add_parser(
+        "list-libraries", parents=parents,
+        help="List all Plex libraries (id, type, title).",
+    )
+
+    p_lt = sub.add_parser(
+        "list-titles", parents=parents, aliases=["list-library"],
+        help="List titles in a library.",
+        description=textwrap.fill(
+            "List the titles in a library. Table output shows the rating key, "
+            "title, release date, rating, and studio. A machine-readable "
+            "format (-f json, yaml, csv, clixml) carries every field the "
+            "server returned for each item, and for a show library nests each "
+            "show's episodes under a seasons object keyed by season name.",
+            width=78,
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p_lt.add_argument(
+        "library_id", metavar="LIBRARY",
+        help="Library ID (int) or library title (str). Obtain both with list-libraries.",
+    )
+    p_lt.add_argument(
+        "--album", default=None, metavar="ALBUM",
+        help="Photo libraries only: restrict listing to a single album name.",
+    )
+
+    p_ls = sub.add_parser(
+        "list-show", parents=parents,
+        help="List all episodes in a show (skipping specials), with optional M3U export.",
+    )
+    p_ls.add_argument(
+        "rating_key", type=int,
+        help="Show ratingKey (int). Obtain with list-titles.",
+    )
+    p_ls.add_argument(
+        "--m3u", metavar="PATH",
+        help="Also export an M3U file at PATH using Plex server filesystem paths.",
+    )
+    add_prefix_argument(p_ls)
+
+    p_et = sub.add_parser(
+        "export-titles", parents=parents,
+        help="Export an entire library to an M3U file or photo gallery.",
+    )
+    p_et.add_argument(
+        "library_id", metavar="LIBRARY",
+        help="Library ID (int) or library title (str). Obtain both with list-libraries.",
+    )
+    p_et.add_argument(
+        "output_path", metavar="PATH",
+        help=(
+            "Output file path. M3U for show/movie libraries; "
+            "HTML gallery for photo libraries."
+        ),
+    )
+    p_et.add_argument(
+        "--sort", choices=["alpha", "date", "random"], default="alpha",
+        help=(
+            "Sort order: 'alpha' = alphabetical by title/show+episode (default), "
+            "'date' = by original air date (undated items last), "
+            "'random' = randomised."
+        ),
+    )
+    p_et.add_argument(
+        "--album", default=None, metavar="ALBUM",
+        help="Photo libraries only: restrict export to a single album name.",
+    )
+    add_prefix_argument(p_et)
+
+
+COMMANDS = {
+    "list-libraries": cmd_list_libraries,
+    "list-titles": cmd_list_titles,
+    # argparse reports whichever spelling was typed, so the alias needs its
+    # own entry for dispatch to find a handler.
+    "list-library": cmd_list_titles,
+    "list-show": cmd_list_show,
+    "export-titles": cmd_export_titles,
+}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/metadata.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Per-item metadata display command."""
+
+from typing import Any, Dict, List
+import argparse
+
+from plexapi.audio import Track
+from plexapi.server import PlexServer
+from plexapi.video import Episode, Movie, Show
+
+from plexdo.console import clean_text, output, output_format
+from plexdo.convert import format_duration
+from plexdo.records import file_paths
+from plexdo.titles import display_title, fetch_item
+
+
+def _base_metadata(item: Any) -> Dict[str, Any]:
+    """Return metadata fields common to all media types."""
+    return {
+        "ratingKey":     int(item.ratingKey),
+        "type":          item.type,
+        "title":         display_title(item),
+        "year":          getattr(item, "year", "") or "",
+        "contentRating": clean_text(getattr(item, "contentRating", "") or ""),
+        "rating":        getattr(item, "rating", "") or "",
+        "duration":      format_duration(getattr(item, "duration", None)),
+        "addedAt":       str(getattr(item, "addedAt", "") or ""),
+        "updatedAt":     str(getattr(item, "updatedAt", "") or ""),
+        "summary":       clean_text(getattr(item, "summary", "") or ""),
+    }
+
+
+def _episode_metadata(ep: Episode) -> Dict[str, Any]:
+    """Return metadata fields specific to Episode items."""
+    record = _base_metadata(ep)
+    record.update({
+        "show":          clean_text(ep.grandparentTitle or ""),
+        "season":        ep.seasonNumber,
+        "episode":       ep.index,
+        "airDate":       str(ep.originallyAvailableAt or ""),
+        "studio":        clean_text(getattr(ep, "studio", "") or ""),
+    })
+    return record
+
+
+def _movie_metadata(movie: Movie) -> Dict[str, Any]:
+    """Return metadata fields specific to Movie items."""
+    record = _base_metadata(movie)
+    record.update({
+        "studio":        clean_text(getattr(movie, "studio", "") or ""),
+        "airDate":       str(getattr(movie, "originallyAvailableAt", "") or ""),
+        "tagline":       clean_text(getattr(movie, "tagline", "") or ""),
+        "genres":        ", ".join(g.tag for g in getattr(movie, "genres", [])),
+        "directors":     ", ".join(d.tag for d in getattr(movie, "directors", [])),
+    })
+    return record
+
+
+def _show_metadata(show: Show) -> Dict[str, Any]:
+    """Return metadata fields specific to Show items."""
+    record = _base_metadata(show)
+    record.update({
+        "studio":        clean_text(getattr(show, "studio", "") or ""),
+        "firstAired":    str(getattr(show, "originallyAvailableAt", "") or ""),
+        "seasons":       getattr(show, "childCount", ""),
+        "episodes":      getattr(show, "leafCount", ""),
+        "genres":        ", ".join(g.tag for g in getattr(show, "genres", [])),
+        "network":       clean_text(getattr(show, "network", "") or ""),
+    })
+    return record
+
+
+def _track_metadata(track: Track) -> Dict[str, Any]:
+    """Return metadata fields specific to Track items."""
+    record = _base_metadata(track)
+    record.update({
+        "album":         clean_text(getattr(track, "parentTitle", "") or ""),
+        "artist":        clean_text(getattr(track, "grandparentTitle", "") or ""),
+        "trackNumber":   getattr(track, "index", ""),
+        "year":          getattr(track, "year", "") or "",
+    })
+    return record
+
+
+_METADATA_BUILDERS = {
+    "episode": _episode_metadata,
+    "movie":   _movie_metadata,
+    "show":    _show_metadata,
+    "track":   _track_metadata,
+}
+
+
+def _file_fields(paths: List[str]) -> Dict[str, str]:
+    """One row per file, numbered only when there is more than one."""
+    if len(paths) == 1:
+        return {"file": paths[0]}
+    return {f"file {number}": path for number, path in enumerate(paths, 1)}
+
+
+def cmd_show_metadata(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Display metadata for a single item by ratingKey."""
+    item = fetch_item(plex, args.rating_key)
+    builder = _METADATA_BUILDERS.get(item.type, _base_metadata)
+    record: Dict[str, Any] = builder(item)
+
+    # A list reads naturally in a structured format, but the key/value table
+    # wants one row per file.
+    paths = file_paths(item)
+    if output_format(args) == "table":
+        record.update(_file_fields(paths))
+    else:
+        record["files"] = paths
+
+    output(record, args)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the metadata subparser."""
+    parser = sub.add_parser(
+        "show-metadata", parents=parents,
+        help="Display metadata for a single item by ratingKey.",
+    )
+    parser.add_argument(
+        "rating_key", type=int,
+        help="Item ratingKey (int). Obtain with list-titles or list-show.",
+    )
+
+
+COMMANDS = {"show-metadata": cmd_show_metadata}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/missing.py

@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Find gaps in the episode numbering of every season of every show."""
+
+from typing import Any, Dict, List, Optional, Set, Tuple
+import argparse
+import textwrap
+
+from plexapi.server import PlexServer
+from plexapi.video import Show
+
+from plexdo.console import clean_text, output
+from plexdo.constants import LOG
+from plexdo.identify import resolve_identifier
+from plexdo.sections import resolve_sections
+from plexdo.throttle import paced
+from plexdo.titles import fetch_item
+
+
+def episode_gaps(numbers: List[int]) -> List[int]:
+    """Return the episode numbers missing from a season.
+
+    The run starts at 0 when the season has an episode 0, otherwise at 1, and
+    ends at the highest number present: a season simply stopping early is not
+    a gap, since there is no way to tell an unaired episode from a missing
+    one.
+    """
+    present = sorted({number for number in numbers if number is not None})
+    if not present:
+        return []
+    start = 0 if present[0] == 0 else 1
+    return [n for n in range(start, present[-1] + 1) if n not in present]
+
+
+def _season_row(show: Any, season: Any) -> Optional[Dict[str, Any]]:
+    """Report one season, or None when its numbering is complete."""
+    episodes = season.episodes()
+    numbers = [vars(episode).get("index") for episode in episodes]
+    missing = episode_gaps([n for n in numbers if n is not None])
+    if not missing:
+        return None
+    present = sorted(n for n in numbers if n is not None)
+    return {
+        "show": clean_text(vars(show).get("title") or ""),
+        "ratingKey": int(show.ratingKey),
+        "season": vars(season).get("index"),
+        "missing": missing,
+        "missingCount": len(missing),
+        "have": len(present),
+        "highest": present[-1] if present else 0,
+    }
+
+
+def parse_seasons(text: str) -> Set[int]:
+    """Parse "1" or "1,3,5" into a set of season numbers."""
+    numbers: Set[int] = set()
+    for part in text.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            numbers.add(int(part))
+        except ValueError:
+            raise SystemExit(
+                f"Not a season number: {part!r}. Give one number, or several "
+                "separated by commas, as in --season 1,3,5."
+            ) from None
+    if not numbers:
+        raise SystemExit("--season needs at least one season number.")
+    return numbers
+
+
+def _wanted(number: Any, chosen: Optional[Set[int]], include_specials: bool) -> bool:
+    """Whether a season should be examined.
+
+    Naming a season explicitly overrides the usual skipping of season 0:
+    asking for --season 0 can only mean the specials.
+    """
+    if chosen is not None:
+        return number in chosen
+    return include_specials or number != 0
+
+
+def _show_rows(
+    show: Any, include_specials: bool, chosen: Optional[Set[int]] = None
+) -> List[Dict[str, Any]]:
+    """Report every incomplete season of one show."""
+    rows: List[Dict[str, Any]] = []
+    for season in show.seasons():
+        if not _wanted(vars(season).get("index"), chosen, include_specials):
+            continue
+        row = _season_row(show, season)
+        if row is not None:
+            rows.append(row)
+    return rows
+
+
+def _show_sections(plex: PlexServer, library_id: Optional[str]) -> List[Any]:
+    """Every show library, or the single one named."""
+    sections = [
+        section for section in resolve_sections(plex, library_id)
+        if section.type == "show"
+    ]
+    if not sections:
+        where = f"library {library_id!r}" if library_id else "this server"
+        raise SystemExit(f"No show libraries found in {where}.")
+    return sections
+
+
+def resolve_show(plex: PlexServer, identifier: str, library_id: Optional[str]) -> Any:
+    """Find one show by ratingKey or title.
+
+    Uses the same precedence as every other identifier in plexdo: a numeric
+    value is a ratingKey, a title matches exactly before case-insensitively,
+    and an ambiguous title aborts rather than guessing.
+    """
+    roster: List[Tuple[int, str]] = []
+    for section in _show_sections(plex, library_id):
+        roster.extend(
+            (int(show.ratingKey), clean_text(vars(show).get("title") or ""))
+            for show in section.all()
+        )
+    key = resolve_identifier(roster, identifier, "show", "list-titles <library>")
+    show = fetch_item(plex, key)
+    if not isinstance(show, Show):
+        raise SystemExit(
+            f"ratingKey {key} is a {type(show).__name__.lower()}, not a show."
+        )
+    return show
+
+
+def _flatten(rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Render the missing list as text, for the table renderer."""
+    return [dict(row, missing=", ".join(str(n) for n in row["missing"]))
+            for row in rows]
+
+
+def cmd_find_missing(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Report seasons whose episode numbering has holes in it."""
+    chosen = parse_seasons(args.seasons) if args.seasons else None
+
+    if args.all_shows:
+        if args.show:
+            raise SystemExit(
+                f"Give a show or --all, not both; drop {args.show!r} to check "
+                "every show."
+            )
+        if chosen is not None:
+            raise SystemExit("--season applies to a single show, not to --all.")
+        rows = _scan_libraries(plex, args)
+    else:
+        if not args.show:
+            raise SystemExit(
+                "Name a show, by title or ratingKey, or pass --all to check "
+                "every show in every library."
+            )
+        show = resolve_show(plex, args.show, args.library_id)
+        rows = _show_rows(show, args.include_specials, chosen)
+
+    if not rows:
+        LOG.info("Every season examined is complete.")
+        print("No gaps found.")
+        return
+
+    LOG.info("%d season(s) with gaps", len(rows))
+    output(_flatten(rows) if args.format == "table" else rows, args)
+
+
+def _scan_libraries(plex: PlexServer, args: argparse.Namespace) -> List[Dict[str, Any]]:
+    """Walk every show of every selected library."""
+    rows: List[Dict[str, Any]] = []
+    for section in _show_sections(plex, args.library_id):
+        shows = section.all()
+        LOG.info("Checking %d show(s) in '%s'", len(shows), section.title)
+        for show in paced(shows, args, "shows"):
+            rows.extend(_show_rows(show, args.include_specials))
+    return rows
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the find-missing subparser."""
+    parser = sub.add_parser(
+        "find-missing", parents=parents,
+        help="Find gaps in the episode numbering of a show's seasons.",
+        description=textwrap.fill(
+            "Report the episode numbers missing between the start of a "
+            "season and its highest episode. Names one show by default; -A "
+            "checks every show. A season that simply stops early is not "
+            "reported, since an unaired episode cannot be told from a missing "
+            "one.",
+            width=78,
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "show", metavar="SHOW", nargs="?", default=None,
+        help=(
+            "Show title (str) or ratingKey (int) to check. Obtain either with "
+            "list-titles. Omit only when using -A."
+        ),
+    )
+    parser.add_argument(
+        "-l", "--library", dest="library_id", metavar="LIBRARY", default=None,
+        help=(
+            "Library ID (int) or title (str) to look in. Obtain both with "
+            "list-libraries. Narrows the search for SHOW, or the sweep for -A."
+        ),
+    )
+    parser.add_argument(
+        "-A", "--all", dest="all_shows", action="store_true", default=False,
+        help="Check every show, rather than one named show.",
+    )
+    parser.add_argument(
+        "-s", "--season", dest="seasons", metavar="SEASONS", default=None,
+        help=(
+            "Season number, or several separated by commas, as in 1,3,5. "
+            "Applies to a single show. Naming season 0 includes the specials."
+        ),
+    )
+    parser.add_argument(
+        "--include-specials", action="store_true", default=False,
+        help=(
+            "Also check season 0 when no season is named. Specials are "
+            "numbered irregularly, so this is off by default."
+        ),
+    )
+
+
+COMMANDS = {"find-missing": cmd_find_missing}
+
+REQUIRES_PLEX = frozenset(COMMANDS)