watch
Watch: one socket that says which of your objects changed, so what shows them reads them again instead of polling.
for message in noclick.watch(objects=["deployment", "domain"]):
if message.type == "change":
refresh(message.object, message.object_id)
elif message.type == "reset" or (message.type == "ready" and not message.resumed):
refresh_all()A change names an object (as its read's object says it: deployment, channel, agent, ...) and its
id, never its data: read it again. It is not the event log (noclick.Event, webhooks), which records what
happened, with data, for 30 days and delivers each event at least once. A change is a hint, delivered at most once:
re-read everything you show on reset, on a ready that didn't resume (the first one too, for anything you read
before it), and on a slow timer of your own if you must never be stale.
Your key follows the account's objects, its users' included; acting for one user (user), only that user's. A
server whose page should watch hands the page a token from watch_token (pass the page's origin); the page
opens it with the TypeScript SDK's watch({ token }).
watch needs the websockets package: pip install "noclick[live]".
noclick.watch(
*, objects=None, user=..., client=None, token=None, on_status=None
) -> Iterator[WatchMessage]Follow your objects' changes until you stop reading. Reconnects by itself (a new token each time), resuming
after the last change it gave you; raises only what trying again can't fix: the token call refused (a revoked
key, a scope the key lacks, a deployment where watching isn't available) or WatchRefused, the room refusing
two fresh tokens in a row. token: where tokens come from instead of this client, a function returning
(url, token). on_status hears connecting, live, reconnecting and stopped.
A change can be lost (a deploy, a dropped connection, a busy second), and nothing says so but these: read again
what you show on reset, on a ready that didn't resume, and on a slow timer of your own if it must never be
stale.
NoneWho the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
None)NoneNoneWatchMessage values: ready as each connection opens, change, typing and reset.
Follow your deployments as they move:
for message in noclick.watch(objects=["deployment"]):
if message.type == "change":
print(message.object, message.object_id, message.status)In async code, relay it to your own UI:
async for message in noclick.watch.aio(objects=["channel"]):
if message.type == "change":
await websocket.send_json(message.raw)watch_token
noclick.watch_token(*, objects=None, origin=None, user=..., client=None) -> WatchTokenA single-use token for the watch socket (POST /v1/watch/tokens), to open within a minute: hand url and
token to the page that connects, with its origin (the socket must then come from that page).
NoneNoneWho the call acts for. Defaults to the user set by noclick.as_user (none: the account itself).
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
None)A WatchToken: the socket's url, the token, when it expires and when the connection it opens ends.
token = noclick.watch_token(user="user_42", origin="https://app.example.com")
return {"url": token.url, "token": token.token}WatchReady
class WatchReadyThe socket is open: resumed when it carried on from the last change you got, so nothing was missed.
| resumed | bool | |
| type | str |
WatchChange
class WatchChangeAn object changed: read it again.
| id | str | This change's place in the stream (what a reconnect resumes after). |
| at | Any | |
| object | str | |
| object_id | str | None | Its id; None for a |
| status | str | None | Its status as its read gave it then (advisory: the read is the truth); None once it's gone. |
| parent | dict[str, str] | None | What it belongs to ( |
| change | str | None | What moved: an agent's |
| version | int | None | A workflow's graph version now. |
| workspace_id | str | None | |
| message_id | str | None | |
| thread_id | str | None | |
| raw | dict[str, Any] | The response JSON exactly as the API sent it. |
| type | str |
WatchTyping
class WatchTypingSomeone started or stopped typing in a channel you read (never sent to the one typing).
| channel_id | str | |
| workspace_id | str | None | |
| user_id | str | Who: a user's id, or |
| typing | bool | |
| raw | dict[str, Any] | The response JSON exactly as the API sent it. |
| type | str |
WatchReset
class WatchResetToo much changed to say each: read again everything you show.
| type | str |
WatchToken
class WatchTokenA single-use token for the socket at url, good until expires_at.
| url | str | |
| token | str | |
| expires_at | Any | |
| connection_ends_at | Any | When the connection it opens ends ( |
| objects | list[str] | |
| user_id | str | None | The user whose objects it follows; None for the account's. |
| origin | str | None | The page's origin the socket must come from, when one was given. |
| raw | dict[str, Any] | The response JSON exactly as the API sent it. |
WatchRefused
class WatchRefused(Error)The room refused two fresh tokens in a row: access ended (a revoked key, a deleted user).
- Inherits from Error.
WatchMessage
noclick.WatchMessage = Union[WatchReady, WatchChange, WatchTyping, WatchReset]What watch yields; a message type this version doesn't know is skipped, so the stream can grow.