plexdo 1.1.18__py3-none-any.whl

plexdo/__init__.py

@@ -0,0 +1,26 @@
+# plexdo - a command-line interface for Plex Media Server.
+# Copyright (C) 2026 SidusNare
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""plexdo - a command-line interface for Plex Media Server.
+
+The public entry point is :func:`plexdo.cli.main`, exposed by the ``plexdo``
+console script.
+"""
+
+__version__ = "1.1.18"
+__all__ = ["__version__"]

plexdo/__main__.py

@@ -0,0 +1,24 @@
+# plexdo - a command-line interface for Plex Media Server.
+# Copyright (C) 2026 SidusNare
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Allow the package to be run as ``python -m plexdo``."""
+
+from plexdo.cli import main
+
+if __name__ == "__main__":
+    main()

plexdo/accounts.py

@@ -0,0 +1,253 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""User lookup, per-user servers, and account classification."""
+
+from typing import Any, List, Optional, Tuple
+import sys
+
+from plexapi.exceptions import BadRequest, NotFound, Unauthorized
+from plexapi.myplex import MyPlexAccount, MyPlexUser
+from plexapi.server import PlexServer
+
+from plexdo.config import cached_config, section_optional, token_store_path
+from plexdo.console import clean_text
+from plexdo.constants import LOG
+from plexdo.identify import resolve_identifier
+from plexdo.tokens import lookup, store_token
+
+
+class UserAccessError(RuntimeError):
+    """The server refused to act on behalf of a user.
+
+    Deliberately an ordinary Exception rather than a sys.exit: it must be
+    catchable so copy-playlist-all-users can skip one inaccessible user and
+    carry on down the list. cli.main turns it into a clean exit for the
+    single-user commands.
+
+    Carries a one-line ``summary`` alongside the full explanation, so a loop
+    over many users can report each failure in one line instead of repeating
+    three paragraphs of advice per user.
+    """
+
+    def __init__(self, message: str, summary: str) -> None:
+        super().__init__(message)
+        self.summary = summary
+
+
+def _access_denied(user_title: str, user_id: int) -> UserAccessError:
+    """Build the explanation shown when a user's token is rejected."""
+    return UserAccessError(
+        f"Access denied for user {user_title!r} (id={user_id}): the Plex "
+        f"server rejected that user's token.\n\n"
+        "Plex scopes every token to what that user can actually see, and "
+        "being the server admin does not override it. A user with no "
+        "libraries shared to them has no access to this server at all, so "
+        "there is nothing an admin token can do on their behalf.\n\n"
+        f"Share at least one library with {user_title!r} in Plex under "
+        "Settings > Users & Sharing, then try again.\n\n"
+        "If that user does have access under their own login, add their "
+        f"credentials to a [{user_id}] section of the config file and they "
+        "will be used automatically. Pass 0 to act as the admin account "
+        "itself.",
+        summary=(
+            f"access denied (401) - no libraries are shared with "
+            f"{user_title!r} on this server"
+        ),
+    )
+
+
+def _connect_with(plex: PlexServer, token: str) -> Optional[PlexServer]:
+    """Return a server connected with a token, or None if it is refused."""
+    try:
+        # pylint: disable-next=protected-access
+        return PlexServer(plex._baseurl, token)
+    except Unauthorized as exc:
+        # plexapi attaches the server's HTML error page here; keep it for
+        # --debug so it never reaches the user's terminal.
+        LOG.debug("Token rejected by server: %s", exc)
+        return None
+
+
+def _candidate_usernames(user_id: int, user: MyPlexUser) -> List[str]:
+    """Names this user's token might be filed under, most specific first."""
+    configured = section_optional(cached_config(), str(user_id), "username")
+    names = [
+        configured,
+        getattr(user, "username", None),
+        getattr(user, "email", None),
+        getattr(user, "title", None),
+    ]
+    seen: List[str] = []
+    for name in names:
+        text = clean_text(name or "")
+        if text and text not in seen:
+            seen.append(text)
+    return seen
+
+
+def _connect_as_shared_user(plex: PlexServer, user: MyPlexUser) -> Optional[PlexServer]:
+    """Stage 1: the admin-issued, server-scoped token for this user."""
+    try:
+        token = user.get_token(plex.machineIdentifier)
+    except (BadRequest, NotFound, Unauthorized) as exc:
+        LOG.debug("get_token failed for %r: %s", user.title, exc)
+        return None
+    if not token:
+        LOG.debug("get_token returned nothing for %r", user.title)
+        return None
+    return _connect_with(plex, token)
+
+
+def _connect_from_store(
+    plex: PlexServer, user: MyPlexUser, user_id: int
+) -> Optional[PlexServer]:
+    """Stage 2: a token saved previously for this user."""
+    path = token_store_path(cached_config())
+    for name in _candidate_usernames(user_id, user):
+        token = lookup(path, name)
+        if not token:
+            continue
+        server = _connect_with(plex, token)
+        if server is not None:
+            LOG.info("Using stored token for %r", name)
+            return server
+        LOG.debug("Stored token for %r was rejected; will try logging in", name)
+    return None
+
+
+def _connect_by_login(
+    plex: PlexServer, user_id: int
+) -> Optional[PlexServer]:
+    """Stage 3: log in with the credentials in the [<user_id>] section."""
+    cfg = cached_config()
+    section = str(user_id)
+    username = section_optional(cfg, section, "username")
+    password = section_optional(cfg, section, "password")
+    if not (username and password):
+        LOG.debug("No username/password in config section [%s]", section)
+        return None
+
+    LOG.info("Logging in as %r for user id %s", username, section)
+    try:
+        account = MyPlexAccount(username=username, password=password)
+    except (Unauthorized, BadRequest) as exc:
+        LOG.warning("Login failed for %r: %s", username, exc)
+        return None
+
+    token = account.authenticationToken
+    server = _connect_with(plex, token)
+    if server is None:
+        LOG.warning(
+            "%r signed in to plex.tv but that account cannot reach this "
+            "server; nothing has been shared with it.", username,
+        )
+        return None
+
+    store_token(token_store_path(cfg), username, token)
+    LOG.info("Saved a token for %r for future runs", username)
+    return server
+
+
+def server_for_user(plex: PlexServer, user_id: int) -> PlexServer:
+    """Return a PlexServer scoped to the given user.
+
+    Pass user_id=0 to use the admin account (the token from config).
+
+    Otherwise three sources are tried in turn, because a server will refuse
+    an admin-issued token for a user it has shared nothing with:
+
+    1. the server-scoped token the admin can mint via get_token()
+    2. a token already saved in the JSON token store for that user
+    3. a fresh login using the username and password in the config section
+       named for the user ID, whose token is then saved for next time
+
+    Raises UserAccessError when none of them yields access.
+    """
+    if user_id == 0:
+        LOG.debug("user_id=0: using admin account")
+        return plex
+
+    account = plex.myPlexAccount()
+    user: MyPlexUser = _find_user_by_id(account, user_id)
+
+    for stage, connect in (
+        ("admin-issued token", lambda: _connect_as_shared_user(plex, user)),
+        ("stored token", lambda: _connect_from_store(plex, user, user_id)),
+        ("configured credentials", lambda: _connect_by_login(plex, user_id)),
+    ):
+        server = connect()
+        if server is not None:
+            LOG.debug("Connected as %r via %s", user.title, stage)
+            return server
+        LOG.debug("Could not connect as %r via %s", user.title, stage)
+
+    raise _access_denied(user.title, user_id)
+
+
+def _find_user_by_id(account: MyPlexAccount, user_id: int) -> MyPlexUser:
+    """Locate a MyPlexUser by numeric id, failing fast if absent."""
+    for user in account.users():
+        if int(user.id) == user_id:
+            return user
+    sys.exit(f"User ID not found: {user_id}")
+
+
+def _is_restricted(user: MyPlexUser) -> bool:
+    """Return True if the user is a restricted (managed) account.
+
+    plexapi exposes `restricted` as the raw XML string rather than a bool,
+    so a plain truth test would treat the common "0" value as True and
+    mislabel every account as managed.
+    """
+    raw = getattr(user, "restricted", None)
+    if isinstance(raw, bool):
+        return raw
+    return str(raw or "").strip().lower() not in ("", "0", "false")
+
+
+def account_type(user: MyPlexUser) -> str:
+    """Classify a user account as managed, home, friend, or shared."""
+    if _is_restricted(user):
+        return "managed"
+    if getattr(user, "home", False):
+        return "home"
+    if getattr(user, "friend", False):
+        return "friend"
+    return "shared"
+
+
+# Namespace attributes that hold a user identifier, resolved centrally in
+# cli.main() so every command handler receives a plain numeric user ID.
+USER_ID_ARGUMENTS = ("user_id", "user_a", "user_b", "source_user_id")
+
+
+def _user_roster(plex: PlexServer) -> List[Tuple[int, str]]:
+    """Return (id, title) for the admin account and every shared user."""
+    account = plex.myPlexAccount()
+    roster = [(0, clean_text(getattr(account, "title", "") or "admin"))]
+    roster.extend(
+        (int(user.id), clean_text(user.title or ""))
+        for user in account.users()
+    )
+    return roster
+
+
+def resolve_user_identifier(roster: List[Tuple[int, str]], value: Any) -> int:
+    """Resolve a numeric user ID or a user title to a numeric user ID."""
+    return resolve_identifier(roster, value, "user", "list-users")
+
+
+def resolve_user_arguments(plex: PlexServer, args: "argparse.Namespace") -> None:
+    """Replace user ID/title arguments with numeric user IDs, in place.
+
+    The roster is fetched once per invocation, so a command taking two user
+    arguments costs a single extra API call rather than two.
+    """
+    present = [
+        name for name in USER_ID_ARGUMENTS if getattr(args, name, None) is not None
+    ]
+    if not present:
+        return
+    roster = _user_roster(plex)
+    for name in present:
+        setattr(args, name, resolve_user_identifier(roster, getattr(args, name)))

plexdo/airdates.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Air-date estimation for episodes missing originallyAvailableAt."""
+
+from typing import List, Optional, Tuple
+import datetime
+import statistics
+
+from plexapi.video import Episode
+
+from plexdo.constants import LOG
+from plexdo.convert import parse_date
+
+
+def episodes_in_same_season(ep: Episode, all_eps: List[Episode]) -> List[Episode]:
+    """Return all episodes in the same season as ep (excluding ep itself)."""
+    return [
+        e for e in all_eps
+        if e.seasonNumber == ep.seasonNumber
+        and int(e.ratingKey) != int(ep.ratingKey)
+    ]
+
+
+def _collect_neighbors(
+    ep: Episode, season_eps: List[Episode]
+) -> Tuple[List[datetime.datetime], List[datetime.datetime]]:
+    """
+    Return (prev_dates, next_dates) - up to 6 known dates on each side.
+    Episodes are ordered by episodeNumber within the season.
+    """
+    ordered = sorted(
+        (e for e in season_eps if e.index is not None),
+        key=lambda e: e.index,
+    )
+    ep_index = ep.index or 0
+    prev_dates: List[datetime.datetime] = []
+    next_dates: List[datetime.datetime] = []
+
+    for e in reversed(ordered):
+        if e.index < ep_index:
+            dt = parse_date(e.originallyAvailableAt)
+            if dt is not None:
+                prev_dates.append(dt)
+            if len(prev_dates) >= 6:
+                break
+
+    for e in ordered:
+        if e.index > ep_index:
+            dt = parse_date(e.originallyAvailableAt)
+            if dt is not None:
+                next_dates.append(dt)
+            if len(next_dates) >= 6:
+                break
+
+    return prev_dates, next_dates
+
+
+def _median_interval(dates: List[datetime.datetime]) -> Optional[datetime.timedelta]:
+    """Compute the median timedelta between adjacent sorted dates."""
+    sorted_dates = sorted(dates)
+    if len(sorted_dates) < 3:  # need >=3 dates -> >=2 intervals
+        return None
+    intervals = [
+        (sorted_dates[i + 1] - sorted_dates[i]).total_seconds()
+        for i in range(len(sorted_dates) - 1)
+    ]
+    if len(intervals) < 2:
+        return None
+    return datetime.timedelta(seconds=statistics.median(intervals))
+
+
+def _estimate_date(
+    prev_dates: List[datetime.datetime],
+    next_dates: List[datetime.datetime],
+) -> Optional[datetime.datetime]:
+    """Estimate a missing air date from neighboring known dates."""
+    all_known = prev_dates + next_dates
+    median_td = _median_interval(all_known)
+    if median_td is None:
+        return None
+
+    estimates: List[datetime.datetime] = []
+    if prev_dates:
+        latest_prev = max(prev_dates)
+        estimates.append(latest_prev + median_td)
+    if next_dates:
+        earliest_next = min(next_dates)
+        estimates.append(earliest_next - median_td)
+
+    if not estimates:
+        return None
+    if len(estimates) == 1:
+        return estimates[0]
+    avg_ts = sum(e.timestamp() for e in estimates) / len(estimates)
+    return datetime.datetime.fromtimestamp(avg_ts)
+
+
+def prompt_for_date(ep: Episode, last_used: Optional[datetime.datetime]) -> datetime.datetime:
+    """Interactively ask the user for a missing air date."""
+    example = last_used.strftime("%Y-%m-%d") if last_used else "2000-01-01"
+    prompt = (
+        f"\nCannot resolve air date for: {ep.grandparentTitle} "
+        f"S{ep.seasonNumber:02d}E{ep.index:02d} - {ep.title}\n"
+        f"Enter date (YYYY-MM-DD) [example: {example}]: "
+    )
+    while True:
+        raw = input(prompt).strip()
+        try:
+            return datetime.datetime.strptime(raw, "%Y-%m-%d")
+        except ValueError:
+            print("Invalid format, please use YYYY-MM-DD.")
+
+
+def resolve_episode_date(
+    ep: Episode,
+    season_peers: List[Episode],
+    last_used: Optional[datetime.datetime],
+) -> datetime.datetime:
+    """Return a resolved datetime for an episode, estimating or prompting if needed."""
+    dt = parse_date(ep.originallyAvailableAt)
+    if dt is not None:
+        return dt
+
+    prev_dates, next_dates = _collect_neighbors(ep, season_peers)
+    estimated = _estimate_date(prev_dates, next_dates)
+    if estimated is not None:
+        LOG.info(
+            "Estimated date for '%s' S%02dE%02d: %s",
+            ep.grandparentTitle,
+            ep.seasonNumber,
+            ep.index,
+            estimated.date(),
+        )
+        return estimated
+
+    return prompt_for_date(ep, last_used)

plexdo/cache.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Completion cache written as a side effect of list commands."""
+
+from pathlib import Path
+from typing import Any, Dict, List
+import json
+
+from plexdo.config import cached_config, config_optional
+from plexdo.constants import CONFIG_PATH, DEFAULT_CACHE_DIR, LOG
+
+
+def cache_dir() -> Path:
+    """Return the completion cache directory.
+
+    [plex] cache_dir overrides the platform default. The config is only
+    consulted when it exists, so this stays usable before `plexdo login` has
+    ever been run.
+    """
+    if CONFIG_PATH.exists():
+        configured = config_optional(cached_config(), "cache_dir")
+        if configured:
+            return Path(configured).expanduser()
+    return DEFAULT_CACHE_DIR
+
+
+def write_cache(name: str, data: List[Dict[str, Any]]) -> None:
+    """Atomically write data to the completion cache, silently ignoring errors."""
+    try:
+        directory = cache_dir()
+        directory.mkdir(parents=True, exist_ok=True)
+        cache_file = directory / f"{name}.json"
+        tmp = cache_file.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data), encoding="utf-8")
+        tmp.replace(cache_file)
+        LOG.debug("Cache updated: %s", cache_file)
+    except OSError:
+        pass

plexdo/cli.py

@@ -0,0 +1,157 @@
+# plexdo - a command-line interface for Plex Media Server.
+# Copyright (C) 2026 SidusNare
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+# more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Top-level argument parsing and command dispatch."""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from plexdo import __version__
+from plexdo.accounts import UserAccessError, resolve_user_arguments
+from plexdo.sections import resolve_library_arguments
+from plexdo.commands import build_registry, register_all
+from plexdo.formats import OUTPUT_FORMATS
+from plexdo.throttle import DEFAULT_THROTTLE, THROTTLE_THRESHOLD
+from plexdo.config import cached_config, connect_plex
+from plexdo.logs import configure_logging
+from plexdo.security import scrub_password_argument
+
+
+def _add_global_flags(
+    parser: argparse.ArgumentParser, suppress: bool = False
+) -> None:
+    """Add the flags accepted by every command.
+
+    When *suppress* is set the flags default to ``argparse.SUPPRESS`` instead
+    of ``False``. That matters for the copies inherited by each subparser: a
+    subparser parses into its own namespace and then copies every attribute
+    onto the main one, so ordinary ``False`` defaults would clobber a flag
+    that was given before the subcommand. With SUPPRESS the attribute only
+    exists when the flag was actually passed, so either position works.
+    """
+    default = argparse.SUPPRESS if suppress else False
+    parser.add_argument(
+        "-f", "--format", dest="format", choices=list(OUTPUT_FORMATS),
+        default=argparse.SUPPRESS if suppress else "table", metavar="FORMAT",
+        help=(
+            "Output format: " + ", ".join(OUTPUT_FORMATS) + ". "
+            "Default is an aligned table."
+        ),
+    )
+    # A convenience alias writing to the same destination as --format, so
+    # there is only ever one attribute for a command to consult.
+    parser.add_argument(
+        "--json", dest="format", action="store_const", const="json",
+        default=argparse.SUPPRESS, help="Shorthand for --format json.",
+    )
+    parser.add_argument(
+        "-W", "--wide", action="store_true", default=default,
+        help=(
+            "Do not shrink table columns to the terminal width. By default "
+            "the widest column is truncated so a row fits on one line; "
+            "redirected output is never truncated."
+        ),
+    )
+    parser.add_argument(
+        "--throttle", type=float, metavar="SECONDS",
+        default=argparse.SUPPRESS if suppress else DEFAULT_THROTTLE,
+        help=(
+            "Seconds to wait between requests in operations that query once "
+            f"per item, when there are more than {THROTTLE_THRESHOLD} of them "
+            f"(default: {DEFAULT_THROTTLE}). Use 0 to disable."
+        ),
+    )
+    parser.add_argument(
+        "-V", "--version", action="version",
+        version=f"plexdo {__version__}",
+        help="Show the installed version and exit.",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", default=default,
+        help="Print high-level progress to stderr.",
+    )
+    parser.add_argument(
+        "--debug", action="store_true", default=default,
+        help="Print detailed internal logs to stderr.",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", default=default, dest="dry_run",
+        help="Show what would happen without mutating Plex.",
+    )
+
+
+def _global_flags_parent() -> argparse.ArgumentParser:
+    """Return a parent parser supplying the global flags to every subcommand."""
+    parent = argparse.ArgumentParser(add_help=False)
+    _add_global_flags(parent, suppress=True)
+    return parent
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct and return the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="plexdo",
+        description=(
+            f"Interact with a Plex Media Server via plexapi.  (version {__version__})"
+        ),
+        epilog=(
+            "Global flags (-f/--format, --json, -v/--verbose, --debug, "
+            "--dry-run, -V/--version) may be given either before or after the "
+            "command name."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    _add_global_flags(parser)
+    parents: List[argparse.ArgumentParser] = [_global_flags_parent()]
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+    register_all(sub, parents)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Entry point for the ``plexdo`` console script."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    configure_logging(args.verbose, args.debug)
+    scrub_password_argument(args)
+
+    handlers, needs_plex = build_registry()
+    handler = handlers.get(args.command)
+    if handler is None:
+        sys.exit(f"Unknown command: {args.command}")
+
+    if args.command in needs_plex:
+        plex = connect_plex(cached_config())
+        # Commands receive numeric user and library IDs; titles are resolved
+        # here so no handler has to care which form the user typed.
+        resolve_user_arguments(plex, args)
+        resolve_library_arguments(plex, args)
+        try:
+            handler(plex, args)
+        except UserAccessError as exc:
+            # Raised deep in accounts.server_for_user so the all-users loop
+            # can skip a user; for a single-user command it is fatal.
+            sys.exit(str(exc))
+    else:
+        handler(None, args)