pulze-renderflow 2.0.7__tar.gz → 2.0.9__tar.gz

{pulze_renderflow-2.0.7 → pulze_renderflow-2.0.9}/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.7 → pulze_renderflow-2.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pulze-renderflow
-Version: 2.0.7
+Version: 2.0.9
 Summary: Official RenderFlow API client for Python
 Project-URL: Homepage, https://pulze.io/products/renderflow
 Author-email: Pulze <support@pulze.io>
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
-# renderflow
+# pulze-renderflow
 
 Official Python client for the [RenderFlow](https://pulze.io/products/renderflow) API.
 
@@ -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, ...
+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
 ```
@@ -73,10 +73,14 @@ help(farm.jobs.get_jobs)    # the operation's own documentation, generated from
 A recipe — `type` plus a file and the flat per-DCC fields — is the short way in; the service
 expands it into the step tree:
 
+Every recipe requires `type`, `file` and `host` — `host` is which application renders it, and only
+its `id` is mandatory:
+
 ```python
 job = farm.jobs.create_job(body={
     "type": "blender.render",
     "file": "//share/scenes/shot_010.blend",
+    "host": {"id": "blender", "version": "4.5"},
     "frame": "1-100",
     "pool_id": "...",
 })
@@ -86,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
 
@@ -96,7 +156,7 @@ reads them from `models.pyi` — autocomplete and type checking with nothing to
 ```python
 from renderflow.models import MayaRenderRecipe
 
-recipe: MayaRenderRecipe = {"type": "maya.render", "file": "//share/scenes/hero.mb", "host": {"name": "maya"}}
+recipe: MayaRenderRecipe = {"type": "maya.render", "file": "//share/scenes/hero.mb", "host": {"id": "maya", "version": "2026"}}
 farm.jobs.create_job(body=recipe)
 ```
 

{pulze_renderflow-2.0.7 → pulze_renderflow-2.0.9}/README.md

@@ -1,4 +1,4 @@
-# renderflow
+# pulze-renderflow
 
 Official Python client for the [RenderFlow](https://pulze.io/products/renderflow) API.
 
@@ -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, ...
+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
 ```
@@ -53,10 +53,14 @@ help(farm.jobs.get_jobs)    # the operation's own documentation, generated from
 A recipe — `type` plus a file and the flat per-DCC fields — is the short way in; the service
 expands it into the step tree:
 
+Every recipe requires `type`, `file` and `host` — `host` is which application renders it, and only
+its `id` is mandatory:
+
 ```python
 job = farm.jobs.create_job(body={
     "type": "blender.render",
     "file": "//share/scenes/shot_010.blend",
+    "host": {"id": "blender", "version": "4.5"},
     "frame": "1-100",
     "pool_id": "...",
 })
@@ -66,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
 
@@ -76,7 +136,7 @@ reads them from `models.pyi` — autocomplete and type checking with nothing to
 ```python
 from renderflow.models import MayaRenderRecipe
 
-recipe: MayaRenderRecipe = {"type": "maya.render", "file": "//share/scenes/hero.mb", "host": {"name": "maya"}}
+recipe: MayaRenderRecipe = {"type": "maya.render", "file": "//share/scenes/hero.mb", "host": {"id": "maya", "version": "2026"}}
 farm.jobs.create_job(body=recipe)
 ```
 

{pulze_renderflow-2.0.7 → pulze_renderflow-2.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pulze-renderflow"
-version = "2.0.7"
+version = "2.0.9"
 description = "Official RenderFlow API client for Python"
 readme = "README.md"
 license = "MIT"

pulze_renderflow-2.0.9/renderflow/farm.py

@@ -0,0 +1,243 @@
+"""The RenderFlow API client.
+
+    import renderflow as rf
+
+    farm = rf.connect()                                    # the local service, no key
+    farm = rf.connect("https://rf.studio.lan:44445", api_key="rf_...")   # a remote farm
+
+    for job in farm.jobs.get_jobs(status="working").data:
+        print(job.name, job.status)
+
+Operations are grouped by tag and named after the document's ``operationId`` — the same names
+the REST route, the TypeScript SDK, ``rfcli`` and the MCP tools use, so one operation reads the
+same everywhere. ``farm.jobs.get_jobs`` is ``GET /jobs``; ``farm.nodes.stop_node`` is
+``POST /nodes/{id}/stop``.
+
+Nothing here is written per operation, and nothing is generated: the methods are the operations
+of the OpenAPI document shipped inside this package (``renderflow/openapi.json``), bound to this
+farm on first use — an operation added to the document arrives the moment the copy is refreshed,
+and one that is removed stops existing rather than answering 404. Bodies are plain dicts;
+answers read with dot access (``job.name``) and hand back the raw payload via ``to_dict()``.
+The typed view of it all is ``models.pyi``, which the editor reads and the interpreter never
+pays for — the whole client is standard library, so it runs inside a DCC's own Python.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Callable
+
+from . import wire
+from .live import LiveConnection, LiveEvent
+from .wire import ApiError, AuthenticatedClient, Client
+
+DEFAULT_URL = "http://127.0.0.1:44442"
+
+
+class Group:
+    """One tag's operations, bound to a farm — ``farm.jobs``, ``farm.nodes``."""
+
+    def __init__(self, farm: "Farm", tag: str) -> None:
+        self._farm = farm
+        self._tag = tag
+        self._operations = wire.operations()[tag]
+
+    def __dir__(self) -> list[str]:
+        return sorted(self._operations)
+
+    def __getattr__(self, name: str) -> Callable[..., Any]:
+        try:
+            operation = self._operations[name]
+        except KeyError:
+            raise AttributeError(
+                f"`{self._tag}` has no operation `{name}`. Available: {', '.join(self.__dir__())}"
+            ) from None
+
+        client = self._farm._client
+
+        def call(*args: Any, **kwargs: Any) -> Any:
+            return client.call(operation, args, kwargs)
+
+        call.__name__ = name
+        call.__doc__ = operation.doc
+        setattr(self, name, call)   # resolved once; afterwards it is a plain attribute
+        return call
+
+    def __repr__(self) -> str:
+        return f"<renderflow group {self._tag}: {len(self._operations)} operations>"
+
+
+#: Group name to the socket entity it watches. A group absent from this watches nothing: the
+#: archive, `info`, `service` and the webhook subscriptions have no live collection behind them.
+LIVE_ENTITIES = {
+    "jobs": "jobs",
+    "tasks": "tasks",
+    "nodes": "nodes",
+    "pools": "pools",
+    "users": "users",
+    "user_groups": "user-groups",
+    "errors": "errors",
+    "schedule": "schedule",
+    "licenses": "render-licenses"
+}
+
+
+class LiveGroup(Group):
+    """A group whose collection the farm also pushes, so it can be watched as well as read."""
+
+    def __dir__(self) -> list[str]:
+        # `dir(farm.jobs)` is how this client is explored, so anything it answers has to be in it.
+        return sorted({*super().__dir__(), "on"})
+
+    def on(self, handler: Callable[[LiveEvent], None], filter: dict[str, Any] | None = None) -> Callable[[], None]:
+        """Watch this collection. Answers the function that stops watching it.
+
+        One socket carries every subscription, opened on the first and closed with the last::
+
+            stop = farm.jobs.on(lambda event: print(event.op, event.id), {"id": job.id})
+            stop()
+
+        ``filter`` narrows it: ``id`` on any entity, ``step_id`` on tasks, ``node_id`` on the node
+        joins. A list is one subscription over several ids rather than several subscriptions.
+
+        **A ``resync`` event is not a change.** It means events were missed and this collection has
+        to be read again, because the socket has no replay. It arrives through this same handler
+        precisely so there is nothing to forget to pass.
+        """
+        return self._farm.live.subscribe(LIVE_ENTITIES[self._tag], handler, filter)
+
+
+#: What counts as the end of a job. A stop is resumable, so `suspended` is not one of them.
+SETTLED = ("completed", "failed")
+
+
+class JobsGroup(LiveGroup):
+    """`jobs`, plus the one wait that is not an operation of the document."""
+
+    def __dir__(self) -> list[str]:
+        # `dir(farm.jobs)` is how this client is discovered, so anything it answers has to be in it.
+        return sorted({*super().__dir__(), "settled"})
+
+    def settled(self, job_id, *, statuses=None, timeout=None, interval=2.0):
+        """Waits for a job to finish. Answers the job, or ``None`` when it is no longer there.
+
+        Every integration writes this, and writes it wrong: the naive loop stops on ``completed``
+        only, so a failed render waits for ever, and it treats a job that has been removed as one
+        still to come.
+
+        Archiving and deleting are the same thing from out here, so either resolves ``None`` --
+        whichever happened, this job is not going to finish.
+
+        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. The interval is
+        the cost: a render measured in hours wants ``interval=30``, not two seconds. Reach for
+        ``farm.jobs.on(...)`` when the moment a job finishes is what matters.
+
+        ``timeout`` is seconds, and there is none by default -- a long render legitimately takes
+        days. Raising ``TimeoutError`` rather than answering is deliberate: a caller that waited in
+        vain has not been given a job, and must not be handed something that reads like one.
+        """
+        ends = tuple(statuses) if statuses else SETTLED
+        deadline = None if timeout is None else time.monotonic() + timeout
+
+        while True:
+            try:
+                job = self.get_job(job_id)
+            except ApiError as refused:
+                if refused.status == 404:
+                    return None
+                raise
+
+            if getattr(job, "status", None) in ends:
+                return job
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise TimeoutError(f"{job_id} had not finished after {timeout}s")
+
+            # Never overshoot the deadline just to complete a sleep.
+            nap = interval if deadline is None else min(interval, max(0.0, deadline - time.monotonic()))
+            time.sleep(nap)
+
+
+#: The groups that carry more than the document's operations. Every other group whose collection
+#: the farm pushes gets `on` through `LiveGroup`.
+GROUPS = {"jobs": JobsGroup}
+
+
+def _group_class(tag: str) -> type:
+    if tag in GROUPS:
+        return GROUPS[tag]
+    return LiveGroup if tag in LIVE_ENTITIES else Group
+
+
+class Farm:
+    """A connection to one RenderFlow installation. Prefer ``renderflow.connect()``."""
+
+    def __init__(self, url: str | None = None, api_key: str | None = None, *, timeout: float = 60.0) -> None:
+        self.url = (url or os.environ.get("RENDERFLOW_URL") or DEFAULT_URL).rstrip("/")
+        key = api_key if api_key is not None else os.environ.get("RENDERFLOW_API_KEY")
+
+        base_url = self.url if self.url.endswith("/api/v1") else f"{self.url}/api/v1"
+
+        # No key is a real configuration, not a missing one: `POST /jobs` and the loopback
+        # routes are reachable from the same machine without a credential, which is how a DCC
+        # plugin on a workstation submits.
+        if key:
+            self._client: Client | AuthenticatedClient = AuthenticatedClient(base_url=base_url, token=key, timeout=timeout)
+        else:
+            self._client = Client(base_url=base_url, timeout=timeout)
+
+        self._groups: dict[str, Group] = {}
+        self._key = key or ""
+        self._live: LiveConnection | None = None
+
+    def __dir__(self) -> list[str]:
+        return sorted({*super().__dir__(), *self.tags()})
+
+    def tags(self) -> list[str]:
+        return sorted(wire.operations())
+
+    def __getattr__(self, name: str) -> Group:
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        if name not in self._groups:
+            if name not in self.tags():
+                raise AttributeError(f"no such API group `{name}`. Available: {', '.join(self.tags())}")
+            self._groups[name] = _group_class(name)(self, name)
+
+        return self._groups[name]
+
+    @property
+    def live(self) -> LiveConnection:
+        """The one socket every ``on`` shares. Constructing it opens nothing."""
+        if self._live is None:
+            self._live = LiveConnection(self.url, self._key)
+
+        return self._live
+
+    def close(self) -> None:
+        if self._live is not None:
+            self._live.close()
+
+        self._client.close()
+
+    def __enter__(self) -> "Farm":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"<renderflow.Farm {self.url}>"
+
+
+def connect(url: str | None = None, api_key: str | None = None, *, timeout: float = 60.0) -> Farm:
+    """Connect to a farm.
+
+    Each argument falls back to the environment and then to the local service:
+    ``url`` to ``RENDERFLOW_URL`` then ``http://127.0.0.1:44442``, ``api_key`` to
+    ``RENDERFLOW_API_KEY`` then to no credential at all.
+    """
+    return Farm(url, api_key, timeout=timeout)