plexdo 1.1.18__py3-none-any.whl

plexdo/commands/stream.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Media streaming to stdout."""
+
+import argparse
+import os
+import sys
+import textwrap
+
+import requests
+from plexapi.server import PlexServer
+
+from plexdo.console import output_format
+from plexdo.constants import LOG
+from plexdo.titles import display_title, fetch_item
+
+
+def _stream_to_stdout(url: str, label: str) -> None:
+    """Stream a URL to binary stdout, handling a closed pipe gracefully."""
+    if sys.stdout.isatty():
+        LOG.warning(
+            "stdout is a terminal - pipe into a player, e.g.: "
+            "plexdo read <lib> <key> | mpv -"
+        )
+    LOG.info("Streaming: %s", label)
+    try:
+        with requests.get(url, stream=True, timeout=30) as resp:
+            resp.raise_for_status()
+            for chunk in resp.iter_content(chunk_size=65536):
+                sys.stdout.buffer.write(chunk)
+        sys.stdout.buffer.flush()
+    except BrokenPipeError:
+        # Downstream player exited (e.g. user quit mpv) - not an error.
+        # Point stdout at the null device so the interpreter's final flush
+        # does not print "BrokenPipeError ignored" to stderr on exit.
+        LOG.debug("Downstream closed pipe; stream ended.")
+        try:
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        except OSError:
+            pass
+    except requests.HTTPError as exc:
+        sys.exit(f"HTTP error while streaming: {exc}")
+
+
+def cmd_read(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Stream a media file to stdout by library ID and ratingKey."""
+    if output_format(args) != "table":
+        LOG.warning(
+            "Output format flags have no effect on the read command; "
+            "binary media data goes to stdout."
+        )
+
+    rating_key = int(args.rating_key)
+    item = fetch_item(plex, rating_key)
+
+    item_lib_id = int(getattr(item, "librarySectionID", 0))
+    if item_lib_id != args.library_id:
+        sys.exit(
+            f"ratingKey {rating_key} belongs to library {item_lib_id}, "
+            f"not library {args.library_id}."
+        )
+
+    if not getattr(item, "media", None):
+        sys.exit(f"No media attached to ratingKey: {rating_key}")
+
+    parts = item.media[0].parts
+    if not parts:
+        sys.exit(f"No parts found for ratingKey: {rating_key}")
+
+    if len(item.media) > 1 or len(parts) > 1:
+        LOG.warning(
+            "Multiple media/parts found; streaming first part only. "
+            "Use list-show or show-metadata to inspect."
+        )
+
+    part = parts[0]
+    label = display_title(item)
+    url = plex.url(part.key, includeToken=True)
+
+    LOG.info("File : %s", part.file or "(no server path)")
+    LOG.info("URL  : %s", url)
+
+    if args.dry_run:
+        print(f"title : {label}", file=sys.stderr)
+        print(f"file  : {part.file or '(none)'}", file=sys.stderr)
+        print(f"url   : {url}", file=sys.stderr)
+        return
+
+    _stream_to_stdout(url, label)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the read subparser."""
+    parser = sub.add_parser(
+        "read", parents=parents,
+        help=(
+            "Stream a media file to stdout. Pipe into a player: "
+            "plexdo read <lib> <key> | mpv -"
+        ),
+        description=textwrap.fill(
+            "Stream a media file to standard output, for piping into a player "
+            "or redirecting to a file. Quitting the player early is not an "
+            "error.",
+            width=78,
+        ),
+        epilog=(
+            "examples:\n"
+            "  plexdo read 3 12345 > episode.mkv\n"
+            "  plexdo read 3 12345 | mpv -\n"
+            "\n"
+            "On Linux with a display attached but no desktop environment, mpv\n"
+            "can draw straight to the console through the kernel modesetting\n"
+            "driver, so playback needs neither X nor Wayland:\n"
+            "\n"
+            "  plexdo read 3 12345 | mpv --vo=drm -\n"
+            "\n"
+            "Run it from a virtual terminal rather than a terminal emulator,\n"
+            "and make sure your user can reach the DRM device (usually via the\n"
+            "video group)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "library_id", metavar="LIBRARY",
+        help="Library ID (int) or library title (str). Obtain both with list-libraries.",
+    )
+    parser.add_argument(
+        "rating_key", type=int,
+        help="Item ratingKey (int). Obtain with list-titles or list-show.",
+    )
+
+
+COMMANDS = {"read": cmd_read}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/users.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""User listing command."""
+
+import argparse
+
+from plexapi.server import PlexServer
+
+from plexdo.accounts import account_type
+from plexdo.cache import write_cache
+from plexdo.console import output
+
+
+def cmd_list_users(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List managed/home users visible to the admin token."""
+    account = plex.myPlexAccount()
+    rows = [
+        {
+            "id": int(u.id),
+            "type": account_type(u),
+            "title": u.title,
+        }
+        for u in account.users()
+    ]
+    write_cache("users", rows)
+    output(rows, args)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the user listing subparser."""
+    sub.add_parser("list-users", parents=parents, help="List all managed/home users (id, type, title).")
+
+
+COMMANDS = {"list-users": cmd_list_users}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/watched.py

@@ -0,0 +1,295 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Watched-state synchronisation between two users."""
+
+from typing import Any, Dict, List, NamedTuple, Optional, Sequence, Tuple
+import argparse
+import datetime
+import sys
+
+from plexapi.server import PlexServer
+
+from plexdo.accounts import server_for_user
+from plexdo.console import output, output_format
+from plexdo.constants import LOG
+from plexdo.convert import parse_date
+from plexdo.sections import resolve_sections
+from plexdo.throttle import paced
+from plexdo.titles import display_title, fetch_item
+
+
+# Library type -> the leaf libtype that actually carries watch state.
+# Photo libraries have none and are skipped entirely.
+_WATCHABLE_LIBTYPES = {"movie": "movie", "show": "episode", "artist": "track"}
+
+
+# Plex rewrites viewOffset continuously during playback, so offsets within
+# this many milliseconds are treated as identical rather than as a change.
+_OFFSET_TOLERANCE_MS = 10_000
+
+
+class WatchState(NamedTuple):
+    """One item's watch progress as seen by one user."""
+
+    played: bool
+    offset: int
+    last_viewed: Optional[datetime.datetime]
+    item: Any
+
+
+class PlannedChange(NamedTuple):
+    """A single pending watch-state update."""
+
+    rating_key: int
+    title: str
+    action: str
+    target: str
+    winner: WatchState
+    loser: WatchState
+
+
+def _call_first_method(item: Any, names: Sequence[str], *args: Any) -> bool:
+    """Call the first method in names that exists; return True if one ran.
+
+    plexapi renamed these (markWatched -> markPlayed, etc.), so both
+    spellings are attempted for compatibility across library versions.
+    """
+    for name in names:
+        method = getattr(item, name, None)
+        if callable(method):
+            method(*args)
+            return True
+    LOG.debug("None of %s available on %r", list(names), type(item).__name__)
+    return False
+
+
+def _item_is_played(item: Any) -> bool:
+    """Return True if the item is marked fully played for this user."""
+    for attr in ("isPlayed", "isWatched"):
+        value = getattr(item, attr, None)
+        if isinstance(value, bool):
+            return value
+    return bool(getattr(item, "viewCount", 0))
+
+
+def _watch_state(item: Any) -> WatchState:
+    """Capture the watch state of a single item."""
+    return WatchState(
+        played=_item_is_played(item),
+        offset=int(getattr(item, "viewOffset", 0) or 0),
+        last_viewed=parse_date(getattr(item, "lastViewedAt", None)),
+        item=item,
+    )
+
+
+def _has_watch_data(state: WatchState) -> bool:
+    """Return True if the user has played or partially played the item."""
+    return state.played or state.offset > 0
+
+
+def _states_match(first: WatchState, second: WatchState) -> bool:
+    """Return True if two states are close enough to need no update."""
+    if first.played != second.played:
+        return False
+    if first.played:
+        return True
+    return abs(first.offset - second.offset) <= _OFFSET_TOLERANCE_MS
+
+
+def _viewed_sort_key(
+    state: WatchState, prefer_earliest: bool
+) -> datetime.datetime:
+    """Timestamp used to pick a winner; undated states never win."""
+    if state.last_viewed is not None:
+        return state.last_viewed
+    return datetime.datetime.max if prefer_earliest else datetime.datetime.min
+
+
+def _select_winner(
+    first: WatchState, second: WatchState, unwatch: bool
+) -> Optional[Tuple[WatchState, WatchState]]:
+    """Return (winner, loser), or None when no update is needed."""
+    first_data, second_data = _has_watch_data(first), _has_watch_data(second)
+    if not (first_data or second_data) or _states_match(first, second):
+        return None
+
+    if first_data != second_data:
+        # Exactly one side has data. The default sync propagates the watched
+        # state outward; --unwatch propagates the unwatched state instead.
+        first_wins = first_data == (not unwatch)
+        return (first, second) if first_wins else (second, first)
+
+    first_key = _viewed_sort_key(first, unwatch)
+    second_key = _viewed_sort_key(second, unwatch)
+    first_wins = (
+        first_key <= second_key if unwatch else first_key >= second_key
+    )
+    return (first, second) if first_wins else (second, first)
+
+
+def _planned_action(winner: WatchState) -> str:
+    """Return the action label needed to adopt the winner's state."""
+    if winner.played:
+        return "markPlayed"
+    if winner.offset > 0:
+        return "setProgress"
+    return "markUnplayed"
+
+
+def _apply_action(change: PlannedChange) -> None:
+    """Perform one planned watch-state change on the target user's item."""
+    item = change.loser.item
+    if change.action == "markPlayed":
+        _call_first_method(item, ("markPlayed", "markWatched"))
+        return
+    if change.loser.played:
+        _call_first_method(item, ("markUnplayed", "markUnwatched"))
+    if change.action == "setProgress":
+        _call_first_method(item, ("updateProgress",), change.winner.offset)
+
+
+def _watchable_sections(user_plex: PlexServer, library_id: Optional[int]) -> List[Any]:
+    """Return the library sections that carry watch state."""
+    sections = resolve_sections(user_plex, library_id)
+    return [s for s in sections if s.type in _WATCHABLE_LIBTYPES]
+
+
+def _collect_watch_states(
+    user_plex: PlexServer, library_id: Optional[int], rating_key: Optional[int]
+) -> Dict[int, WatchState]:
+    """Return ratingKey -> WatchState for one user, honouring the filters."""
+    states: Dict[int, WatchState] = {}
+
+    if rating_key is not None:
+        item = fetch_item(user_plex, rating_key)
+        states[int(item.ratingKey)] = _watch_state(item)
+        return states
+
+    for section in _watchable_sections(user_plex, library_id):
+        libtype = _WATCHABLE_LIBTYPES[section.type]
+        # section.all(libtype=...) hits the plain listing endpoint; the search
+        # endpoint needs a non-empty query and would silently return nothing.
+        for item in section.all(libtype=libtype):
+            states[int(item.ratingKey)] = _watch_state(item)
+    return states
+
+
+def _build_sync_plan(
+    states_a: Dict[int, WatchState],
+    states_b: Dict[int, WatchState],
+    args: argparse.Namespace,
+) -> List[PlannedChange]:
+    """Compare both users' states and return the changes required."""
+    plan: List[PlannedChange] = []
+    for rating_key in sorted(set(states_a) & set(states_b)):
+        first, second = states_a[rating_key], states_b[rating_key]
+        selected = _select_winner(first, second, args.unwatch)
+        if selected is None:
+            continue
+        winner, loser = selected
+        if args.one_way and loser is first:
+            LOG.debug("--one-way: skipping write to first user for %d", rating_key)
+            continue
+        plan.append(PlannedChange(
+            rating_key=rating_key,
+            title=display_title(loser.item),
+            action=_planned_action(winner),
+            target="a" if loser is first else "b",
+            winner=winner,
+            loser=loser,
+        ))
+    return plan
+
+
+def _plan_rows(
+    plan: List[PlannedChange], args: argparse.Namespace
+) -> List[Dict[str, Any]]:
+    """Build display rows describing the planned changes."""
+    labels = {"a": f"user {args.user_a}", "b": f"user {args.user_b}"}
+    return [
+        {
+            "ratingKey": change.rating_key,
+            "title": change.title,
+            "action": change.action,
+            "target": labels[change.target],
+        }
+        for change in plan
+    ]
+
+
+def cmd_copy_watched(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Synchronise watched state and resume points between two users."""
+    if args.user_a == args.user_b:
+        sys.exit("The two user IDs must differ.")
+
+    states_a = _collect_watch_states(
+        server_for_user(plex, args.user_a), args.library_id, args.rating_key
+    )
+    states_b = _collect_watch_states(
+        server_for_user(plex, args.user_b), args.library_id, args.rating_key
+    )
+    LOG.info(
+        "Collected %d item(s) for user %d and %d for user %d",
+        len(states_a), args.user_a, len(states_b), args.user_b,
+    )
+
+    plan = _build_sync_plan(states_a, states_b, args)
+    if not plan:
+        LOG.info("Watch state already in sync.")
+        if output_format(args) == "table":
+            print("Watch state already in sync.", file=sys.stderr)
+        else:
+            output([], args)
+        return
+
+    output(_plan_rows(plan, args), args)
+
+    if args.dry_run:
+        LOG.info("--dry-run: no watch state was changed.")
+        return
+
+    for change in paced(plan, args, "updates"):
+        _apply_action(change)
+    LOG.info("Applied %d change(s).", len(plan))
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the copy-watched subparser."""
+    uid_help = (
+        "user ID (int) or user title (str); use 0 for the admin account. "
+        "Obtain both with list-users."
+    )
+    parser = sub.add_parser(
+        "copy-watched", parents=parents,
+        help="Synchronise watched state and resume points between two users.",
+    )
+    parser.add_argument("user_a", metavar="USER", help=f"First {uid_help}")
+    parser.add_argument("user_b", metavar="USER", help=f"Second {uid_help}")
+    parser.add_argument(
+        "-1", "--one-way", dest="one_way", action="store_true", default=False,
+        help="Only write to the second user; never modify the first.",
+    )
+    parser.add_argument(
+        "-l", "--library", dest="library_id", default=None, metavar="LIBRARY",
+        help="Restrict to one library, by ID or title. Obtain both with list-libraries.",
+    )
+    parser.add_argument(
+        "-t", "--title", dest="rating_key", type=int, default=None, metavar="KEY",
+        help="Restrict to a single item ratingKey. Obtain with list-titles or search.",
+    )
+    parser.add_argument(
+        "--unwatch", action="store_true", default=False,
+        help=(
+            "Invert the sync: if either user has an item unwatched, mark it "
+            "unwatched for both; if both have progress, the earliest "
+            "lastViewedAt wins instead of the most recent."
+        ),
+    )
+
+
+COMMANDS = {"copy-watched": cmd_copy_watched}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/config.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Config file loading, token reading, and permission checks."""
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+import configparser
+import os
+import re
+import sys
+
+from plexapi.server import PlexServer
+
+from plexdo.constants import CONFIG_PATH, LOG, PERMISSIVE_MODE_MASK
+from plexdo.tokens import admin_token
+
+
+def check_file_permissions(path: Path, label: str) -> None:
+    """Warn if a secret-bearing file is readable by group or other.
+
+    Emitted at WARNING level so it surfaces without --verbose, and on stderr
+    so it can never contaminate --json output.
+    """
+    if os.name == "nt":
+        # Windows has no POSIX mode bits; os.stat synthesises 0o666, which
+        # would trip this check on every run with advice (chmod) that cannot
+        # help. Access there is governed by ACLs instead.
+        LOG.debug("Skipping POSIX permission check for %s on Windows", path)
+        return
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return
+    leaked = mode & PERMISSIVE_MODE_MASK
+    if leaked:
+        LOG.warning(
+            "SECURITY: %s at %s has mode %04o - readable by %s. "
+            "Tighten it with: chmod 600 %s",
+            label, path, mode & 0o7777,
+            "group and others" if leaked & 0o007 else "group",
+            path,
+        )
+
+
+def _expand_environment(cfg: configparser.ConfigParser) -> None:
+    """Expand environment variables in every [plex] value, in place.
+
+    os.path.expandvars follows the platform: $VAR and ${VAR} everywhere, plus
+    %VAR% on Windows. It leaves an unset variable as literal text, which would
+    surface later as a baffling "no such file" for a path like
+    "$XDG_RUNTIME_DIR/.plex.token", so an unresolved name is warned about here
+    in whichever spelling the platform accepts.
+    """
+    if not cfg.has_section("plex"):
+        return
+    for key, raw in cfg.items("plex"):
+        expanded = os.path.expandvars(raw)
+        if expanded != raw:
+            LOG.debug("Expanded environment variables in [plex] %s", key)
+        unresolved = re.findall(r"\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?", expanded)
+        if os.name == "nt":
+            unresolved += re.findall(r"%([A-Za-z_][A-Za-z0-9_]*)%", expanded)
+        for name in unresolved:
+            LOG.warning(
+                "[plex] %s references the environment variable %s, which is "
+                "not set; leaving it literal. Set it, or use an absolute path "
+                "in %s.",
+                key, name, CONFIG_PATH,
+            )
+        cfg.set("plex", key, expanded)
+
+
+def section_optional(
+    cfg: configparser.ConfigParser, section: str, key: str
+) -> Optional[str]:
+    """Return a stripped optional value from any section, or None."""
+    value = cfg.get(section, key, fallback=None)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+@lru_cache(maxsize=1)
+def cached_config() -> configparser.ConfigParser:
+    """Return the parsed config, reading the file at most once per process.
+
+    Memoised so the fallback login path can reach the per-user sections
+    without re-reading the file, and re-emitting its permission warning, once
+    per user in a loop.
+    """
+    return load_config()
+
+
+def config_optional(cfg: configparser.ConfigParser, key: str) -> Optional[str]:
+    """Return a stripped optional value from the [plex] section, or None."""
+    value = cfg.get("plex", key, fallback=None)
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+def load_config() -> configparser.ConfigParser:
+    """Load and return the INI config, failing fast if absent."""
+    if not CONFIG_PATH.exists():
+        sys.exit(
+            f"Config not found: {CONFIG_PATH}\n"
+            "Run `plexdo write-config-example` to create a template."
+        )
+    check_file_permissions(CONFIG_PATH, "config file")
+    # interpolation=None: a password containing "%" would otherwise raise
+    # InterpolationSyntaxError before it could ever be used.
+    cfg = configparser.ConfigParser(interpolation=None)
+    cfg.read(CONFIG_PATH, encoding="utf-8")
+    _expand_environment(cfg)
+    LOG.debug("Loaded config from %s", CONFIG_PATH)
+    return cfg
+
+
+def token_store_path(cfg: configparser.ConfigParser) -> Path:
+    """Return the expanded path of the JSON token store."""
+    return Path(cfg.get("plex", "token_path")).expanduser()
+
+
+def read_token(token_path_raw: str, username: Optional[str] = None) -> str:
+    """Return the admin token from the JSON token store."""
+    token_path = Path(token_path_raw).expanduser()
+    if not token_path.exists():
+        sys.exit(
+            f"Token file not found: {token_path}\n"
+            "Run `plexdo login` to authenticate and create it."
+        )
+    check_file_permissions(token_path, "token file")
+    token = admin_token(token_path, username)
+    if not token:
+        sys.exit(
+            f"No admin token in {token_path}.\n"
+            "Run `plexdo login` to authenticate, or set [plex] username to "
+            "the account whose token should be used."
+        )
+    LOG.debug("Admin token loaded from %s", token_path)
+    return token
+
+
+def connect_plex(cfg: configparser.ConfigParser) -> PlexServer:
+    """Create and return a connected PlexServer instance."""
+    url = cfg.get("plex", "url")
+    token_path = cfg.get("plex", "token_path")
+    token = read_token(token_path, config_optional(cfg, "username"))
+    LOG.info("Connecting to Plex at %s", url)
+    return PlexServer(url, token)