plextool 3.0.1__tar.gz

plextool-3.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milkmansson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plextool-3.0.1/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: plextool
+Version: 3.0.1
+Summary: Maintenance helpers for a Plex Media Server
+Author: Milkmansson
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/milkmansson/plextool
+Project-URL: Documentation, https://plextool.readthedocs.io/
+Project-URL: Source, https://github.com/milkmansson/plextool
+Project-URL: Issues, https://github.com/milkmansson/plextool/issues
+Keywords: plex,plex-media-server,plexapi,recently-added,duplicates,watched,subtitles,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: plexapi>=4.18
+Requires-Dist: pyjwt[crypto]
+Provides-Extra: qr
+Requires-Dist: segno; extra == "qr"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: segno; extra == "dev"
+Dynamic: license-file
+
+# plextool
+
+> [!WARNING]
+> Still in development/testing... please raise an issue if you find one!
+
+Command line tools for Plex library maintenance, built on
+[python-plexapi](https://python-plexapi.readthedocs.io/). They talk to the
+server through its API. Nothing here touches the Plex database file, which is
+too risky to edit by hand.
+
+## What it is useful for
+
+plextool is a command line toolkit for looking after a Plex Media Server: fixing
+things Plex's web interface can't, and finding problems across a large library.
+Typical jobs:
+
+- **Fix the Recently Added order.** This is what it was first built for. Plex has no way to
+  edit the Recently Added lists, so after you rebuild the database, delete
+  duplicate files and rescan, or reorganise files on disk, everything shows up as
+  "new" and the real newest content is buried. [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html)
+  changes the "added at" date of movies, shows, seasons and episodes: set each
+  item back to its own release or air date, shift dates by an offset, or set one date for a
+  whole batch. The date is locked so a rescan can't undo it.
+  ```console
+  $ plextool recent --recent 20 --release              # preview: put the 20 newest back to their release dates
+  $ plextool recent --title "Some Show" --shift=-30d --commit
+  ```
+- **Find and remove duplicate movies and episodes.** [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html)
+  lists every item Plex holds more than one file for, and can delete the extras you don't want.
+- **Free up disk space.** [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) finds large, never-watched or
+  long-idle movies and shows.
+- **Audit a library.** [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) reports unmatched items, missing files,
+  missing posters or summaries, low-resolution video, and missing subtitle or audio languages.
+- **Copy, back up and restore watched status.** [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) moves watched
+  state between users (for example when a shared account is split), saves it to a file, and
+  restores it after a rebuild or when someone closes and reopens their Plex account.
+- **Clear a stuck Continue Watching list.** [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) lists and removes
+  entries that won't go away.
+- **Back up and restore playlists.** [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) saves video playlists
+  to a file and recreates them on the same or another server.
+- **Get subtitles.** [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) extracts the subtitle tracks inside MKV and MP4
+  files, searches Plex's subtitle providers for a language and downloads one, and, with
+  `--export`, copies the subtitle Plex downloaded out of its database into a file beside
+  the video so it works outside Plex too. Plex itself never writes that file.
+- **Script Plex.** Reports can print JSON, and exports can go through a pipe, so the output
+  feeds other tools.
+
+Everything that changes the server is a preview until you pass `--commit`. plextool uses Plex's API and
+never edits the Plex database file. It signs in through your browser with
+[`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html), and works against a server on the same machine, across the
+internet, or directly with no internet access ([`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html)).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| [`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) | Sign in to Plex with a link or QR code, list and remove old sign-ins from your account, and wipe the saved login and keys. |
+| [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on your account or network and choose the one to use. Covers working offline or directly against the server. |
+| [`plextool status`](https://plextool.readthedocs.io/en/latest/commands/status.html) | Server version, library sizes, who is watching what. |
+| [`plextool scan`](https://plextool.readthedocs.io/en/latest/commands/scan.html) | Scan libraries or a single folder, refresh metadata, empty trash, optimize. |
+| [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html) | Change "added at" dates to reorder Recently Added. Works on movies, shows, seasons and episodes. |
+| [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html) | List movies and episodes that have more than one file, and optionally delete the extras. |
+| [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) | Find large, unwatched or long-idle content to free up space. |
+| [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) | Find unmatched items, missing files, missing posters or summaries, low resolution, missing subtitle or audio languages. |
+| [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) | Copy watched state between users, back it up and restore it, or mark a show or movie watched. |
+| [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) | List or clear stuck Continue Watching entries. |
+| [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) | Back up and restore video playlists. |
+| [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) | Extract subtitles from MKV and MP4 files, search Plex's subtitle providers for new ones and pick which to download, and copy subtitles Plex downloaded (kept in its database, not beside the video) out as files next to the video. Files are named for Plex, forced and SDH included. |
+
+The `plextool` commands that change anything do a dry run unless you pass
+`--commit`. Deleting files (`dupes --keep`) also asks you to type `DELETE`.
+
+## Quick start
+
+Install it from PyPI. This needs `python` installed as a prerequisite:
+
+```console
+$ python3 -m venv .venv && source .venv/bin/activate   # optional: keeps plextool's packages separate
+$ pip install 'plextool[qr]'        # '[qr]' adds a QR code to the sign-in; leave it off if you don't want one
+$ plextool auth login               # open the link it prints (or scan the QR code) and approve
+$ plextool server find              # servers on your Plex account and on your network
+$ plextool server use "My Server"   # one of the names from the list
+$ plextool status                   # libraries, and who is watching what right now
+```
+
+`status` ends with what is playing:
+
+```console
+Now playing (1 session, 0 transcoding)
+  alice: Some Movie (2020) [playing] on Living Room TV
+```
+
+To get, say, Swedish subtitles for that movie from the subtitle providers Plex searches:
+
+```console
+$ plextool subs fetch -t "Some Movie" --lang sv --list               # see what is available; nothing is downloaded
+$ plextool subs fetch -t "Some Movie" --lang sv --choose --commit    # pick one; Plex downloads it
+$ plextool subs fetch -t "Some Movie" --lang sv --choose --export --commit   # same, and also save a file beside the video
+```
+
+**Where the subtitle ends up.** When Plex downloads a subtitle from a provider, it keeps
+the copy in its own database. It does not put a file next to the video, so only Plex can
+show it: another player, or another Plex server, never sees it. The first two commands stop
+there, and you pick the subtitle from the player's subtitle menu.
+
+**`--export` gets around that.** Once Plex has downloaded the subtitle, plextool copies
+Plex's stored copy out of the server and saves it as an ordinary file beside the video
+(`<video name>.sv.srt`), which any player can use. It doesn't read the video file, so the
+MKV or MP4 is never opened, and it doesn't contact the subtitle provider. (Subtitle
+tracks that are already inside an MKV or MP4 are a different job, for `plextool subs extract`.)
+For `--export`, the machine you run it on must be able to read the media files. If it sees
+them under a different path than Plex does, use `--map`. The
+[`subs` page](https://plextool.readthedocs.io/en/latest/commands/subs.html#where-each-subtitle-comes-from) sets out where each kind of subtitle comes from.
+
+For a TV show, `-t "Some Show"` covers every episode, which is a search for each one,
+so start with `--list`.
+
+If the server is on the machine you are typing on, skip `server find` and `server use`:
+plextool tries `http://localhost:32400` by default. Without internet access, see
+[working offline](https://plextool.readthedocs.io/en/latest/commands/server.html#working-offline-or-directly-against-the-server).
+
+## Getting help
+
+Every command explains itself, with options and examples:
+
+```console
+$ plextool --help
+$ plextool recent --help
+$ plextool watched copy --help
+```
+
+A fuller page for each command is on [Read the Docs](https://plextool.readthedocs.io/)
+(linked in the table above); its source is in `docs/source/commands/`.
+
+## Install
+
+plextool is tested on Python 3.12. It declares Python 3.9 or later, so pip will
+install it on older versions. If something doesn't work on one, please
+[open an issue](https://github.com/milkmansson/plextool/issues) with your Python
+version.
+
+`plextool subs` also needs MKVToolNix (`mkvmerge`, `mkvextract`) for MKV files and
+FFmpeg (`ffmpeg`, `ffprobe`) for MP4 files. You only need the ones for the file types
+you use.
+
+```console
+$ pip install plextool     # installs the `plextool` command
+$ plextool --help
+```
+
+To install from a checkout instead (this needs `git`):
+
+```console
+$ git clone https://github.com/milkmansson/plextool.git
+$ cd plextool
+$ pip install .
+```
+
+To run from a checkout without installing, `pip install -r requirements.txt`
+and use `python3 -m plextool ...` instead.
+
+## Connecting
+
+Sign in once. This prints a link (and a QR code, if `segno` is installed) to
+approve in a browser:
+
+```console
+$ plextool auth login
+$ plextool server find                       # skip if the server is on this machine
+$ plextool server use "My Server"            # or: server use http://myserver:32400
+```
+
+Without a saved choice, plextool uses `http://localhost:32400`, or `$PLEX_URL`
+or `--base-url` if given. [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) explains the
+options, including working with no internet or directly on the server's machine.
+
+That saves a Plex token in `~/.config/plextool/` (readable only by you).
+[`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) explains exactly what is kept, how to wipe it
+with `plextool auth wipe`, and `--type jwt`, a short-lived token that plex.tv
+accepts but Plex Media Server doesn't yet.
+
+If you would rather supply your own [Plex token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/),
+plextool looks for one in this order: `--token`, `--token-file FILE` (`-` for
+standard input), `$PLEX_TOKEN`, the output of `$PLEX_TOKEN_CMD`, then the saved
+login. Prefer `--token-file` or the environment to `--token`, which leaves the
+token in your shell history.
+
+## Development
+
+```console
+$ pip install -e '.[dev]'
+$ pytest
+```
+
+## Disclaimer
+
+These tools only use the documented plexapi calls, but they do write to your
+server when you pass `--commit`. Check the dry run first. Use at your own risk.

plextool-3.0.1/README.md

@@ -0,0 +1,198 @@
+# plextool
+
+> [!WARNING]
+> Still in development/testing... please raise an issue if you find one!
+
+Command line tools for Plex library maintenance, built on
+[python-plexapi](https://python-plexapi.readthedocs.io/). They talk to the
+server through its API. Nothing here touches the Plex database file, which is
+too risky to edit by hand.
+
+## What it is useful for
+
+plextool is a command line toolkit for looking after a Plex Media Server: fixing
+things Plex's web interface can't, and finding problems across a large library.
+Typical jobs:
+
+- **Fix the Recently Added order.** This is what it was first built for. Plex has no way to
+  edit the Recently Added lists, so after you rebuild the database, delete
+  duplicate files and rescan, or reorganise files on disk, everything shows up as
+  "new" and the real newest content is buried. [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html)
+  changes the "added at" date of movies, shows, seasons and episodes: set each
+  item back to its own release or air date, shift dates by an offset, or set one date for a
+  whole batch. The date is locked so a rescan can't undo it.
+  ```console
+  $ plextool recent --recent 20 --release              # preview: put the 20 newest back to their release dates
+  $ plextool recent --title "Some Show" --shift=-30d --commit
+  ```
+- **Find and remove duplicate movies and episodes.** [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html)
+  lists every item Plex holds more than one file for, and can delete the extras you don't want.
+- **Free up disk space.** [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) finds large, never-watched or
+  long-idle movies and shows.
+- **Audit a library.** [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) reports unmatched items, missing files,
+  missing posters or summaries, low-resolution video, and missing subtitle or audio languages.
+- **Copy, back up and restore watched status.** [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) moves watched
+  state between users (for example when a shared account is split), saves it to a file, and
+  restores it after a rebuild or when someone closes and reopens their Plex account.
+- **Clear a stuck Continue Watching list.** [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) lists and removes
+  entries that won't go away.
+- **Back up and restore playlists.** [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) saves video playlists
+  to a file and recreates them on the same or another server.
+- **Get subtitles.** [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) extracts the subtitle tracks inside MKV and MP4
+  files, searches Plex's subtitle providers for a language and downloads one, and, with
+  `--export`, copies the subtitle Plex downloaded out of its database into a file beside
+  the video so it works outside Plex too. Plex itself never writes that file.
+- **Script Plex.** Reports can print JSON, and exports can go through a pipe, so the output
+  feeds other tools.
+
+Everything that changes the server is a preview until you pass `--commit`. plextool uses Plex's API and
+never edits the Plex database file. It signs in through your browser with
+[`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html), and works against a server on the same machine, across the
+internet, or directly with no internet access ([`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html)).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| [`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) | Sign in to Plex with a link or QR code, list and remove old sign-ins from your account, and wipe the saved login and keys. |
+| [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on your account or network and choose the one to use. Covers working offline or directly against the server. |
+| [`plextool status`](https://plextool.readthedocs.io/en/latest/commands/status.html) | Server version, library sizes, who is watching what. |
+| [`plextool scan`](https://plextool.readthedocs.io/en/latest/commands/scan.html) | Scan libraries or a single folder, refresh metadata, empty trash, optimize. |
+| [`plextool recent`](https://plextool.readthedocs.io/en/latest/commands/recent.html) | Change "added at" dates to reorder Recently Added. Works on movies, shows, seasons and episodes. |
+| [`plextool dupes`](https://plextool.readthedocs.io/en/latest/commands/dupes.html) | List movies and episodes that have more than one file, and optionally delete the extras. |
+| [`plextool stale`](https://plextool.readthedocs.io/en/latest/commands/stale.html) | Find large, unwatched or long-idle content to free up space. |
+| [`plextool audit`](https://plextool.readthedocs.io/en/latest/commands/audit.html) | Find unmatched items, missing files, missing posters or summaries, low resolution, missing subtitle or audio languages. |
+| [`plextool watched`](https://plextool.readthedocs.io/en/latest/commands/watched.html) | Copy watched state between users, back it up and restore it, or mark a show or movie watched. |
+| [`plextool resume`](https://plextool.readthedocs.io/en/latest/commands/resume.html) | List or clear stuck Continue Watching entries. |
+| [`plextool playlists`](https://plextool.readthedocs.io/en/latest/commands/playlists.html) | Back up and restore video playlists. |
+| [`plextool subs`](https://plextool.readthedocs.io/en/latest/commands/subs.html) | Extract subtitles from MKV and MP4 files, search Plex's subtitle providers for new ones and pick which to download, and copy subtitles Plex downloaded (kept in its database, not beside the video) out as files next to the video. Files are named for Plex, forced and SDH included. |
+
+The `plextool` commands that change anything do a dry run unless you pass
+`--commit`. Deleting files (`dupes --keep`) also asks you to type `DELETE`.
+
+## Quick start
+
+Install it from PyPI. This needs `python` installed as a prerequisite:
+
+```console
+$ python3 -m venv .venv && source .venv/bin/activate   # optional: keeps plextool's packages separate
+$ pip install 'plextool[qr]'        # '[qr]' adds a QR code to the sign-in; leave it off if you don't want one
+$ plextool auth login               # open the link it prints (or scan the QR code) and approve
+$ plextool server find              # servers on your Plex account and on your network
+$ plextool server use "My Server"   # one of the names from the list
+$ plextool status                   # libraries, and who is watching what right now
+```
+
+`status` ends with what is playing:
+
+```console
+Now playing (1 session, 0 transcoding)
+  alice: Some Movie (2020) [playing] on Living Room TV
+```
+
+To get, say, Swedish subtitles for that movie from the subtitle providers Plex searches:
+
+```console
+$ plextool subs fetch -t "Some Movie" --lang sv --list               # see what is available; nothing is downloaded
+$ plextool subs fetch -t "Some Movie" --lang sv --choose --commit    # pick one; Plex downloads it
+$ plextool subs fetch -t "Some Movie" --lang sv --choose --export --commit   # same, and also save a file beside the video
+```
+
+**Where the subtitle ends up.** When Plex downloads a subtitle from a provider, it keeps
+the copy in its own database. It does not put a file next to the video, so only Plex can
+show it: another player, or another Plex server, never sees it. The first two commands stop
+there, and you pick the subtitle from the player's subtitle menu.
+
+**`--export` gets around that.** Once Plex has downloaded the subtitle, plextool copies
+Plex's stored copy out of the server and saves it as an ordinary file beside the video
+(`<video name>.sv.srt`), which any player can use. It doesn't read the video file, so the
+MKV or MP4 is never opened, and it doesn't contact the subtitle provider. (Subtitle
+tracks that are already inside an MKV or MP4 are a different job, for `plextool subs extract`.)
+For `--export`, the machine you run it on must be able to read the media files. If it sees
+them under a different path than Plex does, use `--map`. The
+[`subs` page](https://plextool.readthedocs.io/en/latest/commands/subs.html#where-each-subtitle-comes-from) sets out where each kind of subtitle comes from.
+
+For a TV show, `-t "Some Show"` covers every episode, which is a search for each one,
+so start with `--list`.
+
+If the server is on the machine you are typing on, skip `server find` and `server use`:
+plextool tries `http://localhost:32400` by default. Without internet access, see
+[working offline](https://plextool.readthedocs.io/en/latest/commands/server.html#working-offline-or-directly-against-the-server).
+
+## Getting help
+
+Every command explains itself, with options and examples:
+
+```console
+$ plextool --help
+$ plextool recent --help
+$ plextool watched copy --help
+```
+
+A fuller page for each command is on [Read the Docs](https://plextool.readthedocs.io/)
+(linked in the table above); its source is in `docs/source/commands/`.
+
+## Install
+
+plextool is tested on Python 3.12. It declares Python 3.9 or later, so pip will
+install it on older versions. If something doesn't work on one, please
+[open an issue](https://github.com/milkmansson/plextool/issues) with your Python
+version.
+
+`plextool subs` also needs MKVToolNix (`mkvmerge`, `mkvextract`) for MKV files and
+FFmpeg (`ffmpeg`, `ffprobe`) for MP4 files. You only need the ones for the file types
+you use.
+
+```console
+$ pip install plextool     # installs the `plextool` command
+$ plextool --help
+```
+
+To install from a checkout instead (this needs `git`):
+
+```console
+$ git clone https://github.com/milkmansson/plextool.git
+$ cd plextool
+$ pip install .
+```
+
+To run from a checkout without installing, `pip install -r requirements.txt`
+and use `python3 -m plextool ...` instead.
+
+## Connecting
+
+Sign in once. This prints a link (and a QR code, if `segno` is installed) to
+approve in a browser:
+
+```console
+$ plextool auth login
+$ plextool server find                       # skip if the server is on this machine
+$ plextool server use "My Server"            # or: server use http://myserver:32400
+```
+
+Without a saved choice, plextool uses `http://localhost:32400`, or `$PLEX_URL`
+or `--base-url` if given. [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) explains the
+options, including working with no internet or directly on the server's machine.
+
+That saves a Plex token in `~/.config/plextool/` (readable only by you).
+[`plextool auth`](https://plextool.readthedocs.io/en/latest/commands/auth.html) explains exactly what is kept, how to wipe it
+with `plextool auth wipe`, and `--type jwt`, a short-lived token that plex.tv
+accepts but Plex Media Server doesn't yet.
+
+If you would rather supply your own [Plex token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/),
+plextool looks for one in this order: `--token`, `--token-file FILE` (`-` for
+standard input), `$PLEX_TOKEN`, the output of `$PLEX_TOKEN_CMD`, then the saved
+login. Prefer `--token-file` or the environment to `--token`, which leaves the
+token in your shell history.
+
+## Development
+
+```console
+$ pip install -e '.[dev]'
+$ pytest
+```
+
+## Disclaimer
+
+These tools only use the documented plexapi calls, but they do write to your
+server when you pass `--commit`. Check the dry run first. Use at your own risk.

plextool-3.0.1/plextool/__init__.py

@@ -0,0 +1,3 @@
+"""plextool: maintenance helpers for a Plex Media Server, built on python-plexapi."""
+
+__version__ = "3.0.1"

plextool-3.0.1/plextool/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

plextool-3.0.1/plextool/audit.py

@@ -0,0 +1,142 @@
+"""audit: find metadata and file problems across libraries."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .common import (
+    FILE_LEVEL,
+    PlexToolError,
+    add_command,
+    add_connection_args,
+    add_library_arg,
+    connect,
+    describe,
+    paint,
+    pick_sections,
+    plural,
+)
+
+LOW_RES = {"sd", "480", "576", "360", "240"}
+UNMATCHED_PREFIXES = ("local://", "com.plexapp.agents.none")
+
+
+# Each check takes (item, lang) and returns a short reason string, or None if the item is fine.
+
+def check_unmatched(item, lang):
+    if str(item.guid).startswith(UNMATCHED_PREFIXES):
+        return "not matched to an online source"
+
+
+def check_no_poster(item, lang):
+    if not item.thumb:
+        return "no poster"
+
+
+def check_no_summary(item, lang):
+    if not item.summary:
+        return "no summary"
+
+
+def check_missing_files(item, lang):
+    bad = [part.file for media in item.media for part in media.parts if part.exists is False]
+    if bad:
+        return f"file missing on disk: {bad[0]}" + (f" (+{len(bad) - 1} more)" if len(bad) > 1 else "")
+
+
+def check_low_res(item, lang):
+    resolutions = {m.videoResolution for m in item.media if m.videoResolution}
+    if resolutions and resolutions <= LOW_RES:
+        return f"low resolution ({', '.join(sorted(resolutions))})"
+
+
+def _streams(item, kind):
+    return [s for media in item.media for part in media.parts for s in getattr(part, kind)()]
+
+
+def check_no_subs(item, lang):
+    if not any(s.languageCode == lang for s in _streams(item, "subtitleStreams")):
+        return f"no '{lang}' subtitles"
+
+
+def check_no_audio(item, lang):
+    if not any(s.languageCode == lang for s in _streams(item, "audioStreams")):
+        return f"no '{lang}' audio"
+
+
+# name -> (function, works on files (movie/episode) rather than the library's top level, needs --lang,
+#          needs the full item loaded to see its streams)
+CHECKS = {
+    "unmatched": (check_unmatched, False, False, False),
+    "no-poster": (check_no_poster, False, False, False),
+    "no-summary": (check_no_summary, False, False, False),
+    "missing-files": (check_missing_files, True, False, False),
+    "low-res": (check_low_res, True, False, False),
+    "no-subs": (check_no_subs, True, True, True),
+    "no-audio": (check_no_audio, True, True, True),
+}
+
+
+def run_check(name: str, items: list, lang: str | None) -> list[dict]:
+    """Apply one check to items; returns [{'item': description, 'reason': ...}]."""
+    func, _, _, needs_full = CHECKS[name]
+    found = []
+    for item in items:
+        if needs_full:
+            item.reload()
+        reason = func(item, lang)
+        if reason:
+            found.append({"item": describe(item), "reason": reason})
+    return found
+
+
+def add_parser(subparsers) -> None:
+    parser = add_command(
+        subparsers, 'audit',
+        'find unmatched items, missing files, missing subtitles and more',
+        "Report problems in your libraries. Read-only. Checks: unmatched, no-poster, no-summary, missing-files, low-res, no-subs, no-audio. With no --check, every check that doesn't need --lang runs. no-subs and no-audio read every item's tracks and are slow on large libraries.",
+        ['plextool audit',
+        'plextool audit -c missing-files -c unmatched',
+        "plextool audit -c no-subs --lang eng -l 'TV Shows'"])
+    add_connection_args(parser)
+    add_library_arg(parser)
+    parser.add_argument("-c", "--check", action="append", choices=list(CHECKS), metavar="CHECK",
+                        help="check to run; repeat for several (default: all that don't need --lang)")
+    parser.add_argument("--lang", help="3-letter language code, as Plex shows it, for no-subs / no-audio, eg eng")
+    parser.add_argument("-n", "--limit", type=int, metavar="N", help="show at most N problems per check")
+    parser.add_argument("--json", action="store_true", help="print JSON instead of text")
+    parser.set_defaults(run=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    names = args.check or [n for n, (_, _, needs_lang, _) in CHECKS.items() if not needs_lang]
+    for name in names:
+        if CHECKS[name][2] and not args.lang:
+            raise PlexToolError(f"Check '{name}' needs --lang, eg --lang eng")
+    if args.limit is not None and args.limit < 1:
+        raise PlexToolError("--limit must be at least 1")
+
+    plex = connect(args)
+    report: dict = {}
+    for section in pick_sections(plex, args.library):
+        cache: dict[str, list] = {}
+        for name in names:
+            level = FILE_LEVEL[section.TYPE] if CHECKS[name][1] else section.TYPE
+            if level not in cache:
+                cache[level] = section.search(libtype=level)
+            report.setdefault(name, {})[section.title] = run_check(name, cache[level], args.lang)
+
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        return 0
+
+    total = 0
+    for name, libs in report.items():
+        for title, problems in libs.items():
+            print(paint(f"\n== {name} in {title}: {plural(len(problems), 'problem')} ==", "cyan"))
+            for problem in problems[:args.limit]:
+                print(f"  {problem['item']}: {problem['reason']}")
+            total += len(problems)
+    print(f"\n{plural(total, 'problem')} found.")
+    return 0