plexdo 1.1.18__py3-none-any.whl

plexdo/commands/__init__.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Command registry.
+
+Every command module exposes three names:
+
+``register(sub, parents)``
+    Adds the module's subparsers to the top-level ``add_subparsers`` action.
+    Every subparser must pass ``parents=parents`` so it inherits the global
+    flags and accepts them after the command name as well as before it.
+``COMMANDS``
+    Maps each command name to its handler function.
+``REQUIRES_PLEX``
+    The subset of those names needing a connected server. Commands outside it
+    (``login``, ``write-config-example``) run before a token necessarily exists.
+
+Adding a command means adding a module here - ``cli`` needs no edit.
+"""
+
+import argparse
+from typing import Any, Callable, Dict, FrozenSet, List, Tuple
+
+from plexdo.commands import (auth, build, copy, libraries, metadata, missing,
+                             playlists, rescan, search, status, stream, users,
+                             watched)
+
+# Order determines the order subcommands appear in --help.
+MODULES = (
+    libraries,
+    missing,
+    search,
+    users,
+    playlists,
+    metadata,
+    stream,
+    rescan,
+    status,
+    build,
+    copy,
+    watched,
+    auth,
+)
+
+Handler = Callable[[Any, argparse.Namespace], None]
+
+
+def register_all(
+    sub: "argparse._SubParsersAction",  # pylint: disable=protected-access
+    parents: List[argparse.ArgumentParser],
+) -> None:
+    """Register every command module's subparsers."""
+    for module in MODULES:
+        module.register(sub, parents)
+
+
+def build_registry() -> Tuple[Dict[str, Handler], FrozenSet[str]]:
+    """Return the merged command map and the set needing a Plex connection."""
+    handlers: Dict[str, Handler] = {}
+    needs_plex: set = set()
+    for module in MODULES:
+        handlers.update(module.COMMANDS)
+        needs_plex.update(module.REQUIRES_PLEX)
+    return handlers, frozenset(needs_plex)

plexdo/commands/auth.py

@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Authentication and config bootstrap commands."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+import argparse
+import configparser
+import getpass
+import os
+import sys
+import textwrap
+
+from plexapi.exceptions import BadRequest, Unauthorized
+from plexapi.myplex import MyPlexAccount
+from plexapi.server import PlexServer
+
+from plexdo.config import config_optional, load_config
+from plexdo.console import output, output_format
+from plexdo.constants import CONFIG_EXAMPLE, CONFIG_PATH, LOG
+from plexdo.tokens import ADMIN_KEY, store_token
+
+
+def _prompt_username(supplied: Optional[str]) -> str:
+    """Return the username, prompting if it was not supplied."""
+    username = supplied or input("Plex username or email: ").strip()
+    if not username:
+        sys.exit("Username is required.")
+    return username
+
+
+def _prompt_password() -> str:
+    """Read the password without echoing it to the terminal."""
+    password = getpass.getpass("Plex password: ")
+    if not password:
+        sys.exit("Password is required.")
+    return password
+
+
+def resolve_credentials(
+    cfg: configparser.ConfigParser, args: argparse.Namespace
+) -> Tuple[str, str]:
+    """Resolve (username, password) from arguments and config.
+
+    Precedence rules:
+      * --username given: that username is used and the config password is
+        ignored entirely, because a config password paired with a different
+        username would be a silent credential mismatch.  The password comes
+        from --password, or an interactive prompt.
+      * --username absent: fall back to the config username, and to the
+        config password alongside it.  --password still overrides.
+      * Neither present: prompt for both.
+    """
+    cfg_user = config_optional(cfg, "username")
+    cfg_pass = config_optional(cfg, "password")
+
+    if args.username:
+        if cfg_pass:
+            LOG.debug("--username supplied; ignoring config password.")
+        return args.username, args.password or _prompt_password()
+
+    if cfg_user:
+        LOG.debug("Using username from config: %s", cfg_user)
+        return cfg_user, args.password or cfg_pass or _prompt_password()
+
+    return _prompt_username(None), args.password or _prompt_password()
+
+
+def _obtain_token(username: str, password: str, code: Optional[str]) -> str:
+    """Authenticate against plex.tv and return the account auth token."""
+    kwargs: Dict[str, Any] = {"username": username, "password": password}
+    if code:
+        kwargs["code"] = code
+    try:
+        account = MyPlexAccount(**kwargs)
+    except Unauthorized:
+        sys.exit(
+            "Authentication failed: bad username/password, or a two-factor "
+            "code is required (retry with --code)."
+        )
+    except BadRequest as exc:
+        sys.exit(f"Login rejected by plex.tv: {exc}")
+    return account.authenticationToken
+
+
+def _save_token(token: str, token_path_raw: str, username: Optional[str]) -> Path:
+    """Add this account's token to the JSON store, keeping any others."""
+    path = Path(token_path_raw).expanduser()
+    store_token(path, username or ADMIN_KEY, token)
+    if os.name == "nt":
+        # chmod on Windows only toggles the read-only bit, so claiming 0600
+        # would be misleading; NTFS ACLs govern access instead.
+        LOG.debug("Token written to %s (POSIX mode not applicable)", path)
+    else:
+        LOG.debug("Token written to %s (mode 0600)", path)
+    return path
+
+
+def _verify_token(url: str, token: str) -> bool:
+    """Return True if the token can connect to the configured server."""
+    try:
+        PlexServer(url, token)
+        return True
+    except Exception as exc:  # pylint: disable=broad-except
+        LOG.warning("Token saved but could not connect to %s: %s", url, exc)
+        return False
+
+
+def cmd_login(_plex: Optional[PlexServer], args: argparse.Namespace) -> None:
+    """Authenticate with plex.tv and save the token to token_path."""
+    cfg = load_config()
+    token_path_raw = cfg.get("plex", "token_path")
+    url = cfg.get("plex", "url")
+
+    username, password = resolve_credentials(cfg, args)
+    code: Optional[str] = args.code
+    if args.two_factor and not code:
+        code = input("Two-factor code: ").strip() or None
+
+    LOG.info("Authenticating %s against plex.tv", username)
+    token = _obtain_token(username, password, code)
+
+    if args.dry_run:
+        LOG.info("--dry-run: not writing token.")
+        print(f"Authenticated. Token would be written to: "
+              f"{Path(token_path_raw).expanduser()}", file=sys.stderr)
+        return
+
+    path = _save_token(token, token_path_raw, username)
+    verified = _verify_token(url, token)
+
+    if output_format(args) == "table":
+        print(f"Token saved to: {path}")
+        if verified:
+            print(f"Verified against: {url}")
+    else:
+        output({"token_path": str(path), "verified": verified}, args)
+
+
+def cmd_write_config_example(_plex: Optional[PlexServer], _args: argparse.Namespace) -> None:
+    """Write a template config file."""
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(CONFIG_EXAMPLE, encoding="utf-8")
+    if os.name != "nt":
+        CONFIG_PATH.chmod(0o600)
+    print(f"Config example written to: {CONFIG_PATH}")
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the login and config bootstrap subparsers."""
+    p_login = sub.add_parser(
+        "login", parents=parents,
+        help="Authenticate with plex.tv and save the token to token_path.",
+    )
+    p_login.add_argument(
+        "-u", "--username", default=None, metavar="USER",
+        help="Plex username or email (str). Prompted for if omitted.",
+    )
+    p_login.add_argument(
+        "-p", "--password", default=None, metavar="PASS",
+        help=(
+            "Plex password (str). INSECURE: visible in shell history and "
+            "briefly in `ps`. Prefer the config file or the interactive prompt."
+        ),
+    )
+    p_login.add_argument(
+        "-c", "--code", default=None, metavar="CODE",
+        help="Two-factor authentication code (str), if the account requires one.",
+    )
+    p_login.add_argument(
+        "-2", "--two-factor", dest="two_factor", action="store_true", default=False,
+        help="Prompt for a two-factor code interactively.",
+    )
+
+    sub.add_parser(
+        "write-config-example", parents=parents,
+        help="Write a template config file.",
+        description=textwrap.fill(
+            f"Write a template config file to {CONFIG_PATH} with mode 0600, "
+            "creating parent directories as needed. An existing file at that "
+            "path will be overwritten.",
+            width=78,
+        ),
+        epilog=(
+            "template that would be written:\n\n"
+            + textwrap.indent(CONFIG_EXAMPLE, "  ")
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+
+COMMANDS = {
+    "login": cmd_login,
+    "write-config-example": cmd_write_config_example,
+}
+
+# login and write-config-example both run before a token necessarily exists.
+REQUIRES_PLEX: frozenset = frozenset()

plexdo/commands/build.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Playlist building commands."""
+
+from typing import Iterator, List, Optional, Tuple
+import argparse
+import datetime
+import sys
+
+from plexapi.playlist import Playlist
+from plexapi.server import PlexServer
+from plexapi.video import Episode, Movie, Show
+
+from plexdo.accounts import server_for_user
+from plexdo.airdates import episodes_in_same_season, prompt_for_date, resolve_episode_date
+from plexdo.constants import LOG, MediaItem
+from plexdo.convert import parse_date
+from plexdo.m3u import write_m3u
+from plexdo.paths import add_prefix_argument, mapper_for
+from plexdo.playlists import finalize_playlist, resolve_playlist
+from plexdo.titles import fetch_show, non_special_episodes, shuffle_list
+
+
+def _round_robin(episode_lists: List[List[Episode]]) -> Iterator[Episode]:
+    """Yield episodes in round-robin order across multiple lists."""
+    queues = [list(eps) for eps in episode_lists if eps]
+    while queues:
+        exhausted = []
+        for queue in queues:
+            if queue:
+                yield queue.pop(0)
+            if not queue:
+                exhausted.append(queue)
+        for q in exhausted:
+            queues.remove(q)
+
+
+def cmd_build_interleaved(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Build a round-robin interleaved playlist from multiple shows."""
+    rating_keys = [int(k) for k in args.rating_keys]
+    episode_lists: List[List[Episode]] = []
+
+    for rk in rating_keys:
+        show = fetch_show(plex, rk)
+        eps = non_special_episodes(show)
+        LOG.info("Show '%s': %d episodes", show.title, len(eps))
+        episode_lists.append(eps)
+
+    items: List[MediaItem] = list(_round_robin(episode_lists))
+    finalize_playlist(plex, args.name, items, args)
+
+    if args.m3u:
+        write_m3u(items, args.m3u, mapper_for(plex, args))
+
+
+def _chronological_sort_key(
+    item_date: Tuple[MediaItem, datetime.datetime]
+) -> datetime.datetime:
+    return item_date[1]
+
+
+def _build_chronological_items(
+    plex: PlexServer,
+    rating_keys: List[int],
+) -> List[Tuple[MediaItem, datetime.datetime]]:
+    """Build (item, resolved_datetime) pairs for all given shows/movies."""
+    dated_items: List[Tuple[MediaItem, datetime.datetime]] = []
+    last_used_date: Optional[datetime.datetime] = None
+
+    for rk in rating_keys:
+        media_item = plex.fetchItem(rk)
+        LOG.debug("Processing ratingKey=%d type=%s", rk, type(media_item).__name__)
+
+        if isinstance(media_item, Show):
+            all_eps = non_special_episodes(media_item)
+            for ep in all_eps:
+                season_peers = episodes_in_same_season(ep, all_eps)
+                resolved = resolve_episode_date(ep, season_peers, last_used_date)
+                last_used_date = resolved
+                dated_items.append((ep, resolved))
+
+        elif isinstance(media_item, Movie):
+            dt = parse_date(media_item.originallyAvailableAt)
+            if dt is None:
+                dt = prompt_for_date(media_item, last_used_date)  # type: ignore[arg-type]
+            last_used_date = dt
+            dated_items.append((media_item, dt))
+
+        else:
+            sys.exit(
+                f"ratingKey {rk} is type '{type(media_item).__name__}' "
+                "- only Show and Movie are supported."
+            )
+
+    return dated_items
+
+
+def cmd_build_chronological(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Build a date-sorted playlist from shows and/or movies."""
+    rating_keys = [int(k) for k in args.rating_keys]
+    dated_items = _build_chronological_items(plex, rating_keys)
+
+    dated_items.sort(key=_chronological_sort_key)
+    items: List[MediaItem] = [item for item, _ in dated_items]
+
+    finalize_playlist(plex, args.name, items, args)
+
+    if args.m3u:
+        write_m3u(items, args.m3u, mapper_for(plex, args))
+
+
+def cmd_build_randomize(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Randomize a playlist and save to a new destination playlist."""
+    user_plex = server_for_user(plex, args.user_id)
+    src: Playlist = resolve_playlist(user_plex, args.source)
+
+    all_items: List[MediaItem] = list(src.items())
+    randomized: List[MediaItem] = shuffle_list(all_items)
+
+    LOG.info("Randomized %d items", len(randomized))
+    finalize_playlist(user_plex, args.dest, randomized, args)
+
+    if args.m3u:
+        write_m3u(randomized, args.m3u, mapper_for(user_plex, args))
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the playlist building subparsers."""
+    p_bi = sub.add_parser(
+        "build-interleaved", parents=parents,
+        help="Round-robin interleaved playlist from multiple shows.",
+    )
+    p_bi.add_argument("name", help="Name for the new playlist (str).")
+    p_bi.add_argument(
+        "rating_keys", nargs="+", type=int, metavar="ratingKey",
+        help="One or more Show ratingKeys (int). Obtain with list-titles.",
+    )
+    p_bi.add_argument(
+        "-o", "--overwrite", action="store_true", default=False,
+        help="Replace an existing playlist of the same name instead of failing.",
+    )
+    p_bi.add_argument(
+        "--m3u", metavar="PATH",
+        help="Also export an M3U file at PATH using Plex server filesystem paths.",
+    )
+    add_prefix_argument(p_bi)
+
+    p_bc = sub.add_parser(
+        "build-chronological", parents=parents,
+        help="Date-sorted playlist from shows and/or movies.",
+    )
+    p_bc.add_argument("name", help="Name for the new playlist (str).")
+    p_bc.add_argument(
+        "rating_keys", nargs="+", type=int, metavar="ratingKey",
+        help="One or more Show/Movie ratingKeys (int). Obtain with list-titles.",
+    )
+    p_bc.add_argument(
+        "-o", "--overwrite", action="store_true", default=False,
+        help="Replace an existing playlist of the same name instead of failing.",
+    )
+    p_bc.add_argument(
+        "--m3u", metavar="PATH",
+        help="Also export an M3U file at PATH using Plex server filesystem paths.",
+    )
+    add_prefix_argument(p_bc)
+
+    p_br = sub.add_parser(
+        "build-randomize", parents=parents,
+        help="Randomize a source playlist into a new destination playlist.",
+    )
+    p_br.add_argument("user_id", metavar="USER", help="User ID (int) or user title (str); use 0 for the admin account. Obtain both with list-users.")
+    p_br.add_argument("source", help="Playlist name (str) or ratingKey (int). Obtain either with list-playlists.")
+    p_br.add_argument("dest", help="Destination playlist title (str).")
+    p_br.add_argument(
+        "-o", "--overwrite", action="store_true", default=False,
+        help="Replace an existing playlist of the same name instead of failing.",
+    )
+    p_br.add_argument(
+        "--m3u", metavar="PATH",
+        help="Also export an M3U file at PATH using Plex server filesystem paths.",
+    )
+    add_prefix_argument(p_br)
+
+
+COMMANDS = {
+    "build-interleaved": cmd_build_interleaved,
+    "build-chronological": cmd_build_chronological,
+    "build-randomize": cmd_build_randomize,
+}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/copy.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Playlist copying commands."""
+
+from typing import Any, Dict, List
+import argparse
+import sys
+
+from plexapi.myplex import MyPlexUser
+from plexapi.playlist import Playlist
+from plexapi.server import PlexServer
+
+from plexdo.accounts import UserAccessError, server_for_user
+from plexdo.console import clean_text, output, output_format, print_table, table_limit
+from plexdo.constants import LOG, MediaItem
+from plexdo.playlists import copy_playlist_to, preview_rows, resolve_playlist
+from plexdo.throttle import paced
+
+
+def _copy_to_one_user(
+    plex: PlexServer,
+    user: MyPlexUser,
+    src_items: List[MediaItem],
+    args: argparse.Namespace,
+) -> Dict[str, Any]:
+    """Copy to a single user, converting any failure into a result record."""
+    user_id = int(user.id)
+    label = f"user {user.title!r} (id={user_id})"
+    try:
+        user_plex = server_for_user(plex, user_id)
+        status, final_name, detail = copy_playlist_to(
+            src_items, user_plex, args.source_playlist, args,
+            target_label=label, preview=False,
+        )
+    except UserAccessError as exc:
+        status, final_name, detail = "skipped", "", exc.summary
+    except Exception as exc:  # pylint: disable=broad-except
+        # One user's failure must not end the run over the remaining users.
+        LOG.debug("Copy failed for %s: %s", label, exc)
+        status, final_name, detail = "failed", "", str(exc)
+    return {
+        "user": clean_text(user.title or ""),
+        "id": user_id,
+        "status": status,
+        "playlist": final_name,
+        "detail": detail,
+    }
+
+
+def _report_line(record: Dict[str, Any]) -> str:
+    """Format one per-user outcome as a single line."""
+    line = f"  {record['status']:<8} {record['user']}"
+    extra = record["detail"] or (
+        record["playlist"] if record["playlist"] else ""
+    )
+    return f"{line}  ({extra})" if extra else line
+
+
+def cmd_copy_playlist_all_users(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Copy a playlist from any user to all managed users."""
+    src_plex = server_for_user(plex, args.source_user_id)
+    src: Playlist = resolve_playlist(src_plex, args.source_playlist)
+    src_items: List[MediaItem] = list(src.items())
+    if not src_items:
+        sys.exit(f"Source playlist {src.title!r} is empty - nothing to copy.")
+
+    # The item list is identical for every user, so it is shown once here and
+    # suppressed per user; each user then costs a single line of output.
+    table_mode = output_format(args) == "table"
+    if table_mode:
+        print(f"{src.title} ({len(src_items)} items)")
+        print_table(preview_rows(src_items), table_limit(args))
+        print()
+
+    results: List[Dict[str, Any]] = []
+    for user in paced(list(plex.myPlexAccount().users()), args, "users"):
+        user_id = int(user.id)
+        if user_id == args.source_user_id:
+            record = {
+                "user": clean_text(user.title or ""), "id": user_id,
+                "status": "skipped", "playlist": "", "detail": "source user",
+            }
+        else:
+            record = _copy_to_one_user(plex, user, src_items, args)
+        results.append(record)
+        if table_mode:
+            # Printed as each user completes, so a long run shows progress.
+            print(_report_line(record))
+
+    if not table_mode:
+        output(results, args)
+
+
+def cmd_copy_playlist_to_user(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Copy a playlist from any user to a specific user."""
+    src_plex = server_for_user(plex, args.source_user_id)
+    src: Playlist = resolve_playlist(src_plex, args.source_playlist)
+
+    src_items: List[MediaItem] = list(src.items())
+    user_plex = server_for_user(plex, args.user_id)
+    status, final_name, detail = copy_playlist_to(
+        src_items, user_plex, args.dest, args,
+        target_label=f"user id={args.user_id}",
+    )
+    record = {
+        "user": str(args.user_id), "id": args.user_id,
+        "status": status, "playlist": final_name, "detail": detail,
+    }
+    if output_format(args) == "table":
+        print(_report_line(record))
+    else:
+        output(record, args)
+
+
+_SRC_UID_HELP = (
+    "Source user ID (int) or user title (str); use 0 for the admin "
+    "account. Obtain both with list-users."
+)
+_OVERWRITE_HELP = (
+    "Overwrite an existing playlist of the same name on the destination "
+    "instead of appending ' admin copy'."
+)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the playlist copying subparsers."""
+    playlist_help = (
+        "Playlist name (str) or ratingKey (int). Obtain either with "
+        "list-playlists."
+    )
+    uid_help = (
+        "User ID (int) or user title (str); use 0 for the admin account. "
+        "Obtain both with list-users."
+    )
+
+    p_all = sub.add_parser(
+        "copy-playlist-all-users", parents=parents,
+        help="Copy a playlist from any user to all managed users.",
+    )
+    p_all.add_argument("source_user_id", metavar="USER", help=_SRC_UID_HELP)
+    p_all.add_argument("source_playlist", help="Source. " + playlist_help)
+    p_all.add_argument(
+        "-o", "--overwrite", action="store_true", default=False,
+        help=_OVERWRITE_HELP,
+    )
+
+    p_one = sub.add_parser(
+        "copy-playlist-to-user", parents=parents,
+        help="Copy a playlist from any user to a specific user.",
+    )
+    p_one.add_argument("source_user_id", metavar="USER", help=_SRC_UID_HELP)
+    p_one.add_argument("source_playlist", help="Source. " + playlist_help)
+    p_one.add_argument("user_id", metavar="USER", help="Target " + uid_help)
+    p_one.add_argument("dest", help="Destination playlist title (str).")
+    p_one.add_argument(
+        "-o", "--overwrite", action="store_true", default=False,
+        help=_OVERWRITE_HELP,
+    )
+
+
+COMMANDS = {
+    "copy-playlist-all-users": cmd_copy_playlist_all_users,
+    "copy-playlist-to-user": cmd_copy_playlist_to_user,
+}
+
+REQUIRES_PLEX = frozenset(COMMANDS)