content-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{content_cli-0.4.0 → content_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: content-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: Command-line client for the Content engine (talks to /api/v1).
 Project-URL: Homepage, https://github.com/LatentNoise/content
 Project-URL: Source, https://github.com/LatentNoise/content
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: content-sdk==0.4.0
+Requires-Dist: content-sdk==0.6.0
 Description-Content-Type: text/markdown
 
 # `content` — Content CLI
@@ -95,3 +95,19 @@ content cancel <job_id> ; content retry <job_id>
 
 Global flags: `--api-url URL` and `--json` (raw JSON output) go before the
 subcommand. Exit code is non-zero on API errors or a failed watched job.
+
+## Exit codes when watching a job
+
+`content ... --watch` and `content watch <job>` return the outcome, so a script
+can chain on it (ADR 0021):
+
+| Code | Meaning |
+| --- | --- |
+| `0` | `succeeded` — everything asked for was produced |
+| `2` | `partially_succeeded` — some of it was, and at least one step failed |
+| `1` | `failed` or `cancelled` |
+
+`2` is deliberately distinct from `1`. A playlist that yielded five videos of
+six, or a download whose delivery into your library was refused, is not a
+failure — but it is not a success either, and a script that treats it as one
+will quietly move on with missing files.

{content_cli-0.4.0 → content_cli-0.6.0}/README.md

@@ -69,3 +69,19 @@ content cancel <job_id> ; content retry <job_id>
 
 Global flags: `--api-url URL` and `--json` (raw JSON output) go before the
 subcommand. Exit code is non-zero on API errors or a failed watched job.
+
+## Exit codes when watching a job
+
+`content ... --watch` and `content watch <job>` return the outcome, so a script
+can chain on it (ADR 0021):
+
+| Code | Meaning |
+| --- | --- |
+| `0` | `succeeded` — everything asked for was produced |
+| `2` | `partially_succeeded` — some of it was, and at least one step failed |
+| `1` | `failed` or `cancelled` |
+
+`2` is deliberately distinct from `1`. A playlist that yielded five videos of
+six, or a download whose delivery into your library was refused, is not a
+failure — but it is not a success either, and a script that treats it as one
+will quietly move on with missing files.

{content_cli-0.4.0 → content_cli-0.6.0}/content_cli/cli.py

@@ -16,6 +16,21 @@ from content_sdk.resources import TERMINAL_STATUSES
 from content_cli import __version__
 from content_cli.builders import audio_request, video_request
 
+# Exit codes for a watched job (ADR 0021). Three outcomes, three codes: a
+# script chaining on success must not proceed as if everything arrived, and it
+# should still be able to tell "some of it worked" from "none of it did".
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_PARTIAL = 2
+
+
+def _exit_code_for(status: str) -> int:
+    if status == "succeeded":
+        return EXIT_OK
+    if status == "partially_succeeded":
+        return EXIT_PARTIAL
+    return EXIT_FAILED
+
 
 def _out(obj, as_json: bool) -> None:
     print(json.dumps(obj, indent=2, ensure_ascii=False) if as_json else obj)
@@ -29,8 +44,32 @@ def _print_job(job: dict) -> None:
 
 
 def _watch(client: ContentClient, job_id: str) -> str:
-    """Stream events until the job reaches a terminal state."""
+    """Follow a job's events until it reaches a terminal state.
+
+    Uses the engine's event stream rather than asking again on a timer: a
+    forty-minute download deserves a progress line that moves when something
+    moves. The stream ends by itself when the job does.
+
+    Falls back to polling if the stream cannot be established — an old engine,
+    or a proxy that buffers SSE — because watching a job must not depend on it.
+    """
     seen = 0
+    try:
+        for event in client.stream_events(job_id):
+            seen = event["sequence"]
+            print(f"  {seen:>3} {event['type']} {event['data'] or ''}")
+    except Exception as exc:  # noqa: BLE001 — any stream failure falls back below
+        # Say so rather than degrade silently: a user who sees updates arrive
+        # every two seconds instead of instantly deserves to know the stream
+        # was refused, and by what.
+        print(
+            f"note: event stream unavailable ({exc}); polling instead", file=sys.stderr
+        )
+    return _watch_by_polling(client, job_id, seen)
+
+
+def _watch_by_polling(client: ContentClient, job_id: str, seen: int = 0) -> str:
+    """The original loop, kept as the fallback and as the terminal read."""
     while True:
         for event in client.events(job_id, after_sequence=seen):
             seen = event.sequence
@@ -38,6 +77,11 @@ def _watch(client: ContentClient, job_id: str) -> str:
         status = client.get_job(job_id).status
         if status in TERMINAL_STATUSES:
             print(f"→ {status}")
+            if status == "partially_succeeded":
+                print(
+                    f"  some steps failed — inspect them with: content job {job_id}",
+                    file=sys.stderr,
+                )
             return status
         time.sleep(2.0)
 
@@ -49,7 +93,7 @@ def _submit_and_maybe_watch(client: ContentClient, request: dict, args) -> int:
     print(job.id)
     if getattr(args, "watch", False):
         status = _watch(client, job.id)
-        return 0 if status in ("succeeded", "partially_succeeded") else 1
+        return _exit_code_for(status)
     return 0
 
 
@@ -239,7 +283,7 @@ def run(argv: list[str], client: ContentClient) -> int:
         _out(job, True) if args.json else _print_job(job)
     elif cmd == "watch":
         status = _watch(client, args.job_id)
-        return 0 if status in ("succeeded", "partially_succeeded") else 1
+        return _exit_code_for(status)
     elif cmd == "artifacts":
         arts = client.artifacts(args.job_id)
         if args.json:

{content_cli-0.4.0 → content_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "content-cli"
-version = "0.4.0"
+version = "0.6.0"
 description = "Command-line client for the Content engine (talks to /api/v1)."
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -24,7 +24,7 @@ classifiers = [
 # Pinned to the exact SDK release, not a floor: the monorepo ships one version
 # for everything (`make version`), and a CLI resolving to a different SDK than
 # the one it was tested against is precisely the drift that guarantees buys.
-dependencies = ["content-sdk==0.4.0"]
+dependencies = ["content-sdk==0.6.0"]
 
 [project.scripts]
 content = "content_cli.cli:main"