emby-cli 0.5.2__tar.gz → 0.5.4__tar.gz

emby_cli-0.5.4/AGENTS.md

@@ -0,0 +1,295 @@
+# AGENTS.md — emby-cli
+
+Guide for humans and AI agents contributing to **[emby-cli](https://github.com/soukron/emby-cli)**.
+Read this **before** changing application code, tests, CI, or release workflow.
+
+End-user documentation lives in [`README.md`](README.md). This file is for **maintainers and contributors**.
+
+---
+
+## What this project is
+
+CLI to **search**, **inspect** (`show`), **play**, and **download/backup** original media files from an **Emby** server over its REST API (typically HTTP port `8096`). No SSH, no shared mounts, no rsync.
+
+| | |
+|--|--|
+| Package name | `emby-cli` on [PyPI](https://pypi.org/project/emby-cli/) |
+| Python | ≥ 3.9 (CI: 3.9 / 3.11 / 3.12) |
+| Build / version | hatchling + **hatch-vcs** (version from git tags `v*`) |
+| License | CC-BY-NC-4.0 |
+| Entrypoint | `emby-cli` → `emby_cli.cli:main` |
+
+---
+
+## Repository layout
+
+```
+.
+├── pyproject.toml          # package metadata, ruff, pytest, hatch
+├── README.md               # public user docs (keep host-agnostic)
+├── CHANGELOG.md            # user-facing release notes
+├── LICENSE
+├── .env.example            # env var names only (no secrets)
+├── AGENTS.md               # this file
+├── src/emby_cli/           # application package
+│   ├── cli.py              # argparse + main() + pre-auth validation
+│   ├── client.py           # EmbyClient: HTTP, auth, browse, download/HLS
+│   ├── auth_cache.py       # auth.json contexts (kubeconfig-style)
+│   ├── credentials.py      # resolve server / user / password
+│   ├── mode_args.py        # --item / --library / QUERY helpers
+│   ├── resolve.py          # title lines, pick_best, choice tables
+│   ├── download_ops.py     # download loop, skip, library matching
+│   ├── output.py           # stdout/stderr messages + Stats / exit codes
+│   ├── util.py             # paths, sizes, skip, ffmpeg remux
+│   ├── constants.py        # retries, types, field lists, CLIENT_NAME
+│   ├── types.py            # TypedDict shapes for Emby JSON (documentation)
+│   ├── commands/           # one module per subcommand
+│   └── …
+├── tests/                  # pytest; no real Emby server
+└── .github/workflows/
+    ├── ci.yml              # ruff + pytest matrix
+    └── publish.yml         # tag v* → PyPI (Trusted Publisher)
+```
+
+`src/emby_cli/_version.py` is generated by hatch-vcs (gitignored). Do not edit it by hand.
+
+---
+
+## Local development
+
+```bash
+git clone https://github.com/soukron/emby-cli.git
+cd emby-cli
+python3 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+cp .env.example .env               # optional; fill EMBY_* for manual smoke tests
+```
+
+| Command | Purpose |
+|---------|---------|
+| `pytest` / `pytest -qvv` | Run the suite |
+| `ruff check .` | Lint (also runs in CI) |
+| `python -m build` | Wheel + sdist |
+| `twine check dist/*` | Metadata sanity |
+| `emby-cli …` / `python -m emby_cli …` | Run the CLI |
+
+Editable install uses hatch `dev-mode-dirs = ["src"]`. Changes under `src/emby_cli/` are picked up on the next process start. Pytest sets `pythonpath = ["src"]` so tests always import the working tree.
+
+Re-run `pip install -e ".[dev]"` when dependencies or `[project.scripts]` change.
+
+### Environment variables
+
+The CLI reads **`os.environ` only** (it does not auto-load `.env`; export vars or `set -a && source .env && set +a`).
+
+| Variable | Role |
+|----------|------|
+| `EMBY_SERVER` | Base URL (active context after `login` / `config use-server` if unset) |
+| `EMBY_API_KEY` | API key (alternative to username/password) |
+| `EMBY_USERNAME` / `EMBY_PASSWORD` | Name-based auth |
+| `EMBY_OUTPUT` | Download destination (default `./downloads`) |
+| `EMBY_ITEM_ID` | Default `--id` for `download --item` / `play` |
+| `EMBY_METHOD` | `download` \| `stream` \| `hls` |
+| `EMBY_PLAYER` | External player command for `play` |
+| `EMBY_CACHE_DIR` | Credential store dir (default `~/.cache/emby-cli`; file `auth.json`) |
+| `EMBY_NO_AUTH_CACHE` | `1` = do not read/write session cache |
+
+Never commit `.env`, tokens, passwords, or stream URLs that embed credentials.
+
+---
+
+## Architecture (where logic lives)
+
+```text
+cli.main
+  ├─ validate_*_args          # reject bad selectors BEFORE auth
+  ├─ open EmbyClient + ensure session
+  └─ commands.<cmd>
+        ├─ validate_*_args    # intentional duplicate (defense in depth)
+        └─ EmbyClient / resolve / download_ops / output
+```
+
+| Concern | Primary modules |
+|---------|-----------------|
+| HTTP, retries, auth, browse, binary/HLS download | `client.py` |
+| Session store on disk | `auth_cache.py` |
+| Resolving server/user/password from flags/env/TTY/cache | `credentials.py` |
+| `--item` / `--library` / embedded QUERY | `mode_args.py` + command modules |
+| Title-line resolution (`Movie (2010)`, `Show S01E02`) | `resolve.py` |
+| Download orchestration, skip, library match | `download_ops.py` |
+| User-visible messages and exit codes | `output.py` |
+| New flag or subcommand | `cli.py` + `commands/…` + `help.COMMAND_SUMMARIES` |
+
+`client.py` is large on purpose today (HTTP + Emby ops + download). Prefer small, tested helpers over a big rewrite unless a dedicated refactor is planned. See historical notes in maintainer discussions; do not split every endpoint into its own file without need.
+
+---
+
+## Auth and session cache (important)
+
+- **API key** (`-k` / `EMBY_API_KEY`): never written to disk.
+- **Username/password**: single store `{EMBY_CACHE_DIR}/auth.json` with `contexts[]` + `current_context` (kubeconfig-style). **Password is never stored.** Legacy `*.cache` files migrate automatically.
+- `login` — authenticate, upsert context, activate it.
+- `logout` — `POST /Sessions/Logout` when possible, then remove context.
+- `config` — `current-server`, `get-servers`, `use-server`, `view` (tokens redacted).
+- Other commands: no `--server` → active context; cache hit → reuse token; miss + credentials → transparent login; **HTTP 401** with password available → invalidate cache and re-authenticate **once per top-level request** (no infinite reauth loop).
+- If 401 cannot be recovered (no password, or re-login rejected): raise `AuthenticationError`, clear the stale cache entry, and let `main` print a short stderr message (no traceback).
+- Invalid selectors for `search` / `download` / `play` / `show` are rejected **before** opening a client.
+
+### Intentional duplicate validation
+
+`main()` calls `validate_*_args`, and each `cmd_*` validates again. **Do not merge these.** Pre-auth rejection in `main` plus a safety net if a command is invoked directly.
+
+---
+
+## CLI contracts (do not break casually)
+
+Observable behavior for users and scripts: flags, stdout/stderr split, exit codes, and message prefixes. Prefer CHANGELOG entries when any of these change.
+
+### Modes `--item` / `--library`
+
+Shared pattern (`mode_args.py`) for **`search`** and **`download`**:
+
+| Flag | Behavior |
+|------|----------|
+| `--item [QUERY]` | Media mode; QUERY optional on the same flag. Alias: `--media-item` |
+| `--library [QUERY]` | Library mode; QUERY optional on the same flag |
+| `--id` | Emby ID (alternative to QUERY; CSV allowed where documented) |
+| `--search` | Alternative QUERY (do not combine with QUERY embedded in `--item`/`--library`) |
+
+`nargs='?'` + `const=""` so `--item --all` / `--library --id X` do not swallow the next flag as QUERY.
+
+`show` is different: `--item`/`--library` plus **mandatory `--id`** (no QUERY / `--search`).
+
+### Output streams
+
+| Stream | Content |
+|--------|---------|
+| **stdout** | Tables, progress, `download (method):`, `skip:`, `Done. ok=…`, disambiguation candidate tables |
+| **stderr** | `error: …`, validation failures, fatal messages |
+
+`print_error()` must write to stderr. Scripts should be able to pipe stdout as data.
+
+### List sorting
+
+Any user-facing list/table of items or libraries: sort by **Id descending**, then **Name** alphabetically (case-insensitive). Use `resolve.sort_for_display`.
+
+### Title resolution (`play` / `download --item` / `--from-file`)
+
+Strict by default: year with no match, multiple series, or multiple versions → fail with a table + hint.
+
+`--pick-best-item`: prefer ≤1080p via `pick_best_item` (non-4K preferred). Season-only `Sxx` without `Exx`: download may fetch the whole season (`allow_season_all`); play refuses. Library QUERY uses substring + disambiguation (`match_libraries`).
+
+### Download methods (`-m` / `EMBY_METHOD`)
+
+| Method | Behavior |
+|--------|----------|
+| `download` | `GET /Items/{id}/Download` — best for “original” backup |
+| `stream` | PlaybackInfo + `original.*` (Emby Web style) |
+| `hls` | TS segments remuxed to `.mkv` via bundled `static-ffmpeg` — **not** bit-identical |
+
+Identity headers / User-Agent: `emby-cli/<version>` (`constants.CLIENT_NAME`). `EMBY_SERVER` may include or omit `/emby` (normalized).
+
+### Exit codes
+
+- `download`: non-zero if `error > 0`; with `--from-file` also if `not_found > 0`.
+- `--dry-run` still runs the path; planned items count as `ok` in the Done summary.
+
+---
+
+## Testing rules
+
+1. **No real Emby server** in automated tests. Mock `session.request` / `session.get` / client methods.
+2. Patch `time.sleep` in retry tests; assert attempt counts and backoff values explicitly.
+3. Prefer tests that would **fail if production logic is deleted** (mutation-minded): assert file contents, headers (including new AccessToken after reauth), `clear_auth_cache` calls, stderr vs stdout.
+4. Do not mock away the unit under test (e.g. do not mock `authenticate` when testing reauth end-to-end).
+5. After behavior changes affecting streams or exit codes, update tests to use `capsys.readouterr().err` / `.out` as appropriate.
+
+```bash
+pytest -qvv
+ruff check .
+```
+
+CI runs both on every push/PR.
+
+---
+
+## Coding conventions
+
+- Keep changes **scoped**: one concern per PR/commit when practical.
+- Do not invent a DI framework, async rewrite, or swap `requests` without a strong reason.
+- Do not remove the README **Responsible use** section.
+- Do not put private hostnames, internal paths, or deployment layout into `README.md`.
+- Never log API keys, passwords, or authenticated DirectStream URLs.
+- HLS is not a bit-exact backup; document that if you change download UX.
+- Prefer extending existing helpers (`_retry_response`, `download_items`, `sort_for_display`, …) over copying patterns.
+
+### Things that look redundant but are intentional
+
+| Pattern | Why |
+|---------|-----|
+| Double `validate_*_args` | Pre-auth gate + direct-call safety |
+| Thin `search_items()` wrapper | Convenient API; keep unless clearly unused |
+| Legacy auth-cache aliases (if still present) | Migrate carefully; do not break imports without CHANGELOG |
+
+---
+
+## Git and release (PyPI only)
+
+Version comes from **git tags** `vX.Y.Z` via hatch-vcs. Do not hardcode the version in `pyproject.toml`.
+
+**Do not create GitHub Releases** for this project. Distribution is **PyPI only**. Tag + `publish.yml` is enough.
+
+### Release checklist
+
+1. Move `CHANGELOG.md` `## Unreleased` → `## X.Y.Z` (user-visible notes).
+2. Ensure the working tree is clean.
+3. Tag and push:
+
+   ```bash
+   git tag -a "vX.Y.Z" -m "Release vX.Y.Z"
+   git push origin HEAD
+   git push origin "vX.Y.Z"
+   ```
+
+4. Watch `.github/workflows/publish.yml` (GitHub Environment `pypi` + Trusted Publisher).
+5. If CI already uploaded the wheel and a manual `twine upload` fails with **400 file-name-reuse**, upload **only the `.tar.gz`**.
+
+Maintainers with a local wrapper Makefile may use an equivalent `make release VERSION=X.Y.Z`; the git operations above are the source of truth inside this repository.
+
+---
+
+## Common mistakes
+
+1. Committing secrets or a filled `.env`.
+2. Putting deployment/host details in the public README.
+3. Removing *Responsible use*.
+4. Editing `_version.py` or the version field by hand.
+5. Unifying the duplicate validators “for cleanliness”.
+6. Assuming HLS equals an original file copy.
+7. Running tests against a real Emby and calling that CI.
+8. Creating a GitHub Release when only a PyPI tag was intended.
+9. Changing stdout/stderr or exit codes without updating tests and CHANGELOG.
+
+---
+
+## Typical tasks → files
+
+| Task | Start here |
+|------|------------|
+| Auth, retry, browse, download/HLS | `client.py` |
+| Item/library QUERY modes | `mode_args.py`, `cli.py`, `commands/{search,show,download,play}.py` |
+| New subcommand or flag | `cli.py`, `commands/…`, `help.COMMAND_SUMMARIES` |
+| `show` detail / library recents | `commands/show.py`, `constants.SHOW_*` |
+| Title disambiguation / pick-best | `resolve.py` |
+| Skip / dry-run / library download loop | `download_ops.py` |
+| Message text / exit codes | `output.py` |
+| Emby response typing | `types.py` (TypedDict; apply gradually) |
+| User docs | `README.md` |
+| Release notes | `CHANGELOG.md` |
+
+---
+
+## Related docs
+
+- Users: [`README.md`](README.md), [`CHANGELOG.md`](CHANGELOG.md)
+- License: [`LICENSE`](LICENSE) (CC-BY-NC-4.0)

{emby_cli-0.5.2 → emby_cli-0.5.4}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.4
+
+Fixed:
+
+- macOS: suppress urllib3 `NotOpenSSLWarning` (system Python + LibreSSL) by filtering before `requests` is imported — the previous filter in `cli.py` ran too late because `__init__.py` already pulled in urllib3.
+
+## 0.5.3
+
+Fixed:
+
+- Expired/revoked sessions: print a clear `error:` on stderr (suggest `emby-cli login`) instead of an `HTTPError` traceback; drop the stale AccessToken from the local cache.
+
+Docs:
+
+- Public `AGENTS.md` for contributors (layout, auth, CLI contracts, tests, release).
+
 ## 0.5.2
 
 Changed:

{emby_cli-0.5.2 → emby_cli-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: emby-cli
-Version: 0.5.2
+Version: 0.5.4
 Summary: CLI to list, search, play, and download/backup original media from an Emby server via its REST API.
 Project-URL: Homepage, https://github.com/soukron/emby-cli
 Project-URL: Repository, https://github.com/soukron/emby-cli
@@ -63,11 +63,11 @@ Your session is saved locally. Later commands reuse it, so you usually do not ne
 emby-cli info
 ```
 
-**3. Search and download:**
+**3. Search and play:**
 
 ```bash
 emby-cli search --item "matrix"
-emby-cli download --item "matrix (1999)" --pick-best-item
+emby-cli play --item "matrix (1999)" --pick-best-item
 ```
 
 Use `emby-cli help` for the command list, and `emby-cli <command> -h` for options.
@@ -222,10 +222,11 @@ Flags override environment variables. Optional template: `.env.example` (export
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 pytest -q
+ruff check .
 python -m build && twine check dist/*
 ```
 
-Releases: tag `vX.Y.Z` and push. CI publishes to PyPI via Trusted Publisher.
+Architecture, CLI contracts, testing rules, and release process: see **[AGENTS.md](AGENTS.md)** (for humans and AI agents). Releases: tag `vX.Y.Z` and push — CI publishes to PyPI only (no GitHub Releases).
 
 ---
 

{emby_cli-0.5.2 → emby_cli-0.5.4}/README.md

@@ -28,11 +28,11 @@ Your session is saved locally. Later commands reuse it, so you usually do not ne
 emby-cli info
 ```
 
-**3. Search and download:**
+**3. Search and play:**
 
 ```bash
 emby-cli search --item "matrix"
-emby-cli download --item "matrix (1999)" --pick-best-item
+emby-cli play --item "matrix (1999)" --pick-best-item
 ```
 
 Use `emby-cli help` for the command list, and `emby-cli <command> -h` for options.
@@ -187,10 +187,11 @@ Flags override environment variables. Optional template: `.env.example` (export
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 pytest -q
+ruff check .
 python -m build && twine check dist/*
 ```
 
-Releases: tag `vX.Y.Z` and push. CI publishes to PyPI via Trusted Publisher.
+Architecture, CLI contracts, testing rules, and release process: see **[AGENTS.md](AGENTS.md)** (for humans and AI agents). Releases: tag `vX.Y.Z` and push — CI publishes to PyPI only (no GitHub Releases).
 
 ---
 

{emby_cli-0.5.2 → emby_cli-0.5.4}/pyproject.toml

@@ -76,4 +76,7 @@ target-version = "py39"
 select = ["E4", "E7", "E9", "F", "I", "B", "UP"]
 
 [tool.ruff.lint.per-file-ignores]
-"src/emby_cli/cli.py" = ["E402"]  # warnings.filterwarnings antes de import requests (intencional)
+# warnings.filterwarnings before requests/urllib3 (macOS LibreSSL NotOpenSSLWarning)
+"src/emby_cli/__init__.py" = ["E402"]
+"src/emby_cli/cli.py" = ["E402"]
+"src/emby_cli/client.py" = ["E402"]

emby_cli-0.5.4/src/emby_cli/__init__.py

@@ -0,0 +1,14 @@
+"""emby-cli — backup and stream media from an Emby server."""
+
+from __future__ import annotations
+
+import warnings
+
+# macOS system Python uses LibreSSL; urllib3 v2 only warns (TLS still works).
+# Must run before any import that pulls in requests/urllib3 (see client.py).
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
+
+from emby_cli.client import EmbyClient
+from emby_cli.version import get_version
+
+__all__ = ["EmbyClient", "get_version"]

{emby_cli-0.5.2 → emby_cli-0.5.4}/src/emby_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.2'
-__version_tuple__ = version_tuple = (0, 5, 2)
+__version__ = version = '0.5.4'
+__version_tuple__ = version_tuple = (0, 5, 4)
 
 __commit_id__ = commit_id = None

{emby_cli-0.5.2 → emby_cli-0.5.4}/src/emby_cli/cli.py

@@ -8,11 +8,12 @@ import sys
 import warnings
 
 # macOS system Python ships LibreSSL; urllib3 v2 only warns, TLS still works.
+# Also set in __init__.py / client.py — package import can load urllib3 first.
 warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
 
 import requests
 
-from emby_cli.client import EmbyClient
+from emby_cli.client import AuthenticationError, EmbyClient
 from emby_cli.commands.config import cmd_config
 from emby_cli.commands.download import cmd_download, validate_download_args
 from emby_cli.commands.help import COMMAND_SUMMARIES, cmd_help
@@ -291,7 +292,18 @@ def _open_client(args: argparse.Namespace) -> EmbyClient:
             file=sys.stderr,
         )
         sys.exit(1)
+    except AuthenticationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
     except requests.HTTPError as exc:
+        resp = getattr(exc, "response", None)
+        if resp is not None and resp.status_code in (401, 403):
+            print(f"error: {exc}", file=sys.stderr)
+            print(
+                "Run `emby-cli login` (or pass a valid --api-key) and try again.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
         print(f"Authentication failed: {exc}", file=sys.stderr)
         sys.exit(1)
     return client
@@ -349,7 +361,11 @@ def main() -> None:
         "play": cmd_play,
         "show": cmd_show,
     }
-    commands[args.command](client, args)
+    try:
+        commands[args.command](client, args)
+    except AuthenticationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":

{emby_cli-0.5.2 → emby_cli-0.5.4}/src/emby_cli/client.py

@@ -5,10 +5,14 @@ from __future__ import annotations
 import hashlib
 import shutil
 import time
+import warnings
 from pathlib import Path
 from typing import Callable
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
+# Before requests/urllib3 (macOS LibreSSL → NotOpenSSLWarning).
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
+
 import m3u8
 import requests
 from tqdm import tqdm
@@ -35,6 +39,16 @@ from emby_cli.version import get_version
 _DEVICE_ID = hashlib.md5(CLIENT_NAME.encode()).hexdigest()
 _AUTH_PATH = "/Users/AuthenticateByName"
 
+_AUTH_EXPIRED_MSG = (
+    "Session expired or credentials were rejected by the server. "
+    "Run `emby-cli login` (or pass a valid --api-key) and try again."
+)
+
+
+class AuthenticationError(RuntimeError):
+    """AccessToken / credentials no longer accepted (HTTP 401 on Emby)."""
+
+
 
 class _RetryImmediately(Exception):
     """Internal signal for a retry that does not need backoff."""
@@ -185,19 +199,30 @@ class EmbyClient:
             reauth_attempted = True
             return self._try_reauthenticate()
 
-        return _retry_response(
-            request,
-            max_attempts=max_attempts,
-            connection_message=lambda attempt, total, exc: (
-                f"  Connection error (attempt {attempt}/{total}), retrying in "
-                f"{RETRY_BACKOFF_BASE * (2 ** (attempt - 1))}s: {exc}"
-            ),
-            server_message=lambda status, attempt, total: (
-                f"  Server error {status} (attempt {attempt}/{total}), retrying in "
-                f"{RETRY_BACKOFF_BASE * (2 ** (attempt - 1))}s"
-            ),
-            retry_http_error=retry_after_reauth,
-        )
+        try:
+            return _retry_response(
+                request,
+                max_attempts=max_attempts,
+                connection_message=lambda attempt, total, exc: (
+                    f"  Connection error (attempt {attempt}/{total}), retrying in "
+                    f"{RETRY_BACKOFF_BASE * (2 ** (attempt - 1))}s: {exc}"
+                ),
+                server_message=lambda status, attempt, total: (
+                    f"  Server error {status} (attempt {attempt}/{total}), retrying in "
+                    f"{RETRY_BACKOFF_BASE * (2 ** (attempt - 1))}s"
+                ),
+                retry_http_error=retry_after_reauth,
+            )
+        except requests.HTTPError as exc:
+            resp = getattr(exc, "response", None)
+            if (
+                resp is not None
+                and resp.status_code == 401
+                and path != _AUTH_PATH
+            ):
+                self._discard_rejected_session()
+                raise AuthenticationError(_AUTH_EXPIRED_MSG) from exc
+            raise
 
     def _get(
         self,
@@ -330,11 +355,24 @@ class EmbyClient:
         self.access_token = self.api_key
         self.user_id = None
 
+    def _discard_rejected_session(self) -> None:
+        """Drop a rejected AccessToken from memory and disk (best effort)."""
+        if self.api_key and self.access_token == self.api_key:
+            # API-key auth: nothing useful to clear from the user cache.
+            return
+        self._invalidate_cached_session()
+
     def _try_reauthenticate(self) -> bool:
         if self._username is None or self._password is None:
             return False
         self._invalidate_cached_session()
-        self.authenticate(self._username, self._password)
+        try:
+            self.authenticate(self._username, self._password)
+        except requests.HTTPError as exc:
+            resp = getattr(exc, "response", None)
+            if resp is not None and resp.status_code in (401, 403):
+                return False
+            raise
         return True
 
     def logout_session(self) -> None:

emby_cli-0.5.4/tests/test_auth_expired.py

@@ -0,0 +1,71 @@
+"""UX when a cached AccessToken is rejected (401)."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from emby_cli.auth_cache import AuthCacheEntry, load_auth_cache, save_auth_cache
+from emby_cli.cli import main
+from emby_cli.client import AuthenticationError, EmbyClient
+
+
+def _resp(status_code):
+    r = MagicMock()
+    r.status_code = status_code
+    if status_code >= 400:
+        r.raise_for_status.side_effect = requests.HTTPError(response=r)
+    else:
+        r.raise_for_status.return_value = None
+    return r
+
+
+def test_stale_cache_401_raises_auth_error_and_clears_store(tmp_path, monkeypatch):
+    monkeypatch.setenv("EMBY_CACHE_DIR", str(tmp_path))
+    save_auth_cache(
+        AuthCacheEntry.create("http://host:8096", "alice", "stale-tok", "uid-1")
+    )
+    client = EmbyClient("http://host:8096")
+    client.ensure_user_session("alice", None)  # restore cache; no password for reauth
+    assert client.access_token == "stale-tok"
+
+    with patch.object(client.session, "request", return_value=_resp(401)):
+        with pytest.raises(AuthenticationError, match="emby-cli login"):
+            client._get("/Users/uid-1/Views")
+
+    assert load_auth_cache(server_url="http://host:8096", username="alice") is None
+    assert client.access_token is None
+
+
+def test_main_prints_friendly_message_on_expired_session(capsys, monkeypatch, tmp_path):
+    monkeypatch.setenv("EMBY_CACHE_DIR", str(tmp_path))
+    save_auth_cache(
+        AuthCacheEntry.create("http://host:8096", "alice", "stale-tok", "uid-1")
+    )
+    monkeypatch.setattr(
+        "sys.argv",
+        ["emby-cli", "--server", "http://host:8096", "search", "--library", "--all"],
+    )
+
+    client = EmbyClient("http://host:8096", use_auth_cache=True)
+    client.access_token = "stale-tok"
+    client.user_id = "uid-1"
+    client._username = "alice"
+
+    with (
+        patch("emby_cli.cli._open_client", return_value=client),
+        patch.object(client, "get_libraries", side_effect=AuthenticationError(
+            "Session expired or credentials were rejected by the server. "
+            "Run `emby-cli login` (or pass a valid --api-key) and try again."
+        )),
+    ):
+        with pytest.raises(SystemExit) as exc:
+            main()
+
+    assert exc.value.code == 1
+    err = capsys.readouterr().err
+    assert "error: Session expired" in err
+    assert "emby-cli login" in err
+    assert "Traceback" not in err

{emby_cli-0.5.2 → emby_cli-0.5.4}/tests/test_client_retry.py

@@ -7,7 +7,7 @@ from unittest.mock import MagicMock, call, patch
 import pytest
 import requests
 
-from emby_cli.client import _AUTH_PATH, EmbyClient
+from emby_cli.client import _AUTH_PATH, AuthenticationError, EmbyClient
 from emby_cli.constants import MAX_RETRIES, RETRY_BACKOFF_BASE
 
 # ── helpers ──────────────────────────────────────────────────────────────
@@ -276,10 +276,9 @@ class TestHttp401Reauth:
             patch("emby_cli.client.time.sleep"),
             patch("emby_cli.client.clear_auth_cache"),
         ):
-            with pytest.raises(requests.HTTPError) as exc_info:
+            with pytest.raises(AuthenticationError, match="Session expired"):
                 c._get("/System/Info")
 
-        assert exc_info.value.response.status_code == 401
         assert req.call_count == 3
 
     def test_next_request_can_reauthenticate_again(self):
@@ -320,12 +319,16 @@ class TestHttp401Reauth:
         with (
             patch.object(c.session, "request", side_effect=[_resp(401)]) as req,
             patch("emby_cli.client.time.sleep") as sleep,
+            patch("emby_cli.client.clear_auth_cache") as clear_cache,
         ):
-            with pytest.raises(requests.HTTPError):
+            with pytest.raises(AuthenticationError, match="Session expired"):
                 c._get("/Items")
 
         assert req.call_count == 1
         sleep.assert_not_called()
+        clear_cache.assert_called_once_with(
+            server_url="http://host:8096", username="user"
+        )
 
     def test_no_reauth_without_username(self):
         c = EmbyClient("http://host:8096", use_auth_cache=False)
@@ -337,7 +340,7 @@ class TestHttp401Reauth:
             patch.object(c.session, "request", side_effect=[_resp(401)]) as req,
             patch("emby_cli.client.time.sleep") as sleep,
         ):
-            with pytest.raises(requests.HTTPError):
+            with pytest.raises(AuthenticationError, match="Session expired"):
                 c._get("/Items")
 
         assert req.call_count == 1

emby_cli-0.5.4/tests/test_urllib3_warning.py

@@ -0,0 +1,22 @@
+"""macOS LibreSSL: urllib3 NotOpenSSLWarning must not reach the user."""
+
+from __future__ import annotations
+
+import warnings
+
+
+def test_libressl_warning_message_is_filtered():
+    """The ignore filter used by emby_cli must catch urllib3's LibreSSL notice."""
+    with warnings.catch_warnings(record=True) as recorded:
+        warnings.simplefilter("always")
+        # Same rule as __init__.py / client.py / cli.py (after simplefilter).
+        warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL")
+        warnings.warn(
+            "urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' "
+            "module is compiled with 'LibreSSL 2.8.3'. See: "
+            "https://github.com/urllib3/urllib3/issues/3020",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    assert recorded == []

emby_cli-0.5.2/src/emby_cli/__init__.py

@@ -1,6 +0,0 @@
-"""emby-cli — backup and stream media from an Emby server."""
-
-from emby_cli.client import EmbyClient
-from emby_cli.version import get_version
-
-__all__ = ["EmbyClient", "get_version"]