plextool 3.1.0__tar.gz → 3.2.0__tar.gz

{plextool-3.1.0 → plextool-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plextool
-Version: 3.1.0
+Version: 3.2.0
 Summary: Maintenance helpers for a Plex Media Server
 Author: Milkmansson
 License-Expression: MIT
@@ -19,7 +19,7 @@ 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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: plexapi>=4.18
@@ -37,16 +37,12 @@ Dynamic: license-file
 > [!WARNING]
 > Still in development/testing... please raise an issue if one is found!
 
-Command line tool for Plex library maintenance, built on
-[python-plexapi](https://python-plexapi.readthedocs.io/). It talks to the
-server through its API. No access is made to the Plex database file, which is
-too risky to edit by hand.
+Swiss army knife command line tool for Plex library maintenance. Built on [python-plexapi](https://python-plexapi.readthedocs.io/), which talks to the
+server through its API.  No accesses is made to 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:
+plextool is a CLI toolkit for looking after a Plex Media Server: fixing things Plex's web interface can't, giving CLI methods to things that would otherwise need many clicks through the web interface for, for server maintenance over SSH, and for finding and fixing problems in large libraries.  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 the database is rebuilt, duplicate
@@ -59,10 +55,20 @@ Typical jobs:
   $ plextool recent --recent 20 --release              # preview: put the 20 newest back to their release dates
   $ plextool recent --title "Some Show" --shift=-30d --commit
   ```
+- **Manage who has access.** [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) lists who can use the server, invites people, changes
+  what they can see and removes them, with a preview of exactly what would be granted or lost.
+- **Tidy the apps authorised on the account.** [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) lists every app and device signed in
+  to the Plex account and removes the old ones by ID, age, app or name. It never removes a Plex Media Server.
+- **Give another tool its own token.** [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) makes, lists and revokes tokens for a program such as a Plex MCP
+  server, so it does not need the saved login. Whether it is full access (`--rw`) or a shared user's (`--ro`)
+  has to be stated, and the output says what the token can do.
 - **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 that are not wanted.
 - **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.
+- **Look up an item, or compare several.** [`plextool info`](https://plextool.readthedocs.io/en/latest/commands/info.html) shows what Plex holds about a movie, show
+  or episode: the people, the tags and IDs, and the technical side (paths, video, audio and subtitle
+  tracks). Giving more than one item shows them side by side with the differences marked.
 - **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
@@ -79,18 +85,23 @@ Typical jobs:
 - **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 `--commit` is passed. plextool uses Plex's API and
-never edits the Plex database file. It signs in through a 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)).
+> [!IMPORTANT]
+> Everything that changes the server is a preview until `--commit` is passed. plextool uses Plex's API and
+> never edits the Plex database file. It signs in through a 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 the account, and wipe the saved login and keys. |
+| [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) | See who has access to the server, and invite, change and remove people: libraries, restrictions, downloads, invitations. Previews until `--commit`. |
+| [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) | List the apps and devices authorised on the Plex account, and sign out the ones no longer wanted, by ID or by age, app or name. Plex Media Servers are never removed. |
+| [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) | Make, list and revoke tokens for other tools (such as an MCP server) without sharing the saved login: a separate full-access token that can be revoked on its own, or a shared user's token. Also shows who has access to the server. |
 | [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on the 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 info`](https://plextool.readthedocs.io/en/latest/commands/info.html) | Everything Plex holds about one item: people, tags, playback, and every file, path, video, audio and subtitle track. Several items can be compared side by side. |
 | [`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. |
@@ -185,8 +196,8 @@ A fuller page for each command is on [Read the Docs](https://plextool.readthedoc
 
 ## 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
+plextool needs Python 3.10 or later, because plexapi 4.18 does. It is tested on
+Python 3.12. If something doesn't work on another version, please
 [open an issue](https://github.com/milkmansson/plextool/issues) with the Python
 version.
 

{plextool-3.1.0 → plextool-3.2.0}/README.md

@@ -3,16 +3,12 @@
 > [!WARNING]
 > Still in development/testing... please raise an issue if one is found!
 
-Command line tool for Plex library maintenance, built on
-[python-plexapi](https://python-plexapi.readthedocs.io/). It talks to the
-server through its API. No access is made to the Plex database file, which is
-too risky to edit by hand.
+Swiss army knife command line tool for Plex library maintenance. Built on [python-plexapi](https://python-plexapi.readthedocs.io/), which talks to the
+server through its API.  No accesses is made to 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:
+plextool is a CLI toolkit for looking after a Plex Media Server: fixing things Plex's web interface can't, giving CLI methods to things that would otherwise need many clicks through the web interface for, for server maintenance over SSH, and for finding and fixing problems in large libraries.  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 the database is rebuilt, duplicate
@@ -25,10 +21,20 @@ Typical jobs:
   $ plextool recent --recent 20 --release              # preview: put the 20 newest back to their release dates
   $ plextool recent --title "Some Show" --shift=-30d --commit
   ```
+- **Manage who has access.** [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) lists who can use the server, invites people, changes
+  what they can see and removes them, with a preview of exactly what would be granted or lost.
+- **Tidy the apps authorised on the account.** [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) lists every app and device signed in
+  to the Plex account and removes the old ones by ID, age, app or name. It never removes a Plex Media Server.
+- **Give another tool its own token.** [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) makes, lists and revokes tokens for a program such as a Plex MCP
+  server, so it does not need the saved login. Whether it is full access (`--rw`) or a shared user's (`--ro`)
+  has to be stated, and the output says what the token can do.
 - **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 that are not wanted.
 - **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.
+- **Look up an item, or compare several.** [`plextool info`](https://plextool.readthedocs.io/en/latest/commands/info.html) shows what Plex holds about a movie, show
+  or episode: the people, the tags and IDs, and the technical side (paths, video, audio and subtitle
+  tracks). Giving more than one item shows them side by side with the differences marked.
 - **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
@@ -45,18 +51,23 @@ Typical jobs:
 - **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 `--commit` is passed. plextool uses Plex's API and
-never edits the Plex database file. It signs in through a 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)).
+> [!IMPORTANT]
+> Everything that changes the server is a preview until `--commit` is passed. plextool uses Plex's API and
+> never edits the Plex database file. It signs in through a 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 the account, and wipe the saved login and keys. |
+| [`plextool users`](https://plextool.readthedocs.io/en/latest/commands/users.html) | See who has access to the server, and invite, change and remove people: libraries, restrictions, downloads, invitations. Previews until `--commit`. |
+| [`plextool devices`](https://plextool.readthedocs.io/en/latest/commands/devices.html) | List the apps and devices authorised on the Plex account, and sign out the ones no longer wanted, by ID or by age, app or name. Plex Media Servers are never removed. |
+| [`plextool token`](https://plextool.readthedocs.io/en/latest/commands/token.html) | Make, list and revoke tokens for other tools (such as an MCP server) without sharing the saved login: a separate full-access token that can be revoked on its own, or a shared user's token. Also shows who has access to the server. |
 | [`plextool server`](https://plextool.readthedocs.io/en/latest/commands/server.html) | Find servers on the 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 info`](https://plextool.readthedocs.io/en/latest/commands/info.html) | Everything Plex holds about one item: people, tags, playback, and every file, path, video, audio and subtitle track. Several items can be compared side by side. |
 | [`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. |
@@ -151,8 +162,8 @@ A fuller page for each command is on [Read the Docs](https://plextool.readthedoc
 
 ## 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
+plextool needs Python 3.10 or later, because plexapi 4.18 does. It is tested on
+Python 3.12. If something doesn't work on another version, please
 [open an issue](https://github.com/milkmansson/plextool/issues) with the Python
 version.
 

{plextool-3.1.0 → plextool-3.2.0}/plextool/__init__.py

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

{plextool-3.1.0 → plextool-3.2.0}/plextool/auth.py

@@ -88,12 +88,12 @@ def _require_jwt_support():
     return MyPlexJWTLogin
 
 
-def _headers(client_id: str) -> dict:
+def _headers(client_id: str, device_name: str | None = None) -> dict:
     return {
         "X-Plex-Client-Identifier": client_id,
         "X-Plex-Product": "plextool",
         "X-Plex-Version": __version__,
-        "X-Plex-Device-Name": f"plextool on {socket.gethostname()}",
+        "X-Plex-Device-Name": device_name or f"plextool on {socket.gethostname()}",
     }
 
 
@@ -191,22 +191,23 @@ KIND_BLURB = {
 }
 
 
-def show_link(url: str, kind: str) -> None:
+def show_link(url: str, kind: str, file=None) -> None:
     # The JWT sign-in is known to work with the trimmed link. The classic token sign-in is known to
     # work with the full link, so it gets that (and a bigger QR code).
     link = _short_link(url) if kind == "jwt" else url
-    print(paint(f"Signing in for {KIND_BLURB[kind]}.", "bold") + "\n")
-    print("Open this link in a browser and sign in to Plex:\n")
-    print(f"  {link}\n")
+    out = file or sys.stdout
+    print(paint(f"Signing in for {KIND_BLURB[kind]}.", "bold") + "\n", file=out)
+    print("Open this link in a browser and sign in to Plex:\n", file=out)
+    print(f"  {link}\n", file=out)
     try:
         import segno
     except ImportError:
-        print("(Install 'segno' to see a QR code here as well: pip install segno)\n")
+        print("(Install 'segno' to see a QR code here as well: pip install segno)\n", file=out)
     else:
-        if sys.stdout.isatty():
-            segno.make(link, error="l").terminal(compact=True)
-            print("Or scan the code above with your phone.\n")
-    print("Waiting for you to approve it...")
+        if out.isatty():
+            segno.make(link, error="l").terminal(compact=True, out=out)
+            print("Or scan the code above with your phone.\n", file=out)
+    print("Waiting for you to approve it...", file=out)
 
 
 def _new_client_id() -> str:
@@ -250,13 +251,18 @@ def login_jwt(timeout: int) -> None:
         print("Once you have chosen a server, 'plextool server test' shows whether it accepts a JWT.")
 
 
-def login_token(timeout: int, print_only: bool) -> None:
+def request_token(timeout: int, device_name: str | None = None, file=None) -> tuple[str, str]:
+    """Run the browser sign-in for a classic token; returns (token, device ID). Saves nothing.
+
+    The sign-in appears under Authorized Devices as `device_name` (default 'plextool on <host>').
+    The link and prompts go to `file` (default standard output).
+    """
     from plexapi.myplex import MyPlexPinLogin
     client_id = _new_client_id()
-    login = MyPlexPinLogin(headers=_headers(client_id), oauth=True)
+    login = MyPlexPinLogin(headers=_headers(client_id, device_name), oauth=True)
     try:
         login.run(timeout=timeout)
-        show_link(login.oauthUrl(), "token")
+        show_link(login.oauthUrl(), "token", file)
         approved = login.waitForLogin()
     except RequestException as e:
         raise PlexToolError(f"Could not reach plex.tv: {e}") from None
@@ -264,11 +270,16 @@ def login_token(timeout: int, print_only: bool) -> None:
         login.stop()
     if not approved:
         raise PlexToolError("Sign-in was not approved in time. Nothing was saved.")
+    return login.token, client_id
+
+
+def login_token(timeout: int, print_only: bool) -> None:
+    token, client_id = request_token(timeout)
     if print_only:
-        print(login.token)
+        print(token)
         return
     directory = config_dir()
-    save_state({"client_id": client_id, "kind": "token", "token": login.token})
+    save_state({"client_id": client_id, "kind": "token", "token": token})
     for name in KEY_FILES:  # a JWT login's keys are no use any more
         (directory / name).unlink(missing_ok=True)
     print(paint("\nSigned in with a classic token.", "green") + f" Saved to {directory}")
@@ -282,6 +293,8 @@ def login_token(timeout: int, print_only: bool) -> None:
 # ---------------------------------------------------------------------------
 
 PRODUCT = "plextool"
+NAMED_TOKEN_PREFIX = "plextool/"   # devices made by `plextool token new --rw --name X`
+OLD_NAMED_TOKEN_PREFIX = "plextool: "   # what early versions used; still recognised
 
 
 def account_devices(token: str, everything: bool = False) -> list:
@@ -305,8 +318,29 @@ def _short(device) -> str:
     return (device.clientIdentifier or "")[:8]
 
 
+def is_named_token(device) -> bool:
+    """True for a device made by 'plextool token new --rw', which belongs to another tool."""
+    return (device.name or "").startswith((NAMED_TOKEN_PREFIX, OLD_NAMED_TOKEN_PREFIX))
+
+
+def is_server(device) -> bool:
+    """True for a Plex Media Server's own entry, which plextool never removes."""
+    provides = [p.strip() for p in (getattr(device, "provides", None) or "").split(",")]
+    return (device.product or "").lower() == "plex media server" or "server" in provides
+
+
+def token_label(device_name: str) -> str:
+    """The name a token was given, without plextool's prefix."""
+    for prefix in (NAMED_TOKEN_PREFIX, OLD_NAMED_TOKEN_PREFIX):
+        if device_name.startswith(prefix):
+            return device_name[len(prefix):]
+    return device_name
+
+
 def describe_device(device, current_id: str | None) -> str:
     mark = paint("  (this login)", "green") if current_id and device.clientIdentifier == current_id else ""
+    if is_named_token(device):
+        mark = paint("  (token for another tool; see 'plextool token list')", "yellow")
     return (f"  {_short(device):<10}{device.name or '?':<40}created {_when(device.createdAt)}   "
             f"last seen {_when(device.lastSeenAt)}{mark}")
 
@@ -326,15 +360,28 @@ def list_devices(args: argparse.Namespace) -> None:
 
 
 def revoke_devices(args: argparse.Namespace) -> None:
-    if not (args.ids or args.others or args.this):
-        raise PlexToolError("Say what to remove: --others, --this, or one or more device IDs "
-                            "from 'plextool auth devices'.")
+    if not (args.ids or args.others or args.this or args.unused_for is not None):
+        raise PlexToolError("Say what to remove: --others, --this, --unused-for DAYS, or one or more device "
+                            "IDs from 'plextool auth devices'.")
+    if args.unused_for is not None and args.unused_for < 1:
+        raise PlexToolError("--unused-for must be at least 1 day.")
     token, _ = resolve_token(args)
-    devices = account_devices(token)
+    everything = account_devices(token, everything=True)
+    devices = [d for d in everything if (d.product or "").lower() == PRODUCT]
     current = load_state().get("client_id")
     chosen = {}
     if args.others:
-        chosen.update({d.clientIdentifier: d for d in devices if d.clientIdentifier != current})
+        kept = [d for d in devices if is_named_token(d)]
+        if kept:
+            print(f"Keeping {plural(len(kept), 'token')} made for other tools with 'plextool token'. "
+                  "'plextool token revoke NAME' removes those.")
+        chosen.update({d.clientIdentifier: d for d in devices
+                       if d.clientIdentifier != current and not is_named_token(d)})
+    if args.unused_for is not None:
+        cutoff = datetime.now() - timedelta(days=args.unused_for)
+        chosen.update({d.clientIdentifier: d for d in devices
+                       if d.clientIdentifier != current and not is_named_token(d)
+                       and (d.lastSeenAt is None or d.lastSeenAt < cutoff)})
     if args.this:
         if not current:
             raise PlexToolError("No saved login, so there is no device of this computer to remove.")
@@ -342,8 +389,14 @@ def revoke_devices(args: argparse.Namespace) -> None:
     for prefix in args.ids:
         matches = [d for d in devices if (d.clientIdentifier or "").startswith(prefix)]
         if not matches:
-            raise PlexToolError(f"No plextool device starts with '{prefix}'. "
-                                "'plextool auth devices' lists them.")
+            other = [d for d in everything if (d.clientIdentifier or "").startswith(prefix)]
+            if other:
+                raise PlexToolError(
+                    f"'{prefix}' is '{other[0].name or '?'}' ({other[0].product or 'unknown app'}), which plextool "
+                    f"did not make, so 'auth revoke' will not remove it. "
+                    f"'plextool devices remove {prefix}' removes other apps.")
+            raise PlexToolError(f"No device on the account starts with '{prefix}'. "
+                                "'plextool token list' shows them all.")
         if len(matches) > 1:
             raise PlexToolError(f"'{prefix}' matches {len(matches)} devices; give more of the ID.")
         chosen[matches[0].clientIdentifier] = matches[0]
@@ -475,10 +528,11 @@ def add_parser(subparsers) -> None:
     revoke = add_command(
         sub, "revoke", "remove plextool sign-ins from your Plex account",
         "Remove plextool devices from your Plex account so plex.tv rejects their tokens. Only "
-        "plextool's own entries can be removed; other Plex apps and devices are never touched. "
+        "plextool's own entries can be removed; other Plex apps and devices are removed with 'plextool devices remove'. "
         "Nothing is removed unless you pass --commit.",
         ["plextool auth revoke --others",
          "plextool auth revoke --others --commit",
+         "plextool auth revoke --unused-for 7 --commit",
          "plextool auth revoke 3895d339 --commit",
          "plextool auth revoke --this --commit"])
     add_token_args(revoke)
@@ -488,6 +542,9 @@ def add_parser(subparsers) -> None:
                         help="every plextool device except the one this login uses")
     revoke.add_argument("--this", action="store_true",
                         help="the device this login uses (do this before 'auth wipe')")
+    revoke.add_argument("--unused-for", type=int, metavar="DAYS",
+                        help="every plextool sign-in not used in the last DAYS days (never this login, "
+                             "and never tokens made with 'plextool token')")
     revoke.add_argument("--commit", action="store_true", help="actually remove them")
 
     wipe_parser = add_command(

{plextool-3.1.0 → plextool-3.2.0}/plextool/cli.py

@@ -10,7 +10,9 @@ from . import (
     __version__,
     audit,
     auth,
+    devices,
     dupes,
+    info,
     playlists,
     recent,
     resume,
@@ -19,6 +21,8 @@ from . import (
     stale,
     status,
     subs,
+    tokens,
+    users,
     watched,
 )
 from .common import PlexToolError, enable_verbose, format_duration
@@ -38,7 +42,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("-v", "--verbose", dest="verbose_first", action="store_true",
                         help="print each request sent to Plex, with its reply, on stderr (also accepted after the command)")
     subparsers = parser.add_subparsers(dest="command", metavar="command")
-    for module in (auth, server, status, scan, recent, dupes, stale, audit, watched, resume, playlists, subs):
+    for module in (auth, tokens, devices, users, server, status, scan, recent, dupes, stale, info, audit, watched, resume, playlists, subs):
         module.add_parser(subparsers)
     return parser
 

{plextool-3.1.0 → plextool-3.2.0}/plextool/common.py

@@ -24,6 +24,7 @@ from plexapi.server import PlexServer
 from requests.exceptions import RequestException
 
 DEFAULT_URL = "http://localhost:32400"
+DEFAULT_TIMEOUT = 10   # seconds to wait for the default address, which may not be a Plex server at all
 TOKEN_ENV = "PLEX_TOKEN"
 TOKEN_CMD_ENV = "PLEX_TOKEN_CMD"
 SIGN_IN_AGAIN = ("It may have been revoked or have expired. "
@@ -203,11 +204,12 @@ class Working:
 
 
 @contextmanager
-def working(label: str):
+def working(label: str, first: float | None = None):
     """Tell the user on stderr, now and then, that a slow step is still going.
 
     Quick steps print nothing. After FIRST_NOTICE seconds a line like
     'still reading TV Shows... 10s' appears, then another every NOTICE_EVERY seconds.
+    `first` replaces FIRST_NOTICE for steps that should speak up sooner.
     stderr is used so --json output on stdout stays clean.
     """
     state = Working()
@@ -215,7 +217,7 @@ def working(label: str):
     started = time.monotonic()
 
     def notify():
-        wait = FIRST_NOTICE
+        wait = FIRST_NOTICE if first is None else first
         while not done.wait(wait):
             detail = f" ({state.detail})" if state.detail else ""
             print(f"  still {label}... {int(time.monotonic() - started)}s{detail}", file=sys.stderr, flush=True)
@@ -347,6 +349,20 @@ def _find_token(args: argparse.Namespace) -> tuple[str, str]:
                         f"or set ${TOKEN_ENV}.")
 
 
+def short_reason(error: Exception) -> str:
+    """A one-line reason for a failed connection, without requests' long wording."""
+    text = str(error)
+    if isinstance(error, requests.exceptions.Timeout) or "timed out" in text:
+        return "no answer (timed out)"
+    if "Connection refused" in text:
+        return "connection refused (nothing is listening there)"
+    if "Name or service not known" in text or "Temporary failure in name resolution" in text:
+        return "the name could not be resolved"
+    if "No route to host" in text or "Network is unreachable" in text:
+        return "no route to the host"
+    return text if len(text) <= 150 else text[:147] + "..."
+
+
 def connect(args: argparse.Namespace) -> PlexServer:
     """Connect to the server named in args, with friendly errors.
 
@@ -355,18 +371,26 @@ def connect(args: argparse.Namespace) -> PlexServer:
     """
     args.token, source = resolve_token(args)
     url = args.base_url or os.environ.get(URL_ENV)
+    chosen = bool(url)
     try:
         if url:
             plex = PlexServer(url, args.token)
         else:
             from . import server  # imported here because server itself uses this module
             saved = server.load_saved()
-            plex = server.connect_saved(saved, args.token) if saved else PlexServer(DEFAULT_URL, args.token)
+            chosen = bool(saved)
+            if saved:
+                plex = server.connect_saved(saved, args.token)
+            else:
+                with working(f"trying {DEFAULT_URL}, as no server is chosen (see 'plextool server use')", first=3):
+                    plex = PlexServer(DEFAULT_URL, args.token, timeout=DEFAULT_TIMEOUT)
     except Unauthorized:
         hint = SIGN_IN_AGAIN if source == "saved login" else "Check that token, or use 'plextool auth login'."
         raise PlexToolError(f"The Plex server rejected the token from {source} (401). {hint}") from None
     except RequestException as e:
-        raise PlexToolError(f"Could not reach {url or DEFAULT_URL}: {e}") from None
+        hint = "" if chosen else (" No server is chosen, so this default was tried. "
+                                  "Run 'plextool server find', then 'plextool server use'.")
+        raise PlexToolError(f"Could not reach {url or DEFAULT_URL}: {short_reason(e)}.{hint}") from None
     args.base_url = plex._baseurl
     return plex
 
@@ -379,14 +403,12 @@ def plex_account(args: argparse.Namespace) -> MyPlexAccount:
         raise PlexToolError(f"Could not reach plex.tv: {e}") from None
 
 
-def user_server(args: argparse.Namespace, admin: PlexServer, name: str | None) -> PlexServer:
-    """Open the server as the named user (the owner if name is None or is the owner)."""
-    if not name:
-        return admin
+def user_access_token(args: argparse.Namespace, admin: PlexServer, name: str) -> str | None:
+    """The named user's access token for this server, or None if `name` is the owner."""
     account = plex_account(args)
     own_names = {n.lower() for n in (account.username, account.email, account.title) if n}
     if name.lower() in own_names:
-        return admin
+        return None
     try:
         user = account.user(name)
     except NotFound:
@@ -394,9 +416,19 @@ def user_server(args: argparse.Namespace, admin: PlexServer, name: str | None) -
     token = user.get_token(admin.machineIdentifier)
     if token:
         _SECRETS.add(token)
-    if not token:
+    else:
         raise PlexToolError(
             f"Could not get an access token for '{name}'. Is this server shared with them?")
+    return token
+
+
+def user_server(args: argparse.Namespace, admin: PlexServer, name: str | None) -> PlexServer:
+    """Open the server as the named user (the owner if name is None or is the owner)."""
+    if not name:
+        return admin
+    token = user_access_token(args, admin, name)
+    if token is None:
+        return admin
     try:
         return PlexServer(args.base_url, token)
     except RequestException as e: