plextool 3.0.1__py3-none-any.whl

plextool/recent.py

@@ -0,0 +1,203 @@
+"""recent: rewrite 'added at' dates to reorder Plex's Recently Added lists."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from datetime import datetime, timedelta
+
+from .common import (
+    SECTION_LEVELS,
+    PlexToolError,
+    add_command,
+    add_connection_args,
+    connect,
+    describe,
+    paint,
+    pick_sections,
+    plural,
+)
+
+_SHIFT_RE = re.compile(r"^([+-]?)(\d+)(min|h|d|w)$")
+_SHIFT_UNITS = {"min": "minutes", "h": "hours", "d": "days", "w": "weeks"}
+
+
+def parse_date(text: str) -> datetime:
+    """Parse 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'."""
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"'{text}' is not a date; use YYYY-MM-DD or 'YYYY-MM-DD HH:MM:SS'") from None
+
+
+def parse_shift(text: str) -> timedelta:
+    """Parse a relative offset such as '+30d', '-2w', '6h' or '90min' (sign optional)."""
+    match = _SHIFT_RE.match(text.strip())
+    if not match:
+        raise argparse.ArgumentTypeError(
+            f"'{text}' is not a shift; use a number and a unit (min, h, d, w), eg -30d")
+    sign, amount, unit = match.groups()
+    delta = timedelta(**{_SHIFT_UNITS[unit]: int(amount)})
+    return -delta if sign == "-" else delta
+
+
+def new_date(item, args: argparse.Namespace, now: datetime) -> datetime | None:
+    """The date this item should get, or None if it can't be worked out."""
+    if args.date:
+        return args.date
+    if args.now:
+        return now
+    if args.release:
+        return item.originallyAvailableAt
+    if item.addedAt is None:
+        return None
+    return item.addedAt + args.shift
+
+
+def find_by_guid(section, level: str, guid: str) -> list:
+    """Find items by Plex GUID (plex://...) or an agent GUID (imdb://, tmdb://, tvdb://)."""
+    if guid.startswith("plex://"):
+        return section.search(guid=guid, libtype=level)
+    return [item for item in section.search(libtype=level)
+            if any(g.id == guid for g in getattr(item, "guids", []))]
+
+
+def find_items(section, level: str, args: argparse.Namespace) -> list:
+    if args.title:
+        return section.search(title=args.title, libtype=level)
+    if args.guid:
+        return find_by_guid(section, level, args.guid)
+    return section.recentlyAdded(maxresults=args.recent, libtype=level)
+
+
+def expand(item, cascade: bool) -> list:
+    """The item itself, plus its seasons and episodes if cascading from a show or season."""
+    targets = [item]
+    if cascade:
+        if item.type == "show":
+            targets += item.seasons() + item.episodes()
+        elif item.type == "season":
+            targets += item.episodes()
+    return targets
+
+
+def show_item(index: int, item) -> None:
+    released = getattr(item, "originallyAvailableAt", None)
+    print(f"{paint(str(index).rjust(6), 'cyan')}: {paint(describe(item), 'bold')}")
+    print(f"        Released: {released}")
+    print(f"           Added: {item.addedAt}")
+    print(f"         Plex ID: {item.guid}")
+    for k, guid in enumerate(getattr(item, "guids", []), start=1):
+        print(f"        GUID[{k:02d}]: {guid.id}")
+
+
+def apply_dates(item, args: argparse.Namespace, now: datetime) -> dict:
+    """Set (or preview) the new date on item and, if cascading, its children.
+
+    Returns counts of 'changed' (which means 'would change' on a dry run),
+    'unchanged' and 'skipped' (no date available, eg no release date).
+    """
+    counts = {"changed": 0, "unchanged": 0, "skipped": 0}
+    children = {"changed": 0, "unchanged": 0, "skipped": 0}
+    for target in expand(item, args.cascade):
+        tally = counts if target is item else children
+        date = new_date(target, args, now)
+        if date is None:
+            tally["skipped"] += 1
+            continue
+        if target.addedAt == date:
+            tally["unchanged"] += 1
+            continue
+        previous = target.addedAt
+        if args.commit:
+            target.editAddedAt(date, locked=not args.no_lock)
+            target.reload()
+        tally["changed"] += 1
+        if target is item:
+            if args.commit:
+                print(paint(f"      ! Date changed from {previous} to {target.addedAt}", "yellow"))
+            else:
+                print(paint(f"      ! Date would change from {previous} to {date}", "red"))
+    if counts["skipped"]:
+        print(paint("      ! No date available for this item (no release date?); skipped", "red"))
+    if args.cascade:
+        verb = "changed" if args.commit else "would change"
+        print(f"      + children: {children['changed']} {verb}, "
+              f"{children['unchanged']} already correct, {children['skipped']} skipped")
+    return {k: counts[k] + children[k] for k in counts}
+
+
+def add_parser(subparsers) -> None:
+    parser = add_command(
+        subparsers, 'recent',
+        "change 'added at' dates to reorder Recently Added",
+        "Change the 'added at' date of movies, shows, seasons or episodes, which moves them in Plex's Recently Added lists. Pick what to change (--title, --guid or --recent) and the new date (--date, --release, --now or --shift). Nothing is written unless --commit is given.\n\nPlex builds the TV Recently Added list from episodes. To reorder a series, use --cascade or --level episode.",
+        ['plextool recent -l Movies -n 3 --release                  # preview the last 3 movies',
+        'plextool recent -g plex://movie/abc123 --release --commit',
+        "plextool recent -l 'TV Shows' -t 'Some Show' --cascade --release --commit",
+        "plextool recent -l 'TV Shows' --level episode -n 20 --shift=-7d --commit"])
+    add_connection_args(parser)
+    parser.add_argument("-l", "--library", action="append", metavar="NAME",
+                        help="library name; repeat for several (default: all movie and TV libraries)")
+    parser.add_argument("--level", choices=sorted({lv for lvs in SECTION_LEVELS.values() for lv in lvs}),
+                        help="what to change: movie, show, season or episode "
+                             "(default: movie for movie libraries, show for TV libraries)")
+    parser.add_argument("--cascade", action="store_true",
+                        help="when changing a show or season, change its seasons and episodes too")
+
+    select = parser.add_mutually_exclusive_group(required=True)
+    select.add_argument("-t", "--title", help="select by title (substring match)")
+    select.add_argument("-g", "--guid", dest="guid", metavar="GUID",
+                        help="select by Plex ID (plex://movie/...) or agent ID (imdb://tt..., tmdb://..., tvdb://...)")
+    select.add_argument("-n", "--recent", type=int, metavar="N",
+                        help="select the N most recently added items (per library)")
+
+    when = parser.add_mutually_exclusive_group(required=True)
+    when.add_argument("-d", "--date", type=parse_date, metavar="DATE",
+                      help="set this date: YYYY-MM-DD or 'YYYY-MM-DD HH:MM:SS'")
+    when.add_argument("-r", "--release", action="store_true",
+                      help="set each item's date to its own original release/air date")
+    when.add_argument("-N", "--now", action="store_true", help="set the date to right now")
+    when.add_argument("-s", "--shift", type=parse_shift, metavar="OFFSET",
+                      help="move each item's current date by an offset, eg +2w, 6h, 90min; write negatives with an = sign: --shift=-30d")
+
+    parser.add_argument("--no-lock", action="store_true",
+                        help="don't lock the date; by default it is locked so a rescan or "
+                             "metadata refresh can't reset it")
+    parser.add_argument("-y", "--commit", dest="commit", action="store_true",
+                        help="write the changes (default is a dry run)")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.recent is not None and args.recent < 1:
+        raise PlexToolError("--recent must be at least 1")
+    plex = connect(args)
+    sections = pick_sections(plex, args.library)
+    now = datetime.now().replace(microsecond=0)
+    totals = {"changed": 0, "unchanged": 0, "skipped": 0}
+
+    for section in sections:
+        level = args.level or section.TYPE
+        if level not in SECTION_LEVELS[section.TYPE]:
+            if args.library:
+                raise PlexToolError(
+                    f"--level {level} doesn't apply to the {section.TYPE} library '{section.title}'")
+            continue
+        if args.cascade and level == "movie":
+            raise PlexToolError("--cascade only applies to shows and seasons")
+        items = find_items(section, level, args)
+        print(paint(f" * {section.title}: found {plural(len(items), level)}", "cyan"))
+        for index, item in enumerate(items, start=1):
+            show_item(index, item)
+            for key, value in apply_dates(item, args, now).items():
+                totals[key] += value
+            print()
+
+    verb = "Changed" if args.commit else "Would change"
+    print(f"{verb} {totals['changed']} item(s); {totals['unchanged']} already correct; "
+          f"{totals['skipped']} skipped.")
+    if not args.commit and totals["changed"]:
+        print("Dry run only. Re-run with --commit to apply.")
+    return 0

plextool/resume.py

@@ -0,0 +1,61 @@
+"""resume: tidy the Continue Watching list."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timedelta
+
+from .common import PlexToolError, add_command, add_connection_args, connect, describe
+
+
+def percent(item) -> int:
+    if item.viewOffset and item.duration:
+        return min(100, round(100 * item.viewOffset / item.duration))
+    return 0
+
+
+def select(items: list, now: datetime, idle_days: int | None = None) -> list:
+    """Partly watched items, optionally only those untouched for idle_days."""
+    chosen = [i for i in items if i.viewOffset]
+    if idle_days is not None:
+        cutoff = now - timedelta(days=idle_days)
+        chosen = [i for i in chosen if i.lastViewedAt is None or i.lastViewedAt < cutoff]
+    return chosen
+
+
+def add_parser(subparsers) -> None:
+    parser = add_command(
+        subparsers, 'resume',
+        'list or clear Continue Watching entries',
+        "List partly-watched items in the token owner's Continue Watching. With --clear, remove them by marking them watched or unwatched. Nothing is written unless --commit is given.",
+        ['plextool resume',
+        'plextool resume --idle 90 --clear watched            # preview',
+        'plextool resume --idle 90 --clear watched --commit'])
+    add_connection_args(parser)
+    parser.add_argument("--idle", type=int, metavar="DAYS", help="only items not played in the last DAYS days")
+    parser.add_argument("--clear", choices=("watched", "unwatched"),
+                        help="mark the listed items watched, or unwatched. Unwatched also "
+                             "resets any earlier view count on that item.")
+    parser.add_argument("-y", "--commit", action="store_true", help="write the changes (default is a dry run)")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.commit and not args.clear:
+        raise PlexToolError("--commit needs --clear watched|unwatched")
+    plex = connect(args)
+    items = select(plex.continueWatching(), datetime.now(), args.idle)
+    if not items:
+        print("Nothing in progress.")
+        return 0
+    for number, item in enumerate(items, start=1):
+        seen = item.lastViewedAt.strftime("%Y-%m-%d") if item.lastViewedAt else "?"
+        print(f"{number:>4}  {percent(item):>3}%  last played {seen}  {describe(item)}")
+        if args.clear and args.commit:
+            item.markPlayed() if args.clear == "watched" else item.markUnplayed()
+    if args.clear:
+        verb = "Marked" if args.commit else "Would mark"
+        print(f"\n{verb} {len(items)} item(s) {args.clear}.")
+        if not args.commit:
+            print("Dry run only. Re-run with --commit to apply.")
+    return 0

plextool/scan.py

@@ -0,0 +1,80 @@
+"""scan: trigger library scans, metadata refreshes and clean-up."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+from .common import (
+    PlexToolError,
+    add_command,
+    add_connection_args,
+    add_library_arg,
+    connect,
+    paint,
+    pick_sections,
+)
+
+
+def add_parser(subparsers) -> None:
+    parser = add_command(
+        subparsers, 'scan',
+        'scan libraries, refresh metadata, empty trash',
+        'Ask the server to scan libraries for new files. With no action option this is a plain scan. Scans run on the server, so the command returns at once unless you use --wait.',
+        ['plextool scan',
+        'plextool scan -l Movies --path /mnt/media/Movies/New --wait',
+        "plextool scan -l 'TV Shows' --refresh",
+        'plextool scan --empty-trash --optimize'])
+    add_connection_args(parser)
+    add_library_arg(parser)
+    parser.add_argument("--path", help="scan only this folder (as the server sees it); needs one --library")
+    parser.add_argument("--refresh", action="store_true",
+                        help="force a metadata refresh from the internet (slow; locked fields are kept)")
+    parser.add_argument("--empty-trash", action="store_true", help="empty the trash of each library")
+    parser.add_argument("--optimize", action="store_true", help="optimize the server database")
+    parser.add_argument("--clean-bundles", action="store_true", help="remove unused metadata bundles")
+    parser.add_argument("--wait", action="store_true", help="wait until the scans finish")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    plex = connect(args)
+    sections = pick_sections(plex, args.library)
+    if args.path and len(sections) != 1:
+        raise PlexToolError("--path needs exactly one --library.")
+
+    only_maintenance = (args.empty_trash or args.optimize or args.clean_bundles) and not (
+        args.refresh or args.path)
+    for section in sections:
+        if args.empty_trash:
+            section.emptyTrash()
+            print(f"Emptied trash: {section.title}")
+        if args.refresh:
+            section.refresh()
+            print(f"Refreshing metadata: {section.title}")
+        elif not only_maintenance:
+            section.update(path=args.path)
+            print(f"Scanning: {section.title}" + (f" ({args.path})" if args.path else ""))
+    if args.optimize:
+        plex.library.optimize()
+        print("Database optimization started.")
+    if args.clean_bundles:
+        plex.library.cleanBundles()
+        print("Bundle clean-up started.")
+
+    if args.wait:
+        wait_for_scans(plex, [s.title for s in sections])
+    return 0
+
+
+def wait_for_scans(plex, titles: list[str], interval: float = 3.0) -> None:
+    """Poll until none of the named libraries report that they are refreshing."""
+    # A scan may take a moment to show up as 'refreshing'.
+    time.sleep(interval)
+    while True:
+        busy = [s.title for s in plex.library.sections() if s.title in titles and s.refreshing]
+        if not busy:
+            print(paint("Scans finished.", "green"))
+            return
+        print(f"  still working: {', '.join(busy)}")
+        time.sleep(interval)