plexdo 1.1.18__py3-none-any.whl

plexdo/commands/playlists.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Playlist inspection and mutation commands."""
+
+from typing import List
+import argparse
+import sys
+
+from plexapi.exceptions import NotFound
+from plexapi.playlist import Playlist
+from plexapi.server import PlexServer
+
+from plexdo.accounts import server_for_user
+from plexdo.cache import write_cache
+from plexdo.console import output
+from plexdo.constants import LOG, MediaItem
+from plexdo.m3u import write_m3u
+from plexdo.paths import add_prefix_argument, mapper_for
+from plexdo.playlists import resolve_playlist
+from plexdo.titles import display_title
+
+
+def cmd_list_playlists(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List playlists for a given user."""
+    user_plex = server_for_user(plex, args.user_id)
+    rows = [
+        {
+            "ratingKey": int(pl.ratingKey),
+            "title": pl.title,
+            "items": pl.leafCount,
+        }
+        for pl in user_plex.playlists()
+    ]
+    write_cache(f"playlists.{args.user_id}", rows)
+    output(rows, args)
+
+
+def cmd_list_playlist(plex: PlexServer, args: argparse.Namespace) -> None:
+    """List items inside a specific playlist for a user."""
+    user_plex = server_for_user(plex, args.user_id)
+    playlist: Playlist = resolve_playlist(user_plex, args.playlist)
+
+    items: List[MediaItem] = list(playlist.items())
+    rows = [
+        {
+            "index": i + 1,
+            "ratingKey": int(item.ratingKey),
+            "title": display_title(item),
+        }
+        for i, item in enumerate(items)
+    ]
+    output(rows, args)
+
+    if args.m3u:
+        write_m3u(items, args.m3u, mapper_for(plex, args))
+
+
+def cmd_export_playlist(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Export an existing playlist to an M3U file."""
+    user_plex = server_for_user(plex, args.user_id)
+    playlist: Playlist = resolve_playlist(user_plex, args.playlist)
+
+    items: List[MediaItem] = list(playlist.items())
+    if not items:
+        sys.exit(f"Playlist '{args.playlist}' is empty - nothing to export.")
+
+    LOG.info("Exporting %d items from '%s' to %s", len(items), args.playlist, args.m3u)
+    write_m3u(items, args.m3u, mapper_for(plex, args))
+    print(f"Exported {len(items)} items to: {args.m3u}")
+
+
+def cmd_remove_playlist(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Delete a playlist from a user's account."""
+    user_plex = server_for_user(plex, args.user_id)
+    playlist: Playlist = resolve_playlist(user_plex, args.playlist)
+
+    LOG.info("Removing playlist '%s' for user_id=%d", args.playlist, args.user_id)
+    if args.dry_run:
+        LOG.info("--dry-run: skipping playlist deletion.")
+        return
+    playlist.delete()
+    print(f"Deleted playlist: {args.playlist!r}")
+
+
+def cmd_append_playlist(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Append one or more items to an existing playlist."""
+    user_plex = server_for_user(plex, args.user_id)
+    playlist: Playlist = resolve_playlist(user_plex, args.playlist)
+
+    rating_keys = [int(k) for k in args.rating_keys]
+    new_items: List[MediaItem] = []
+    for rk in rating_keys:
+        try:
+            new_items.append(user_plex.fetchItem(rk))
+        except NotFound:
+            sys.exit(f"ratingKey not found: {rk}")
+
+    if not new_items:
+        sys.exit("No items to append.")
+
+    LOG.info("Appending %d item(s) to '%s'", len(new_items), args.playlist)
+
+    preview_rows = [
+        {
+            "index": i + 1,
+            "ratingKey": int(item.ratingKey),
+            "title": display_title(item),
+        }
+        for i, item in enumerate(new_items)
+    ]
+    output(preview_rows, args)
+
+    if args.dry_run:
+        LOG.info("--dry-run: skipping append.")
+        return
+
+    playlist.addItems(new_items)
+    LOG.info("Appended %d item(s) to '%s'.", len(new_items), args.playlist)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the playlist inspection and mutation subparsers."""
+    p_lpl = sub.add_parser("list-playlists", parents=parents, help="List playlists for a user.")
+    p_lpl.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_lp = sub.add_parser("list-playlist", parents=parents, help="List items in a specific playlist.")
+    p_lp.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_lp.add_argument(
+        "playlist", type=str,
+        help="Playlist name (str) or ratingKey (int). Obtain either with list-playlists.",
+    )
+    p_lp.add_argument(
+        "--m3u", metavar="PATH",
+        help="Also export an M3U file at PATH using Plex server filesystem paths.",
+    )
+    add_prefix_argument(p_lp)
+
+    p_ep = sub.add_parser("export-playlist", parents=parents, help="Export an existing playlist to an M3U file.")
+    p_ep.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_ep.add_argument("playlist", help="To export. " + "Playlist name (str) or ratingKey (int). Obtain either with list-playlists.")
+    p_ep.add_argument(
+        "m3u", metavar="PATH",
+        help="Destination M3U file path.",
+    )
+    add_prefix_argument(p_ep)
+
+    p_rp = sub.add_parser("remove-playlist", parents=parents, help="Delete a playlist from a user's account.")
+    p_rp.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_rp.add_argument("playlist", help="To delete. " + "Playlist name (str) or ratingKey (int). Obtain either with list-playlists.")
+
+    p_ap = sub.add_parser(
+        "append-playlist", parents=parents,
+        help="Append one or more items to an existing playlist.",
+    )
+    p_ap.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_ap.add_argument("playlist", help="To append to. " + "Playlist name (str) or ratingKey (int). Obtain either with list-playlists.")
+    p_ap.add_argument(
+        "rating_keys", nargs="+", type=int, metavar="ratingKey",
+        help="One or more item ratingKeys to append (int). Obtain with list-titles or list-show.",
+    )
+
+
+COMMANDS = {
+    "list-playlists": cmd_list_playlists,
+    "list-playlist": cmd_list_playlist,
+    "export-playlist": cmd_export_playlist,
+    "remove-playlist": cmd_remove_playlist,
+    "append-playlist": cmd_append_playlist,
+}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/rescan.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Library rescan and scan-status commands."""
+
+from typing import Any, Dict, List
+import argparse
+import sys
+
+from plexapi.server import PlexServer
+
+from plexdo.console import clean_text, output
+from plexdo.constants import LOG
+from plexdo.sections import resolve_section
+
+
+def _cancel_all_scans(plex: PlexServer) -> None:
+    """Cancel any running or queued scan on every library section."""
+    for section in plex.library.sections():
+        try:
+            section.cancelUpdate()
+            LOG.debug("Cancelled scan on '%s'", section.title)
+        except Exception as exc:  # pylint: disable=broad-except
+            LOG.debug("cancelUpdate on '%s' raised %s (may already be idle)", section.title, exc)
+
+
+def _activity_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """Return scan-related activity rows from the Plex server."""
+    rows = []
+    for act in plex.activities:
+        rows.append({
+            "type":     clean_text(getattr(act, "type",     "") or ""),
+            "title":    clean_text(getattr(act, "title",    "") or ""),
+            "subtitle": clean_text(getattr(act, "subtitle", "") or ""),
+            "progress": getattr(act, "progress", ""),
+            "uuid":     clean_text(getattr(act, "uuid",     "") or ""),
+        })
+    return rows
+
+
+def cmd_rescan(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Trigger a library rescan, optionally cancelling pending scans first."""
+    if args.status:
+        rows = _activity_rows(plex)
+        if not rows:
+            print("No active scan jobs.", file=sys.stderr)
+        else:
+            output(rows, args)
+        return
+
+    if args.library_id is None:
+        sys.exit("library_id is required unless --status / -s is used.")
+
+    section = resolve_section(plex, args.library_id)
+
+    if args.now:
+        LOG.info("Cancelling all pending scans before rescan.")
+        if not args.dry_run:
+            _cancel_all_scans(plex)
+
+    LOG.info("Triggering rescan of library '%s' (id=%d)", section.title, args.library_id)
+    if args.dry_run:
+        LOG.info("--dry-run: skipping scan trigger.")
+        return
+
+    section.update()
+    print(f"Rescan triggered for library: {section.title!r}")
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the rescan subparser."""
+    parser = sub.add_parser(
+        "rescan", parents=parents,
+        help="Trigger a library rescan, with optional status view or flush-and-rescan.",
+    )
+    parser.add_argument(
+        "library_id", metavar="LIBRARY", nargs="?", default=None,
+        help="Library ID (int) or title (str). Obtain both with list-libraries. "
+        "Required unless -s / --status is used.",
+    )
+    parser.add_argument(
+        "-s", "--status", action="store_true", default=False,
+        help="Print all active scan jobs with their type, progress, and subtitle.",
+    )
+    parser.add_argument(
+        "-n", "--now", action="store_true", default=False,
+        help="Cancel all pending scans on every library before triggering the rescan.",
+    )
+
+
+COMMANDS = {"rescan": cmd_rescan}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/search.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Library search command."""
+
+from typing import Any, Dict, List, Optional
+import argparse
+
+from plexapi.server import PlexServer
+
+from plexdo.accounts import server_for_user
+from plexdo.console import output
+from plexdo.constants import LOG
+from plexdo.sections import resolve_sections
+from plexdo.titles import display_title
+
+
+_SEARCH_MEDIA_TYPES = ("movie", "show", "episode", "track", "photo", "album", "artist")
+
+
+def _search_result_row(item: Any) -> Dict[str, Any]:
+    """Build a result row from a search hit, resolving the library id."""
+    # plexapi attaches a librarySectionID attribute to all fetched items.
+    lib_id = int(
+        getattr(item, "librarySectionID", 0)
+    )
+    return {
+        "ratingKey": int(item.ratingKey),
+        "libraryId": lib_id,
+        "type":      item.type,
+        "title":     display_title(item),
+    }
+
+
+def _search_in_section(
+    section: Any,
+    query: str,
+    media_type: Optional[str],
+) -> List[Dict[str, Any]]:
+    """Search a single library section, optionally filtered by media type."""
+    kwargs: Dict[str, Any] = {}
+    if media_type:
+        kwargs["libtype"] = media_type
+    try:
+        hits = section.search(query, **kwargs)
+    except Exception as exc:  # pylint: disable=broad-except
+        LOG.warning("Search failed in library '%s': %s", section.title, exc)
+        return []
+    return [_search_result_row(item) for item in hits]  # type: ignore[arg-type]
+
+
+def _search_all_sections(
+    user_plex: PlexServer,
+    query: str,
+    media_type: Optional[str],
+    library_id: Optional[int],
+) -> List[Dict[str, Any]]:
+    """Run the search across one or all library sections."""
+    sections = resolve_sections(user_plex, library_id)
+    rows: List[Dict[str, Any]] = []
+    for section in sections:
+        rows.extend(_search_in_section(section, query, media_type))
+    return rows
+
+
+def cmd_search(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Search Plex for titles matching a query string."""
+    user_plex = server_for_user(plex, args.user_id)
+    library_id: Optional[int] = args.library_id
+    media_type: Optional[str] = args.media_type
+
+    LOG.info(
+        "Searching for %r (type=%s library=%s)", args.query, media_type, library_id
+    )
+    rows = _search_all_sections(user_plex, args.query, media_type, library_id)
+
+    if not rows:
+        LOG.info("No results found.")
+    output(rows, args)
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the search subparser."""
+    parser = sub.add_parser(
+        "search", parents=parents,
+        help="Search Plex for titles matching a query string.",
+    )
+    parser.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.",
+    )
+    parser.add_argument(
+        "query",
+        help="Search string (str). Plex performs a prefix/substring match.",
+    )
+    parser.add_argument(
+        "--media-type", dest="media_type",
+        choices=list(_SEARCH_MEDIA_TYPES), default=None, metavar="TYPE",
+        help=(
+            "Restrict results to a single media type. "
+            f"Choices: {', '.join(_SEARCH_MEDIA_TYPES)}."
+        ),
+    )
+    parser.add_argument(
+        "--library-id", dest="library_id", default=None, metavar="LIBRARY",
+        help="Restrict search to one library, by ID or title. Obtain both with list-libraries.",
+    )
+
+
+COMMANDS = {"search": cmd_search}
+
+REQUIRES_PLEX = frozenset(COMMANDS)

plexdo/commands/status.py

@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Consolidated server status: sessions, users, activity, and identity."""
+
+from typing import Any, Dict, List, Optional
+import argparse
+import sys
+
+from plexapi.server import PlexServer
+
+from plexdo.accounts import account_type
+from plexdo.console import clean_text, output, output_format, print_metadata, print_table, table_limit
+from plexdo.constants import LOG
+from plexdo.convert import format_duration, parse_date
+from plexdo.formats import render
+from plexdo.titles import display_title
+
+
+# Activity types Plex uses for library scanning, as opposed to the other
+# background work (metadata refresh, subscriptions, media analysis).
+_SCAN_MARKERS = ("scan", "refresh", "library")
+
+
+def _server_record(plex: PlexServer) -> Dict[str, Any]:
+    """Identity and version details for the server itself."""
+    updated = parse_date(getattr(plex, "updatedAt", None))
+    return {
+        "name": clean_text(getattr(plex, "friendlyName", "") or ""),
+        "version": clean_text(getattr(plex, "version", "") or ""),
+        "machineIdentifier": clean_text(getattr(plex, "machineIdentifier", "") or ""),
+        "platform": clean_text(getattr(plex, "platform", "") or ""),
+        "platformVersion": clean_text(getattr(plex, "platformVersion", "") or ""),
+        "updatedAt": updated.isoformat(sep=" ") if updated else "",
+        "myPlexUsername": clean_text(getattr(plex, "myPlexUsername", "") or ""),
+        "myPlexSubscription": bool(getattr(plex, "myPlexSubscription", False)),
+    }
+
+
+def _format_offset(milliseconds: Any, duration: Any) -> str:
+    """Render a playback position as elapsed / total."""
+    elapsed = format_duration(milliseconds) or "-"
+    total = format_duration(duration) or "-"
+    return f"{elapsed} / {total}"
+
+
+def _session_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """One row per item currently being played."""
+    rows: List[Dict[str, Any]] = []
+    for item in plex.sessions():
+        players = getattr(item, "players", []) or []
+        player = players[0] if players else None
+        usernames = getattr(item, "usernames", []) or []
+        rows.append({
+            "user": clean_text(usernames[0] if usernames else ""),
+            "title": display_title(item),
+            "state": clean_text(getattr(player, "state", "") or ""),
+            "player": clean_text(getattr(player, "title", "") or ""),
+            "platform": clean_text(getattr(player, "platform", "") or ""),
+            "address": clean_text(getattr(player, "address", "") or ""),
+            "progress": _format_offset(
+                getattr(item, "viewOffset", 0), getattr(item, "duration", 0)
+            ),
+        })
+    return rows
+
+
+def _user_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """Shared and managed users visible to the admin token."""
+    return [
+        {
+            "id": int(user.id),
+            "type": account_type(user),
+            "title": clean_text(user.title or ""),
+            "username": clean_text(getattr(user, "username", "") or ""),
+            "email": clean_text(getattr(user, "email", "") or ""),
+        }
+        for user in plex.myPlexAccount().users()
+    ]
+
+
+def _system_account_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """Accounts the server itself knows about, which is not the same list."""
+    return [
+        {
+            "id": int(account.id),
+            "name": clean_text(account.name or ""),
+            "audioLanguage": clean_text(getattr(account, "defaultAudioLanguage", "") or ""),
+            "subtitleLanguage": clean_text(
+                getattr(account, "defaultSubtitleLanguage", "") or ""
+            ),
+        }
+        for account in plex.systemAccounts()
+    ]
+
+
+def _connection_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """Addresses plex.tv advertises for this server."""
+    try:
+        resource = plex.myPlexAccount().resource(plex.friendlyName)
+        connections = list(resource.connections)
+    except Exception as exc:  # pylint: disable=broad-except
+        # Needs a plex.tv round trip, which a local-only or offline server
+        # cannot satisfy; the rest of the report is still worth printing.
+        LOG.debug("Could not list connections: %s", exc)
+        return []
+    return [
+        {
+            "uri": clean_text(conn.uri or ""),
+            "address": clean_text(conn.address or ""),
+            "port": conn.port,
+            "protocol": clean_text(conn.protocol or ""),
+            "local": bool(conn.local),
+            "relay": bool(conn.relay),
+            "ipv6": bool(getattr(conn, "ipv6", False)),
+        }
+        for conn in connections
+    ]
+
+
+def _is_scan(activity: Any) -> bool:
+    """True when an activity is library scanning rather than other work."""
+    kind = str(getattr(activity, "type", "")).lower()
+    return any(marker in kind for marker in _SCAN_MARKERS)
+
+
+def _split_activity_rows(plex: PlexServer, scans: bool) -> List[Dict[str, Any]]:
+    """In-progress activities, split into scans and everything else."""
+    return [
+        {
+            "type": clean_text(getattr(act, "type", "") or ""),
+            "title": clean_text(getattr(act, "title", "") or ""),
+            "subtitle": clean_text(getattr(act, "subtitle", "") or ""),
+            "progress": getattr(act, "progress", ""),
+            "cancellable": bool(getattr(act, "cancellable", False)),
+        }
+        for act in plex.activities
+        if _is_scan(act) is scans
+    ]
+
+
+def _butler_rows(plex: PlexServer) -> List[Dict[str, Any]]:
+    """Scheduled maintenance tasks and whether each is enabled."""
+    try:
+        tasks = plex.butlerTasks()
+    except Exception as exc:  # pylint: disable=broad-except
+        LOG.debug("Could not list butler tasks: %s", exc)
+        return []
+    return [
+        {
+            "name": clean_text(task.name or ""),
+            "title": clean_text(getattr(task, "title", "") or ""),
+            "enabled": bool(getattr(task, "enabled", False)),
+            "interval": getattr(task, "interval", ""),
+        }
+        for task in tasks
+    ]
+
+
+# Section name -> (heading, collector). Order sets the order of the report.
+_SECTIONS: Dict[str, Any] = {
+    "server": ("Server", _server_record),
+    "sessions": ("Active sessions", _session_rows),
+    "users": ("Shared users", _user_rows),
+    "accounts": ("System accounts", _system_account_rows),
+    "connections": ("Reachable addresses", _connection_rows),
+    "scans": ("Library scans in progress", lambda p: _split_activity_rows(p, True)),
+    "activities": ("Other background activity", lambda p: _split_activity_rows(p, False)),
+    "tasks": ("Scheduled background tasks", _butler_rows),
+}
+
+SECTION_NAMES = tuple(_SECTIONS)
+
+
+def _collect(plex: PlexServer, names: List[str]) -> Dict[str, Any]:
+    """Gather the requested sections, tolerating a failure in any one."""
+    gathered: Dict[str, Any] = {}
+    for name in names:
+        _, collector = _SECTIONS[name]
+        try:
+            gathered[name] = collector(plex)
+        except Exception as exc:  # pylint: disable=broad-except
+            # One unavailable section must not cost the whole report.
+            LOG.warning("Could not read %s: %s", name, exc)
+            gathered[name] = [] if name != "server" else {}
+    return gathered
+
+
+def _print_report(gathered: Dict[str, Any], limit: Optional[int]) -> None:
+    """Print the full multi-section report for the table renderer."""
+    for name, payload in gathered.items():
+        heading, _ = _SECTIONS[name]
+        print(f"\n{heading}")
+        if isinstance(payload, dict):
+            print_metadata(payload, limit)
+        elif payload:
+            print_table(payload, limit)
+        else:
+            print("  (none)")
+
+
+def cmd_status(plex: PlexServer, args: argparse.Namespace) -> None:
+    """Show a consolidated view of what the server is doing."""
+    names = [args.section] if args.section else list(SECTION_NAMES)
+    chosen = output_format(args)
+
+    # csv and clixml are flat by nature and cannot carry eight differently
+    # shaped sections, so one must be named.
+    if chosen in ("csv", "clixml") and not args.section:
+        sys.exit(
+            f"--format {chosen} needs a single section: pass --section with "
+            f"one of {', '.join(SECTION_NAMES)}."
+        )
+
+    gathered = _collect(plex, names)
+
+    if args.section:
+        output(gathered[args.section], args)
+        return
+    if chosen == "table":
+        _print_report(gathered, table_limit(args))
+        return
+    print(render(gathered, chosen))
+
+
+def register(
+    sub: "argparse._SubParsersAction",
+    parents: "List[argparse.ArgumentParser]",
+) -> None:
+    """Register the status subparser."""
+    parser = sub.add_parser(
+        "status", parents=parents,
+        help="Show server identity, sessions, users, scans, and background tasks.",
+    )
+    parser.add_argument(
+        "--section", choices=list(SECTION_NAMES), default=None, metavar="SECTION",
+        help=(
+            "Show only one section: " + ", ".join(SECTION_NAMES) + ". "
+            "Required for --format csv and --format clixml."
+        ),
+    )
+
+
+COMMANDS = {"status": cmd_status}
+
+REQUIRES_PLEX = frozenset(COMMANDS)