pulze-renderflow 2.0.8__tar.gz → 2.0.16__tar.gz

{pulze_renderflow-2.0.8 → pulze_renderflow-2.0.16}/CLAUDE.md

@@ -19,9 +19,27 @@ plugin that embeds it.
 
 ```bash
 python scripts/generate.py     # refresh openapi.json + models.pyi after a public route change
-python test/test_runtime.py    # stdlib unittest, no pytest
+python test/test_runtime.py    # the plugin runtime; stdlib unittest, no pytest
+python test/test_client.py     # the wire client
+python test/test_live.py       # the hand-rolled WebSocket
+npm run test-python            # from the repo root: all three, and what the gate runs
 ```
 
+All three suites are in `test-suites` through `scripts/test.mjs`, which the root's `test-python`
+calls — this package is not an npm workspace, so there is no `npm test --workspace` that reaches it.
+A missing interpreter **fails** that script rather than skipping: `renderflow/runtime.py` is the
+plugin API a node imports, and no type-checker anywhere can see it.
+
+`farm.py` holds what is not an operation of the document: `JobsGroup.settled`, the wait, and
+`LiveGroup.on`, the subscription. `GROUPS` is how one tag gets more than the document gives it, and
+`LIVE_ENTITIES` is the rest — group name to socket entity, so a group whose collection the farm
+pushes gets `on` and one that has no live collection does not. A group that adds something overrides
+`__dir__` too, because `dir(farm.jobs)` is how this client is meant to be explored.
+
+`live.py` is the client half of RFC 6455, hand-rolled on `socket`, `ssl` and `struct`, because the
+standard library has no WebSocket client and this package is allowed no dependency. It speaks the
+same protocol as `sdks/typescript/src/live.ts`, frame for frame.
+
 Both generated files are **committed** — review them like code. Publishing is manual
 (`python -m build` + `twine upload`), on its own cadence; this package's version field is real.
 

{pulze_renderflow-2.0.8 → pulze_renderflow-2.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pulze-renderflow
-Version: 2.0.8
+Version: 2.0.16
 Summary: Official RenderFlow API client for Python
 Project-URL: Homepage, https://pulze.io/products/renderflow
 Author-email: Pulze <support@pulze.io>
@@ -38,7 +38,7 @@ Houdini, Nuke, VRED), where installing anything is a fight.
 import renderflow as rf
 
 farm = rf.connect()                     # the local service on 127.0.0.1:44442
-# farm = rf.connect("https://rf.studio.lan:44442", api_key="rf_...")
+# farm = rf.connect("https://rf.studio.lan:44445", api_key="rf_...")
 
 for job in farm.jobs.get_jobs(status="working").data:
     print(job.name, job.status)
@@ -55,7 +55,7 @@ Operations are grouped by tag and named after the API document's `operationId`,
 reads the same here, in the TypeScript SDK, in `rfcli` and in the MCP tools:
 
 ```python
-farm.tags()                 # every group: jobs, nodes, pools, schedule, render_licenses, ...
+farm.tags()                 # every group: jobs, nodes, pools, schedule, licenses, ...
 dir(farm.jobs)              # every operation in one: get_jobs, create_job, stop_job, ...
 help(farm.jobs.get_jobs)    # the operation's own documentation, generated from the document
 ```
@@ -90,7 +90,63 @@ farm.jobs.stop_job(job.id)
 ```
 
 Bodies are plain dicts; answers read with dot access (`job.name`, `page.data`) and hand back the
-raw payload via `.to_dict()`.
+raw payload via `.to_dict()`. An answer the service does not send as JSON comes back as **bytes** —
+`farm.tasks.get_task_preview(id)` is a rendered frame, ready to write to a file.
+
+## Waiting for a job
+
+```python
+job = farm.jobs.settled(job.id)                  # answers on completed or failed
+job = farm.jobs.settled(job.id, interval=30)     # a render measured in hours
+```
+
+`None` means the job is no longer there. Archiving and deleting look the same from out here, and
+neither is going to finish.
+
+A stop is **not** an end, because suspending a job is resumable — pass
+`statuses=["completed", "failed", "suspended"]` if a stop is an answer for your caller. `timeout` is
+in seconds and there is none by default, since a long render legitimately takes days; it raises
+`TimeoutError` rather than handing back a job that has not finished.
+
+This polls rather than watching, so a wait needs no socket, no thread and no reconnect behaviour,
+and it works where a proxy passes HTTP and refuses an upgrade. `interval` is the cost: two seconds is
+right for a test render and wrong for an overnight one. When the moment a job finishes is what
+matters, watch it instead.
+
+## Live updates
+
+One socket, shared by every subscription, opened on the first and closed with the last. No polling.
+
+```python
+def draw(event):
+    if event.op == "resync":
+        return refetch()          # events were missed, read again
+    print(event.op, event.id, event.patch)
+
+stop = farm.jobs.on(draw, {"id": job.id})
+stop()
+```
+
+`on` is on every group whose collection the farm pushes: `jobs`, `tasks`, `nodes`, `pools`, `users`,
+`user_groups`, `errors`, `schedule` and `licenses`. The second argument narrows it — `id` on
+any of them, `step_id` on tasks, `node_id` on the node joins — and a list is one subscription over
+several ids rather than several subscriptions.
+
+An insert carries the whole row on `event.doc`. An update carries `event.patch`, **keyed by dotted
+path**, so a job's progress arrives as `event.patch["progress.percent"]`. A delete carries the id.
+
+**A `resync` event is not a change.** It means events were missed and the collection has to be read
+again, because the socket has no replay: a reconnect, a dropped frame, or a client the farm outran
+all mean the same thing. It arrives through the same handler precisely so there is nothing to forget
+to pass.
+
+`farm.live.close()` drops everything, and `farm.live.on_error` reports a refused credential; it
+writes to stderr until you replace it. The socket runs on a daemon thread, so a script that forgot to
+unsubscribe still exits.
+
+There is still **no dependency**: `renderflow/live.py` is the client half of RFC 6455 hand-rolled on
+`socket`, `ssl` and `struct`, because installing `websocket-client` into Maya is the fight this
+package exists to avoid.
 
 ## Models
 

{pulze_renderflow-2.0.8 → pulze_renderflow-2.0.16}/README.md

@@ -18,7 +18,7 @@ Houdini, Nuke, VRED), where installing anything is a fight.
 import renderflow as rf
 
 farm = rf.connect()                     # the local service on 127.0.0.1:44442
-# farm = rf.connect("https://rf.studio.lan:44442", api_key="rf_...")
+# farm = rf.connect("https://rf.studio.lan:44445", api_key="rf_...")
 
 for job in farm.jobs.get_jobs(status="working").data:
     print(job.name, job.status)
@@ -35,7 +35,7 @@ Operations are grouped by tag and named after the API document's `operationId`,
 reads the same here, in the TypeScript SDK, in `rfcli` and in the MCP tools:
 
 ```python
-farm.tags()                 # every group: jobs, nodes, pools, schedule, render_licenses, ...
+farm.tags()                 # every group: jobs, nodes, pools, schedule, licenses, ...
 dir(farm.jobs)              # every operation in one: get_jobs, create_job, stop_job, ...
 help(farm.jobs.get_jobs)    # the operation's own documentation, generated from the document
 ```
@@ -70,7 +70,63 @@ farm.jobs.stop_job(job.id)
 ```
 
 Bodies are plain dicts; answers read with dot access (`job.name`, `page.data`) and hand back the
-raw payload via `.to_dict()`.
+raw payload via `.to_dict()`. An answer the service does not send as JSON comes back as **bytes** —
+`farm.tasks.get_task_preview(id)` is a rendered frame, ready to write to a file.
+
+## Waiting for a job
+
+```python
+job = farm.jobs.settled(job.id)                  # answers on completed or failed
+job = farm.jobs.settled(job.id, interval=30)     # a render measured in hours
+```
+
+`None` means the job is no longer there. Archiving and deleting look the same from out here, and
+neither is going to finish.
+
+A stop is **not** an end, because suspending a job is resumable — pass
+`statuses=["completed", "failed", "suspended"]` if a stop is an answer for your caller. `timeout` is
+in seconds and there is none by default, since a long render legitimately takes days; it raises
+`TimeoutError` rather than handing back a job that has not finished.
+
+This polls rather than watching, so a wait needs no socket, no thread and no reconnect behaviour,
+and it works where a proxy passes HTTP and refuses an upgrade. `interval` is the cost: two seconds is
+right for a test render and wrong for an overnight one. When the moment a job finishes is what
+matters, watch it instead.
+
+## Live updates
+
+One socket, shared by every subscription, opened on the first and closed with the last. No polling.
+
+```python
+def draw(event):
+    if event.op == "resync":
+        return refetch()          # events were missed, read again
+    print(event.op, event.id, event.patch)
+
+stop = farm.jobs.on(draw, {"id": job.id})
+stop()
+```
+
+`on` is on every group whose collection the farm pushes: `jobs`, `tasks`, `nodes`, `pools`, `users`,
+`user_groups`, `errors`, `schedule` and `licenses`. The second argument narrows it — `id` on
+any of them, `step_id` on tasks, `node_id` on the node joins — and a list is one subscription over
+several ids rather than several subscriptions.
+
+An insert carries the whole row on `event.doc`. An update carries `event.patch`, **keyed by dotted
+path**, so a job's progress arrives as `event.patch["progress.percent"]`. A delete carries the id.
+
+**A `resync` event is not a change.** It means events were missed and the collection has to be read
+again, because the socket has no replay: a reconnect, a dropped frame, or a client the farm outran
+all mean the same thing. It arrives through the same handler precisely so there is nothing to forget
+to pass.
+
+`farm.live.close()` drops everything, and `farm.live.on_error` reports a refused credential; it
+writes to stderr until you replace it. The socket runs on a daemon thread, so a script that forgot to
+unsubscribe still exits.
+
+There is still **no dependency**: `renderflow/live.py` is the client half of RFC 6455 hand-rolled on
+`socket`, `ssl` and `struct`, because installing `websocket-client` into Maya is the fight this
+package exists to avoid.
 
 ## Models
 

{pulze_renderflow-2.0.8 → pulze_renderflow-2.0.16}/pyproject.toml

@@ -1,58 +1,58 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "pulze-renderflow"
-version = "2.0.8"
-description = "Official RenderFlow API client for Python"
-readme = "README.md"
-license = "MIT"
-requires-python = ">=3.10"
-authors = [
-    { name = "Pulze", email = "support@pulze.io" }
-]
-keywords = [
-    "3dsmax",
-    "arnold",
-    "blender",
-    "cinema4d",
-    "corona",
-    "fusion",
-    "houdini",
-    "maya",
-    "nuke",
-    "redshift",
-    "vray",
-    "network-rendering",
-    "pulze",
-    "render-farm",
-    "renderflow",
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-]
-# None, deliberately. The client binds to the OpenAPI document shipped inside the package
-# (`renderflow/wire.py` + `renderflow/openapi.json`), so the whole SDK is standard library —
-# it imports inside a DCC's bundled Python with nothing installed. The typed models are
-# `models.pyi`, which only editors read. datamodel-code-generator is a dev-only tool used by
-# `scripts/generate.py`, never a requirement of the package.
-dependencies = []
-
-[project.urls]
-Homepage = "https://pulze.io/products/renderflow"
-
-[tool.hatch.build.targets.wheel]
-packages = ["renderflow"]
-
-[tool.hatch.build.targets.sdist]
-exclude = [
-    "examples/",
-]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pulze-renderflow"
+version = "2.0.16"
+description = "Official RenderFlow API client for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Pulze", email = "support@pulze.io" }
+]
+keywords = [
+    "3dsmax",
+    "arnold",
+    "blender",
+    "cinema4d",
+    "corona",
+    "fusion",
+    "houdini",
+    "maya",
+    "nuke",
+    "redshift",
+    "vray",
+    "network-rendering",
+    "pulze",
+    "render-farm",
+    "renderflow",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# None, deliberately. The client binds to the OpenAPI document shipped inside the package
+# (`renderflow/wire.py` + `renderflow/openapi.json`), so the whole SDK is standard library —
+# it imports inside a DCC's bundled Python with nothing installed. The typed models are
+# `models.pyi`, which only editors read. datamodel-code-generator is a dev-only tool used by
+# `scripts/generate.py`, never a requirement of the package.
+dependencies = []
+
+[project.urls]
+Homepage = "https://pulze.io/products/renderflow"
+
+[tool.hatch.build.targets.wheel]
+packages = ["renderflow"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "examples/",
+]

{pulze_renderflow-2.0.8 → pulze_renderflow-2.0.16}/renderflow/__init__.py

@@ -4,7 +4,7 @@ Two halves, one import:
 
     import renderflow as rf
 
-    plates = rf.files("plates", pattern="*.exr")   # declarations become UI fields and CLI flags
+    plates = rf.folder("plates")                   # a declaration is the field and the value
 
     @rf.execute
     def convert(plate):                            # runs on a render node, once per item
@@ -22,7 +22,6 @@ which is why it is a function and not a class you construct at import time.
 from __future__ import annotations
 
 import atexit
-import os
 import sys
 from typing import TYPE_CHECKING, Any
 
@@ -39,14 +38,15 @@ from .runtime import (
     done,
     env,
     execute,
+    expand,
     file,
-    files,
     float_,
     folder,
     frames,
     int_,
     job,
     log,
+    list_,
     node,
     output,
     pairs,
@@ -54,20 +54,24 @@ from .runtime import (
     paths,
     prepare,
     progress,
+    read,
     resolution,
+    state,
     step,
     submit,
     task,
+    tasks,
     text,
     tool,
 )
 
-# `int`, `float`, `bool` and `file` are builtins; inside this module the declarations are spelled
+# `int`, `float`, `bool` and `list` are builtins; inside this module they are spelled
 # with a trailing underscore so they do not shadow them, and exported under the names the docs use.
 # A caller writes `rf.int("samples")` — `rf` is a namespace, so nothing is shadowed there.
 globals()["int"] = int_
 globals()["float"] = float_
 globals()["bool"] = bool_
+globals()["list"] = list_
 
 if TYPE_CHECKING:      # for editors only — importing this at runtime would pull in httpx
     from .farm import Farm
@@ -91,41 +95,20 @@ if _INSPECT_FLAG in sys.argv:
         sys.stdout = _real_stdout
         runtime._inspect()
 
-else:
-    # A bare `python script.py --plates ./x` runs the whole list here, at exit — the declarations
-    # only exist once the module body has run. A bootstrap binds values before the script imports
-    # us, which sets `driven` and keeps this out of its way.
-    runtime._read_argv(sys.argv[1:])
-
-    _previous_excepthook = sys.excepthook
-
-    def _mark_crashed(kind, value, trace) -> None:
-        runtime._ctx.crashed = True
-        _previous_excepthook(kind, value, trace)
-
-    sys.excepthook = _mark_crashed
-
-    @atexit.register
-    def _run_bare() -> None:
-        if runtime._ctx.driven or runtime._ctx.crashed or runtime._ctx.hooks["execute"] is None:
-            return
-
-        code = runtime._local(sys.argv[1:])
-        if code:
-            sys.stdout.flush()
-            sys.stderr.flush()
-            os._exit(code)    # atexit cannot set the exit code any other way
+# Nothing happens otherwise. Importing this package does not make a script runnable as a program:
+# a plugin runs as a task, where a bootstrap binds its values, its node and the farm's path mapping
+# first, and none of that exists in a terminal.
 
 __all__ = [
     # connecting
     "connect", "Farm",
     # declarations
     "text", "int", "float", "bool", "choice", "file", "folder", "pairs", "resolution", "output",
-    "frames", "files", "args",
+    "frames", "args", "expand", "list",
     # lifecycle
-    "execute", "submit", "prepare", "cleanup",
+    "execute", "submit", "tasks", "read", "prepare", "cleanup",
     # context
-    "job", "step", "task", "node", "env", "paths", "path", "app", "tool",
+    "job", "step", "task", "node", "env", "paths", "path", "app", "tool", "state",
     # reporting
     "progress", "log", "fatal", "done",
     # exceptions