plextool 3.0.1__py3-none-any.whl

plextool/cli.py

@@ -0,0 +1,52 @@
+"""Command line entry point: `plextool <command> ...`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import (
+    __version__,
+    audit,
+    auth,
+    dupes,
+    playlists,
+    recent,
+    resume,
+    scan,
+    server,
+    stale,
+    status,
+    subs,
+    watched,
+)
+from .common import PlexToolError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="plextool", description="Maintenance helpers for a Plex Media Server.",
+        epilog="Run 'plextool COMMAND --help' for a command's options and examples.\n"
+               "Run 'plextool auth login' once to sign in, then 'plextool server find' if the server isn't on localhost.\n"
+               "Anything that changes your server is a dry run unless you pass --commit.",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", metavar="command")
+    for module in (auth, server, status, scan, recent, dupes, stale, audit, watched, resume, playlists, subs):
+        module.add_parser(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    try:
+        return args.run(args)
+    except PlexToolError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130

plextool/common.py

@@ -0,0 +1,274 @@
+"""Helpers shared by the plextool commands: connection, output styling, naming."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shlex
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+from typing import TextIO
+
+from plexapi.exceptions import NotFound, Unauthorized
+from plexapi.server import PlexServer
+from requests.exceptions import RequestException
+
+DEFAULT_URL = "http://localhost:32400"
+TOKEN_ENV = "PLEX_TOKEN"
+TOKEN_CMD_ENV = "PLEX_TOKEN_CMD"
+SIGN_IN_AGAIN = ("It may have been revoked or have expired. "
+                 "Sign in again with 'plextool auth login'.")
+URL_ENV = "PLEX_URL"
+
+# Which item types ('libtype') each kind of library section can be worked at.
+SECTION_LEVELS = {
+    "movie": ("movie",),
+    "show": ("show", "season", "episode"),
+}
+
+
+# The item type that carries the media files in each kind of library.
+FILE_LEVEL = {"movie": "movie", "show": "episode"}
+
+
+class PlexToolError(Exception):
+    """A problem to report to the user without a traceback."""
+
+
+# ---------------------------------------------------------------------------
+# Output styling
+# ---------------------------------------------------------------------------
+
+_CODES = {
+    "bold": "1",
+    "red": "91",
+    "yellow": "93",
+    "green": "92",
+    "cyan": "96",
+}
+
+
+def _color_enabled(stream=None) -> bool:
+    stream = stream or sys.stdout
+    return stream.isatty() and "NO_COLOR" not in os.environ
+
+
+def paint(text: str, *styles: str, stream=None) -> str:
+    """Wrap text in ANSI styles, but only when writing to a colour-capable terminal."""
+    if not styles or not _color_enabled(stream):
+        return text
+    codes = ";".join(_CODES[s] for s in styles)
+    return f"\033[{codes}m{text}\033[0m"
+
+
+def pretty_size(num_bytes: int | None) -> str:
+    """Format a byte count for humans, eg 1536 -> '1.5 KB'."""
+    size = float(num_bytes or 0)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024:
+            return f"{int(size)} B" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+
+def plural(count: int, word: str) -> str:
+    return f"{count} {word}{'' if count == 1 else 's'}"
+
+
+# ---------------------------------------------------------------------------
+# Describing items
+# ---------------------------------------------------------------------------
+
+def _num(value) -> int:
+    return value if isinstance(value, int) else 0
+
+
+def describe(item) -> str:
+    """One-line human name for a movie, show, season or episode."""
+    kind = getattr(item, "type", None)
+    if kind == "season":
+        return f"{item.parentTitle} S{_num(item.index):02d}"
+    if kind == "episode":
+        return (f"{item.grandparentTitle} S{_num(item.seasonNumber):02d}"
+                f"E{_num(item.episodeNumber):02d} - {item.title}")
+    year = getattr(item, "year", None)
+    return f"{item.title} ({year})" if year else str(item.title)
+
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+def add_command(subparsers, name: str, summary: str, description: str, examples: list[str]):
+    """Add a (sub)command whose --help shows a wrapped description and worked examples."""
+    description = "\n\n".join(textwrap.fill(p, 78) for p in description.split("\n\n"))
+    epilog = "examples:\n" + "\n".join(f"  {e}" for e in examples)
+    return subparsers.add_parser(
+        name, help=summary, description=description, epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+
+def add_token_args(parser: argparse.ArgumentParser) -> None:
+    """Add --token and --token-file."""
+    parser.add_argument(
+        "-T", "--token", dest="token", default=None,
+        help="Plex token. Visible in your shell history and process list; "
+             "prefer 'plextool auth login', --token-file or $PLEX_TOKEN")
+    parser.add_argument(
+        "--token-file", dest="token_file", metavar="FILE", default=None,
+        help="read the Plex token from FILE ('-' reads standard input)")
+
+
+def add_connection_args(parser: argparse.ArgumentParser) -> None:
+    """Add --token, --token-file and --base-url, which every command needs."""
+    add_token_args(parser)
+    parser.add_argument(
+        "-b", "--base-url", dest="base_url", default=None,
+        help=f"Plex server URL (default: ${URL_ENV}, else the server chosen with "
+             f"'plextool server use', else {DEFAULT_URL})")
+
+
+def _token_from_file(path: str) -> str:
+    try:
+        text = sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+    except OSError as e:
+        raise PlexToolError(f"Could not read the token file: {e}") from None
+    token = text.strip()
+    if not token:
+        raise PlexToolError(f"The token file {path} is empty.")
+    return token
+
+
+def _token_from_command(command: str) -> str:
+    try:
+        done = subprocess.run(shlex.split(command), check=False, capture_output=True,
+                              text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError, ValueError) as e:
+        raise PlexToolError(f"${TOKEN_CMD_ENV} failed: {e}") from None
+    token = done.stdout.strip()
+    if done.returncode != 0 or not token:
+        raise PlexToolError(f"${TOKEN_CMD_ENV} gave no token (exit status {done.returncode}).")
+    return token
+
+
+def resolve_token(args: argparse.Namespace) -> tuple[str, str]:
+    """Find the Plex token to use, as (token, where it came from).
+
+    Order: --token, --token-file, $PLEX_TOKEN, the output of $PLEX_TOKEN_CMD, then the
+    login saved by 'plextool auth login'.
+    """
+    if args.token:
+        print("warning: --token leaves the token in your shell history and process list. "
+              f"Use 'plextool auth login', --token-file or ${TOKEN_ENV} instead.", file=sys.stderr)
+        return args.token, "--token"
+    if getattr(args, "token_file", None):
+        return _token_from_file(args.token_file), "--token-file"
+    if os.environ.get(TOKEN_ENV):
+        return os.environ[TOKEN_ENV], f"${TOKEN_ENV}"
+    if os.environ.get(TOKEN_CMD_ENV):
+        return _token_from_command(os.environ[TOKEN_CMD_ENV]), f"${TOKEN_CMD_ENV}"
+    from . import auth  # imported here because auth itself uses this module
+    token = auth.stored_token()
+    if token:
+        auth.use_saved_identity()
+        return token, "saved login"
+    raise PlexToolError("No Plex token found. Run 'plextool auth login', or use --token-file "
+                        f"or set ${TOKEN_ENV}.")
+
+
+def connect(args: argparse.Namespace) -> PlexServer:
+    """Connect to the server named in args, with friendly errors.
+
+    The server is --base-url, else $PLEX_URL, else the one saved by 'plextool server use',
+    else the default on this machine. args.base_url is set to the address that worked.
+    """
+    args.token, source = resolve_token(args)
+    url = args.base_url or os.environ.get(URL_ENV)
+    try:
+        if url:
+            plex = PlexServer(url, args.token)
+        else:
+            from . import server  # imported here because server itself uses this module
+            saved = server.load_saved()
+            plex = server.connect_saved(saved, args.token) if saved else PlexServer(DEFAULT_URL, args.token)
+    except Unauthorized:
+        hint = SIGN_IN_AGAIN if source == "saved login" else "Check that token, or use 'plextool auth login'."
+        raise PlexToolError(f"The Plex server rejected the token from {source} (401). {hint}") from None
+    except RequestException as e:
+        raise PlexToolError(f"Could not reach {url or DEFAULT_URL}: {e}") from None
+    args.base_url = plex._baseurl
+    return plex
+
+
+def write_json(path: str, data: dict) -> TextIO:
+    """Write data as JSON to a file, or to standard output if path is '-'.
+
+    Returns the stream a status message should go to: standard error when the data is
+    on standard output, so the message can't end up inside it.
+    """
+    if path == "-":
+        json.dump(data, sys.stdout, indent=2, ensure_ascii=False)
+        sys.stdout.write("\n")
+        return sys.stderr
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+    except OSError as e:
+        raise PlexToolError(f"Could not write {path}: {e}") from None
+    return sys.stdout
+
+
+def read_json(path: str) -> dict:
+    """Read JSON from a file, or from standard input if path is '-'."""
+    try:
+        if path == "-":
+            return json.load(sys.stdin)
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, ValueError) as e:
+        raise PlexToolError(f"Could not read {'standard input' if path == '-' else path}: {e}") from None
+
+
+def pick_sections(plex: PlexServer, names: list[str] | None) -> list:
+    """Return the named library sections, or every movie and TV section if none named."""
+    if names:
+        sections = []
+        for name in names:
+            try:
+                sections.append(plex.library.section(name))
+            except NotFound:
+                available = ", ".join(s.title for s in plex.library.sections())
+                raise PlexToolError(
+                    f"No library called '{name}'. Available: {available}") from None
+        unsupported = [s for s in sections if s.TYPE not in SECTION_LEVELS]
+        if unsupported:
+            raise PlexToolError(
+                f"Library '{unsupported[0].title}' is a {unsupported[0].TYPE} library; "
+                "only movie and TV libraries are supported.")
+        return sections
+    return [s for s in plex.library.sections() if s.TYPE in SECTION_LEVELS]
+
+
+def add_library_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("-l", "--library", action="append", metavar="NAME",
+                        help="library name; repeat for several (default: all movie and TV libraries)")
+
+
+def item_size(item) -> int:
+    """Total bytes of every file attached to a movie or episode, across all versions."""
+    return sum(part.size or 0 for media in item.media for part in media.parts)
+
+
+def confirm_typed(word: str, message: str, assume_yes: bool = False) -> None:
+    """Make the user type `word` before a destructive step; raise PlexToolError if they don't."""
+    if assume_yes:
+        return
+    if not sys.stdin.isatty():
+        raise PlexToolError("Refusing to continue without a terminal to confirm on. "
+                            "Pass --assume-yes to skip the prompt.")
+    answer = input(f"{message}\nType {word} to continue: ")
+    if answer.strip() != word:
+        raise PlexToolError("Not confirmed; nothing was changed.")

plextool/dupes.py

@@ -0,0 +1,190 @@
+"""dupes: list items that Plex holds more than one file/version for."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from plexapi.exceptions import BadRequest, NotFound
+
+from .common import (
+    FILE_LEVEL,
+    PlexToolError,
+    add_command,
+    add_connection_args,
+    add_library_arg,
+    confirm_typed,
+    connect,
+    describe,
+    paint,
+    pick_sections,
+    plural,
+    pretty_size,
+)
+
+
+def find_duplicates(section) -> list:
+    """Items in a section with more than one media version."""
+    level = FILE_LEVEL[section.TYPE]
+    try:
+        return section.search(libtype=level, duplicate=True)
+    except (BadRequest, NotFound):
+        # The server didn't accept the duplicate filter; check every item instead.
+        return [item for item in section.search(libtype=level) if len(item.media) > 1]
+
+
+def summarise(item) -> dict:
+    """A plain-data description of an item and each of its versions."""
+    versions = []
+    for index, media in enumerate(item.media):
+        parts = [{"file": p.file, "size": p.size or 0} for p in media.parts]
+        versions.append({
+            "index": index,
+            "resolution": media.videoResolution,
+            "codec": media.videoCodec,
+            "size": sum(p["size"] for p in parts),
+            "height": media.height or 0,
+            "parts": parts,
+        })
+    sizes = [v["size"] for v in versions]
+    return {
+        "title": describe(item),
+        "plex_id": item.guid,
+        "versions": versions,
+        # Space freed by keeping only the largest version.
+        "reclaimable": sum(sizes) - max(sizes, default=0),
+    }
+
+
+KEEP_KEYS = {
+    "largest": lambda v: v["size"],
+    "smallest": lambda v: -v["size"],
+    "best-resolution": lambda v: (v["height"], v["size"]),
+}
+
+
+def choose_deletions(entry: dict, keep: str) -> tuple[list[int], str | None]:
+    """Pick which versions of an item to delete, keeping one.
+
+    Returns (indices to delete, reason the item was skipped or None). Items with a
+    multi-part version are skipped, because deleting one part would break it.
+    """
+    versions = entry["versions"]
+    if any(len(v["parts"]) > 1 for v in versions):
+        return [], "has a multi-part version"
+    best = max(versions, key=KEEP_KEYS[keep])
+    return [v["index"] for v in versions if v is not best], None
+
+
+def print_summary(number: int, entry: dict) -> None:
+    print(f"{paint(str(number).rjust(5), 'cyan')} {paint(entry['title'], 'bold')}")
+    for version in entry["versions"]:
+        quality = " ".join(filter(None, (version["resolution"], version["codec"])))
+        label = f"  [{quality}]" if quality else ""
+        parts = version["parts"]
+        if len(parts) == 1:
+            print(f"     - [{version['index']}] {parts[0]['file']}  {pretty_size(version['size'])}{label}")
+        else:
+            print(f"     - [{version['index']}] {plural(len(parts), 'part')}, "
+                  f"{pretty_size(version['size'])} total{label}")
+            for part in parts:
+                print(f"         {part['file']}  {pretty_size(part['size'])}")
+            print(paint("         (multi-part version: these files play as one item; "
+                        "deleting one part breaks it)", "yellow"))
+
+
+def add_parser(subparsers) -> None:
+    parser = add_command(
+        subparsers, 'dupes',
+        'list items with more than one file (and optionally delete extras)',
+        'Report movies and episodes that Plex has more than one version of. Read-only unless --keep is given. Duplicates are whatever Plex has matched together, right or wrong.\n\n--keep deletes the other versions of every duplicate from disk. It is a preview unless you add --commit, and then you must type DELETE to confirm.',
+        ['plextool dupes',
+        'plextool dupes -l Movies --sort size -n 20',
+        'plextool dupes -l Movies --keep best-resolution            # preview deletions',
+        'plextool dupes -l Movies --keep best-resolution --commit   # really delete'])
+    add_connection_args(parser)
+    add_library_arg(parser)
+    parser.add_argument("-n", "--limit", type=int, metavar="N", help="show at most N items per library")
+    parser.add_argument("--sort", choices=("title", "size"), default="title",
+                        help="order by title, or by reclaimable space (largest first)")
+    parser.add_argument("--json", action="store_true", help="print JSON instead of text")
+    parser.add_argument("--keep", choices=list(KEEP_KEYS),
+                        help="DELETES the other versions of every duplicate, keeping the largest, "
+                             "smallest or highest-resolution one. Dry run unless --commit.")
+    parser.add_argument("-y", "--commit", action="store_true", help="with --keep: really delete files")
+    parser.add_argument("--assume-yes", action="store_true", help="with --commit: skip the typed confirmation")
+    parser.set_defaults(run=run)
+
+
+def delete_extras(found: list, keep: str, commit: bool, assume_yes: bool) -> int:
+    """Delete (or preview deleting) all but one version of each (item, entry) pair."""
+    plan = []
+    for item, entry in found:
+        indices, skipped = choose_deletions(entry, keep)
+        if skipped:
+            print(paint(f"  skip {entry['title']}: {skipped}", "yellow"))
+            continue
+        plan.append((item, entry, indices))
+
+    freed = 0
+    print(paint(f"\nKeeping the {keep} version of each item:", "cyan"))
+    for item, entry, indices in plan:
+        print(f"  {entry['title']}")
+        for v in entry["versions"]:
+            action = paint("DELETE", "red") if v["index"] in indices else paint("keep  ", "green")
+            print(f"    {action} {v['parts'][0]['file']}  {pretty_size(v['size'])}")
+            if v["index"] in indices:
+                freed += v["size"]
+    count = sum(len(i) for _, _, i in plan)
+    print(f"\n{plural(count, 'file')} would be deleted, freeing {pretty_size(freed)}.")
+    if not commit or not count:
+        if count:
+            print("Dry run only. Re-run with --commit to delete.")
+        return 0
+
+    confirm_typed("DELETE", f"This permanently deletes {plural(count, 'file')} from disk.", assume_yes)
+    for item, entry, indices in plan:
+        victims = [item.media[i] for i in indices]
+        for media in victims:
+            try:
+                media.delete()
+            except BadRequest:
+                raise PlexToolError(
+                    "The server refused to delete. Enable Settings > Library > "
+                    "'Allow media deletion' and try again.") from None
+            print(f"  deleted {media.parts[0].file}")
+    return 0
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.limit is not None and args.limit < 1:
+        raise PlexToolError("--limit must be at least 1")
+    if args.commit and not args.keep:
+        raise PlexToolError("--commit needs --keep")
+    plex = connect(args)
+    report = {}
+    pairs = []
+    for section in pick_sections(plex, args.library):
+        found = [(item, summarise(item)) for item in find_duplicates(section)]
+        if args.sort == "size":
+            found.sort(key=lambda p: p[1]["reclaimable"], reverse=True)
+        found = found[:args.limit] if args.limit else found
+        pairs += found
+        report[section.title] = [entry for _, entry in found]
+
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        return 0 if not args.keep else delete_extras(pairs, args.keep, args.commit, args.assume_yes)
+
+    total = reclaimable = 0
+    for title, entries in report.items():
+        print(paint(f"\n== {title}: {plural(len(entries), 'item')} with duplicates ==", "cyan"))
+        for number, entry in enumerate(entries, start=1):
+            print_summary(number, entry)
+        total += len(entries)
+        reclaimable += sum(e["reclaimable"] for e in entries)
+    print(f"\n{plural(total, 'item')} with duplicates; "
+          f"{pretty_size(reclaimable)} could be freed by keeping only the largest version of each.")
+    if args.keep:
+        return delete_extras(pairs, args.keep, args.commit, args.assume_yes)
+    return 0