zerogen 0.2.1__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {zerogen-0.2.1 → zerogen-0.3.0}/PKG-INFO +132 -7
  2. {zerogen-0.2.1 → zerogen-0.3.0}/README.md +131 -6
  3. {zerogen-0.2.1 → zerogen-0.3.0}/pyproject.toml +1 -1
  4. {zerogen-0.2.1 → zerogen-0.3.0}/pyproject.toml.orig +1 -1
  5. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/__init__.py +6 -2
  6. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_client.py +24 -5
  7. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_errors.py +11 -0
  8. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_options.py +1 -1
  9. zerogen-0.3.0/src/zerogen/_version.py +1 -0
  10. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/assets.py +314 -55
  11. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/folders.py +162 -5
  12. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/runs.py +87 -6
  13. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/uploads.py +84 -3
  14. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/__init__.py +64 -0
  15. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/_requests.py +174 -2
  16. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/_responses.py +207 -0
  17. zerogen-0.2.1/src/zerogen/_version.py +0 -1
  18. {zerogen-0.2.1 → zerogen-0.3.0}/LICENSE +0 -0
  19. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_models.py +0 -0
  20. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_pagination.py +0 -0
  21. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/py.typed +0 -0
  22. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/__init__.py +0 -0
  23. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/labels.py +0 -0
  24. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/models.py +0 -0
  25. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/naming_presets.py +0 -0
  26. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/projects.py +0 -0
  27. {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/skills.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: zerogen
3
- Version: 0.2.1
3
+ Version: 0.3.0
4
4
  Summary: The official Python library for the ZeroGen API
5
5
  Keywords: zerogen,generative-ai,image-generation,video-generation,api
6
6
  Author: ZeroGen LLC
@@ -77,6 +77,18 @@ response is a pydantic model with snake_case attributes, such as
77
77
  completes and checks them. Each model takes its own parameters: read a model's
78
78
  request schema with `zerogen.models.get(id)`.
79
79
 
80
+ To label every output as it lands, add `labelIds`, which also needs the
81
+ `library:organize` scope. To upscale one output of a 480p Draft to its final,
82
+ send `upscaleDraft` with the draft's model ID, and leave out `prompt`, `inputs`,
83
+ `output`, `parameters` and `naming`. The final is a new run, quoted and billed
84
+ like any other:
85
+
86
+ ```python
87
+ final = zerogen.runs.create_and_wait(
88
+ {"model": draft_model, "upscaleDraft": {"runId": draft.id, "outputIndex": 0}}
89
+ )
90
+ ```
91
+
80
92
  ## Async
81
93
 
82
94
  `AsyncZeroGen` has the same methods, to await:
@@ -101,6 +113,35 @@ asyncio.run(main())
101
113
  Cancel the task to stop a `create_and_wait` or `wait_for` from waiting; the run
102
114
  keeps running.
103
115
 
116
+ ## Progress
117
+
118
+ To show a run's progress while you wait, pass `wait_for` an `on_update`
119
+ function, which gets the run after each read, and a shorter `poll`:
120
+
121
+ ```python
122
+ from zerogen.types import Run
123
+
124
+
125
+ def report(run: Run) -> None:
126
+ done = sum(output.status == "succeeded" for output in run.outputs)
127
+ print(f"{run.status}: {done} of {len(run.outputs)} outputs")
128
+
129
+
130
+ run = zerogen.runs.create(request)
131
+ run = zerogen.runs.wait_for(run.id, poll=5, on_update=report)
132
+ ```
133
+
134
+ `poll` is how many seconds each read may wait for the run to end, from 1 to 60,
135
+ and 60 by default. The API answers as soon as the run ends, so a shorter `poll`
136
+ only reports progress more often, at a request each time. With `AsyncZeroGen`,
137
+ `on_update` can also be a coroutine function.
138
+
139
+ To stop waiting from another thread, such as when someone presses Cancel, pass
140
+ `ZeroGen`'s `wait_for` a `threading.Event` as `cancel`. When it's set,
141
+ `wait_for` raises `WaitCancelledError` at once, even partway through a read.
142
+ With `AsyncZeroGen`, cancel the task instead. Either way, the run keeps
143
+ running; to stop it, call `runs.cancel`.
144
+
104
145
  ## Inputs
105
146
 
106
147
  Give a run an input by asset ID or by `https` URL. To upload a file, use
@@ -123,6 +164,47 @@ seek. It takes the media type from the filename's extension, or from
123
164
  `content_type`. It sends the file's SHA-256 digest, so a file the project
124
165
  already has is reused instead of uploaded again.
125
166
 
167
+ ## Declared provenance
168
+
169
+ When you upload a file made outside ZeroGen, such as a ComfyUI result, the
170
+ upload can declare what it was made from and with. ZeroGen records the
171
+ declaration as a no-charge run, so the asset's lineage shows its sources, and
172
+ its details show the tool, prompt and workflow as a declaration, unchecked:
173
+
174
+ ```python
175
+ saved = zerogen.uploads.upload(
176
+ "render.png",
177
+ declaration={
178
+ "tool": {
179
+ "name": "comfyui",
180
+ "version": "0.43.0",
181
+ "integration": {"name": "zerogen-nodes", "version": "0.1.0"},
182
+ },
183
+ "sources": [{"asset": upload.asset_id, "role": "reference"}],
184
+ "prompt": "A lighthouse at dawn",
185
+ "externalRef": {"system": "comfyui", "id": "prompt-1"},
186
+ },
187
+ )
188
+ print(saved.declaration_recorded)
189
+ ```
190
+
191
+ A declaration takes `tool` and any of `sources`, `prompt`, `workflow`, a JSON
192
+ object of up to 256 KiB, `externalRef` and `occurredAt`. Declaring `sources`
193
+ needs the `library:read` scope as well as `uploads:create`. With a
194
+ declaration, `naming` names the new asset with a naming preset, as a run's
195
+ outputs are named.
196
+
197
+ When the project already has an identical file, the upload returns that asset,
198
+ and its lineage stands. If you uploaded it and it has no declaration yet, the
199
+ upload declares it, unless a declared source is that file or was made from it.
200
+ `declaration_recorded` says whether ZeroGen recorded your declaration. To declare
201
+ a file you uploaded earlier, use `assets.declare`: an asset takes one
202
+ declaration, from its uploader.
203
+
204
+ `assets.get` returns an asset's declaration in `declared`, and, with
205
+ `include_workflow=True`, its workflow in `workflow`. Both are untrusted
206
+ content.
207
+
126
208
  ## Library
127
209
 
128
210
  Read and organize your organization's Library: `projects`, `assets`,
@@ -141,14 +223,56 @@ zerogen.folders.add_assets(project.id, folder.id, {"assetIds": [a.id for a in vi
141
223
  List filters that take several values, such as `label_id` and `resolution`,
142
224
  take a list.
143
225
 
226
+ Each asset and run names who made it in `created_by`, and where in `created_via`:
227
+ `web`, `agent`, `mcp` or `api`. Both are `None` when ZeroGen recorded no one. To
228
+ find what someone made, pass `created_by` to `assets.search`, with the ID in an
229
+ asset's `created_by` or `zerogen.me()`. `web_url` opens the asset or run in
230
+ ZeroGen, after sign-in, and it's `None` for test keys.
231
+
232
+ `folders.delete` deletes a folder and its subfolders. You choose what happens to
233
+ their assets: `"keep"` preserves them, and `"trash"` sends them to Recently
234
+ deleted, including assets in other folders. It needs the `library:delete` scope,
235
+ which has to be granted explicitly, and test keys can't use it. Within an hour,
236
+ `folders.restore` undoes your own deletion:
237
+
238
+ ```python
239
+ deleted = zerogen.folders.delete(project.id, folder.id, assets="keep")
240
+ zerogen.folders.restore(project.id, {"eventId": deleted.event_id})
241
+ ```
242
+
243
+ To file into a folder path, such as a shot's `SH010/anim`, use
244
+ `folders.ensure_path`. It returns the last folder, creating each one on the
245
+ way that isn't there yet, and reuses a folder of the same name, so clients
246
+ saving into the same path at once share its folders:
247
+
248
+ ```python
249
+ anim = zerogen.folders.ensure_path(project.id, "SH010/anim")
250
+ ```
251
+
252
+ A string path splits on `/`. Folder names can contain `/`, so pass a list,
253
+ such as `["2026/11", "renders"]`, when one does.
254
+
144
255
  To download an asset's original file, use `assets.download`. It returns the
145
- file's bytes, or streams them into a path or a binary file object:
256
+ file's bytes in `content`, with its `filename`, `mime_type` and `size_bytes`.
257
+ Given a path or a binary file object, it streams the file there instead, and
258
+ returns the rest. `assets.download_to` saves the file in a directory and
259
+ returns its `path`:
146
260
 
147
261
  ```python
148
262
  image = zerogen.assets.download(asset_id)
263
+ print(image.mime_type, len(image.content))
264
+
149
265
  zerogen.assets.download(asset_id, "lighthouse.png")
266
+
267
+ saved = zerogen.assets.download_to(asset_id, "downloads")
268
+ print(saved.path)
150
269
  ```
151
270
 
271
+ The `filename` is untrusted content, so don't use it as a path yourself.
272
+ `download_to` makes a name from it with no path separators or characters that
273
+ Windows refuses. When a file in the directory already has that name, it adds a
274
+ number, as in `lighthouse (1).png`, rather than overwrite the file.
275
+
152
276
  Each call reads a new signed link and sends it to storage without your API key.
153
277
  When storage refuses a link as expired, it reads a new one and tries once more.
154
278
  To hand the link to something else, read it with `assets.get_download`: it's
@@ -226,9 +350,9 @@ The client retries connection errors and errors the API marks `retryable`,
226
350
  twice by default, with backoff. For `429` responses, it waits for
227
351
  `Retry-After`, unless that's more than a minute.
228
352
 
229
- Every `POST` sends an `Idempotency-Key`, and a call's retries reuse it, so a
230
- retried create never starts a second run. To retry safely across calls or
231
- processes, pass your own key:
353
+ Every `POST` and `DELETE` sends an `Idempotency-Key`, and a call's retries reuse
354
+ it, so a retried create never starts a second run. To retry safely across calls
355
+ or processes, pass your own key:
232
356
 
233
357
  ```python
234
358
  zerogen.runs.create(request, idempotency_key=job.id)
@@ -253,11 +377,12 @@ zerogen = ZeroGen(
253
377
  | `max_retries` | `2` | Retries for each request. |
254
378
  | `timeout` | `120` | Seconds httpx waits on each step of an attempt. A request that waits on a run gets its wait added. |
255
379
  | `default_headers` | None | Headers to send with every request. |
380
+ | `user_agent` | None | Your app's name and version, such as `zerogen-nodes/0.1`, which the `User-Agent` header names before this library's. |
256
381
  | `http_client` | A new `httpx.Client` or `httpx.AsyncClient` | The httpx client to send requests with, such as one with your proxy settings. |
257
382
 
258
383
  Every method also takes request options as keyword arguments: `timeout`,
259
- `max_retries`, `headers`, and `idempotency_key` for a `POST`. Close a client
260
- you're done with, or use it as a context manager.
384
+ `max_retries`, `headers`, and `idempotency_key` for a `POST` or `DELETE`. Close
385
+ a client you're done with, or use it as a context manager.
261
386
 
262
387
  ## Test keys
263
388
 
@@ -47,6 +47,18 @@ response is a pydantic model with snake_case attributes, such as
47
47
  completes and checks them. Each model takes its own parameters: read a model's
48
48
  request schema with `zerogen.models.get(id)`.
49
49
 
50
+ To label every output as it lands, add `labelIds`, which also needs the
51
+ `library:organize` scope. To upscale one output of a 480p Draft to its final,
52
+ send `upscaleDraft` with the draft's model ID, and leave out `prompt`, `inputs`,
53
+ `output`, `parameters` and `naming`. The final is a new run, quoted and billed
54
+ like any other:
55
+
56
+ ```python
57
+ final = zerogen.runs.create_and_wait(
58
+ {"model": draft_model, "upscaleDraft": {"runId": draft.id, "outputIndex": 0}}
59
+ )
60
+ ```
61
+
50
62
  ## Async
51
63
 
52
64
  `AsyncZeroGen` has the same methods, to await:
@@ -71,6 +83,35 @@ asyncio.run(main())
71
83
  Cancel the task to stop a `create_and_wait` or `wait_for` from waiting; the run
72
84
  keeps running.
73
85
 
86
+ ## Progress
87
+
88
+ To show a run's progress while you wait, pass `wait_for` an `on_update`
89
+ function, which gets the run after each read, and a shorter `poll`:
90
+
91
+ ```python
92
+ from zerogen.types import Run
93
+
94
+
95
+ def report(run: Run) -> None:
96
+ done = sum(output.status == "succeeded" for output in run.outputs)
97
+ print(f"{run.status}: {done} of {len(run.outputs)} outputs")
98
+
99
+
100
+ run = zerogen.runs.create(request)
101
+ run = zerogen.runs.wait_for(run.id, poll=5, on_update=report)
102
+ ```
103
+
104
+ `poll` is how many seconds each read may wait for the run to end, from 1 to 60,
105
+ and 60 by default. The API answers as soon as the run ends, so a shorter `poll`
106
+ only reports progress more often, at a request each time. With `AsyncZeroGen`,
107
+ `on_update` can also be a coroutine function.
108
+
109
+ To stop waiting from another thread, such as when someone presses Cancel, pass
110
+ `ZeroGen`'s `wait_for` a `threading.Event` as `cancel`. When it's set,
111
+ `wait_for` raises `WaitCancelledError` at once, even partway through a read.
112
+ With `AsyncZeroGen`, cancel the task instead. Either way, the run keeps
113
+ running; to stop it, call `runs.cancel`.
114
+
74
115
  ## Inputs
75
116
 
76
117
  Give a run an input by asset ID or by `https` URL. To upload a file, use
@@ -93,6 +134,47 @@ seek. It takes the media type from the filename's extension, or from
93
134
  `content_type`. It sends the file's SHA-256 digest, so a file the project
94
135
  already has is reused instead of uploaded again.
95
136
 
137
+ ## Declared provenance
138
+
139
+ When you upload a file made outside ZeroGen, such as a ComfyUI result, the
140
+ upload can declare what it was made from and with. ZeroGen records the
141
+ declaration as a no-charge run, so the asset's lineage shows its sources, and
142
+ its details show the tool, prompt and workflow as a declaration, unchecked:
143
+
144
+ ```python
145
+ saved = zerogen.uploads.upload(
146
+ "render.png",
147
+ declaration={
148
+ "tool": {
149
+ "name": "comfyui",
150
+ "version": "0.43.0",
151
+ "integration": {"name": "zerogen-nodes", "version": "0.1.0"},
152
+ },
153
+ "sources": [{"asset": upload.asset_id, "role": "reference"}],
154
+ "prompt": "A lighthouse at dawn",
155
+ "externalRef": {"system": "comfyui", "id": "prompt-1"},
156
+ },
157
+ )
158
+ print(saved.declaration_recorded)
159
+ ```
160
+
161
+ A declaration takes `tool` and any of `sources`, `prompt`, `workflow`, a JSON
162
+ object of up to 256 KiB, `externalRef` and `occurredAt`. Declaring `sources`
163
+ needs the `library:read` scope as well as `uploads:create`. With a
164
+ declaration, `naming` names the new asset with a naming preset, as a run's
165
+ outputs are named.
166
+
167
+ When the project already has an identical file, the upload returns that asset,
168
+ and its lineage stands. If you uploaded it and it has no declaration yet, the
169
+ upload declares it, unless a declared source is that file or was made from it.
170
+ `declaration_recorded` says whether ZeroGen recorded your declaration. To declare
171
+ a file you uploaded earlier, use `assets.declare`: an asset takes one
172
+ declaration, from its uploader.
173
+
174
+ `assets.get` returns an asset's declaration in `declared`, and, with
175
+ `include_workflow=True`, its workflow in `workflow`. Both are untrusted
176
+ content.
177
+
96
178
  ## Library
97
179
 
98
180
  Read and organize your organization's Library: `projects`, `assets`,
@@ -111,14 +193,56 @@ zerogen.folders.add_assets(project.id, folder.id, {"assetIds": [a.id for a in vi
111
193
  List filters that take several values, such as `label_id` and `resolution`,
112
194
  take a list.
113
195
 
196
+ Each asset and run names who made it in `created_by`, and where in `created_via`:
197
+ `web`, `agent`, `mcp` or `api`. Both are `None` when ZeroGen recorded no one. To
198
+ find what someone made, pass `created_by` to `assets.search`, with the ID in an
199
+ asset's `created_by` or `zerogen.me()`. `web_url` opens the asset or run in
200
+ ZeroGen, after sign-in, and it's `None` for test keys.
201
+
202
+ `folders.delete` deletes a folder and its subfolders. You choose what happens to
203
+ their assets: `"keep"` preserves them, and `"trash"` sends them to Recently
204
+ deleted, including assets in other folders. It needs the `library:delete` scope,
205
+ which has to be granted explicitly, and test keys can't use it. Within an hour,
206
+ `folders.restore` undoes your own deletion:
207
+
208
+ ```python
209
+ deleted = zerogen.folders.delete(project.id, folder.id, assets="keep")
210
+ zerogen.folders.restore(project.id, {"eventId": deleted.event_id})
211
+ ```
212
+
213
+ To file into a folder path, such as a shot's `SH010/anim`, use
214
+ `folders.ensure_path`. It returns the last folder, creating each one on the
215
+ way that isn't there yet, and reuses a folder of the same name, so clients
216
+ saving into the same path at once share its folders:
217
+
218
+ ```python
219
+ anim = zerogen.folders.ensure_path(project.id, "SH010/anim")
220
+ ```
221
+
222
+ A string path splits on `/`. Folder names can contain `/`, so pass a list,
223
+ such as `["2026/11", "renders"]`, when one does.
224
+
114
225
  To download an asset's original file, use `assets.download`. It returns the
115
- file's bytes, or streams them into a path or a binary file object:
226
+ file's bytes in `content`, with its `filename`, `mime_type` and `size_bytes`.
227
+ Given a path or a binary file object, it streams the file there instead, and
228
+ returns the rest. `assets.download_to` saves the file in a directory and
229
+ returns its `path`:
116
230
 
117
231
  ```python
118
232
  image = zerogen.assets.download(asset_id)
233
+ print(image.mime_type, len(image.content))
234
+
119
235
  zerogen.assets.download(asset_id, "lighthouse.png")
236
+
237
+ saved = zerogen.assets.download_to(asset_id, "downloads")
238
+ print(saved.path)
120
239
  ```
121
240
 
241
+ The `filename` is untrusted content, so don't use it as a path yourself.
242
+ `download_to` makes a name from it with no path separators or characters that
243
+ Windows refuses. When a file in the directory already has that name, it adds a
244
+ number, as in `lighthouse (1).png`, rather than overwrite the file.
245
+
122
246
  Each call reads a new signed link and sends it to storage without your API key.
123
247
  When storage refuses a link as expired, it reads a new one and tries once more.
124
248
  To hand the link to something else, read it with `assets.get_download`: it's
@@ -196,9 +320,9 @@ The client retries connection errors and errors the API marks `retryable`,
196
320
  twice by default, with backoff. For `429` responses, it waits for
197
321
  `Retry-After`, unless that's more than a minute.
198
322
 
199
- Every `POST` sends an `Idempotency-Key`, and a call's retries reuse it, so a
200
- retried create never starts a second run. To retry safely across calls or
201
- processes, pass your own key:
323
+ Every `POST` and `DELETE` sends an `Idempotency-Key`, and a call's retries reuse
324
+ it, so a retried create never starts a second run. To retry safely across calls
325
+ or processes, pass your own key:
202
326
 
203
327
  ```python
204
328
  zerogen.runs.create(request, idempotency_key=job.id)
@@ -223,11 +347,12 @@ zerogen = ZeroGen(
223
347
  | `max_retries` | `2` | Retries for each request. |
224
348
  | `timeout` | `120` | Seconds httpx waits on each step of an attempt. A request that waits on a run gets its wait added. |
225
349
  | `default_headers` | None | Headers to send with every request. |
350
+ | `user_agent` | None | Your app's name and version, such as `zerogen-nodes/0.1`, which the `User-Agent` header names before this library's. |
226
351
  | `http_client` | A new `httpx.Client` or `httpx.AsyncClient` | The httpx client to send requests with, such as one with your proxy settings. |
227
352
 
228
353
  Every method also takes request options as keyword arguments: `timeout`,
229
- `max_retries`, `headers`, and `idempotency_key` for a `POST`. Close a client
230
- you're done with, or use it as a context manager.
354
+ `max_retries`, `headers`, and `idempotency_key` for a `POST` or `DELETE`. Close
355
+ a client you're done with, or use it as a context manager.
231
356
 
232
357
  ## Test keys
233
358
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "zerogen"
3
- version = "0.2.1"
3
+ version = "0.3.0"
4
4
  description = "The official Python library for the ZeroGen API"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "zerogen"
3
- version = "0.2.1"
3
+ version = "0.3.0"
4
4
  description = "The official Python library for the ZeroGen API"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -2,11 +2,11 @@
2
2
 
3
3
  from . import types
4
4
  from ._client import AsyncZeroGen, ZeroGen
5
- from ._errors import ZeroGenConnectionError, ZeroGenError
5
+ from ._errors import WaitCancelledError, ZeroGenConnectionError, ZeroGenError
6
6
  from ._options import PostRequestOptions, RequestOptions
7
7
  from ._pagination import AsyncPage, AsyncPaginator, Page
8
8
  from ._version import __version__
9
- from .resources.assets import DownloadDestination
9
+ from .resources.assets import Download, DownloadDestination, DownloadInfo, SavedDownload
10
10
  from .resources.runs import has_ended
11
11
  from .resources.uploads import ReadyUpload, UploadSource
12
12
 
@@ -14,12 +14,16 @@ __all__ = [
14
14
  "AsyncPage",
15
15
  "AsyncPaginator",
16
16
  "AsyncZeroGen",
17
+ "Download",
17
18
  "DownloadDestination",
19
+ "DownloadInfo",
18
20
  "Page",
19
21
  "PostRequestOptions",
20
22
  "ReadyUpload",
21
23
  "RequestOptions",
24
+ "SavedDownload",
22
25
  "UploadSource",
26
+ "WaitCancelledError",
23
27
  "ZeroGen",
24
28
  "ZeroGenConnectionError",
25
29
  "ZeroGenError",
@@ -37,7 +37,7 @@ RETRY_AFTER_MAX_SECONDS = 60.0
37
37
  Result = TypeVar("Result")
38
38
  Item = TypeVar("Item")
39
39
  Query = Mapping[str, "str | int | bool | list[str] | None"]
40
- Method = Literal["GET", "POST", "PATCH", "PUT"]
40
+ Method = Literal["GET", "POST", "PATCH", "PUT", "DELETE"]
41
41
 
42
42
  _sending_to_storage: ContextVar[bool] = ContextVar("zerogen_sending_to_storage", default=False)
43
43
 
@@ -76,6 +76,7 @@ class _BaseClient:
76
76
  timeout: float,
77
77
  max_retries: int,
78
78
  default_headers: Mapping[str, str] | None,
79
+ user_agent: str | None,
79
80
  ) -> None:
80
81
  api_key = api_key if api_key is not None else _env("ZEROGEN_API_KEY")
81
82
  if not api_key:
@@ -86,6 +87,7 @@ class _BaseClient:
86
87
  self.timeout = timeout
87
88
  self.max_retries = max_retries
88
89
  self._default_headers = dict(default_headers or {})
90
+ self._user_agent = _user_agent(user_agent)
89
91
 
90
92
  def _prepare(
91
93
  self,
@@ -96,9 +98,7 @@ class _BaseClient:
96
98
  wait: int | None,
97
99
  options: RequestOptions,
98
100
  ) -> _Prepared:
99
- headers = httpx.Headers(
100
- {"Accept": "application/json", "User-Agent": f"zerogen-python/{__version__}"}
101
- )
101
+ headers = httpx.Headers({"Accept": "application/json", "User-Agent": self._user_agent})
102
102
  headers.update(self._default_headers)
103
103
  headers.update(options.get("headers") or {})
104
104
  headers["Authorization"] = f"Bearer {self._api_key}"
@@ -106,7 +106,7 @@ class _BaseClient:
106
106
  if body is not None:
107
107
  headers["Content-Type"] = "application/json"
108
108
  content = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()
109
- if method == "POST":
109
+ if method in ("POST", "DELETE"):
110
110
  key = cast("PostRequestOptions", options).get("idempotency_key")
111
111
  headers["Idempotency-Key"] = key if key is not None else str(uuid.uuid4())
112
112
  if wait is not None:
@@ -147,6 +147,7 @@ class ZeroGen(_BaseClient):
147
147
  timeout: float = 120.0,
148
148
  max_retries: int = 2,
149
149
  default_headers: Mapping[str, str] | None = None,
150
+ user_agent: str | None = None,
150
151
  http_client: httpx.Client | None = None,
151
152
  ) -> None:
152
153
  """Creates a client.
@@ -159,6 +160,8 @@ class ZeroGen(_BaseClient):
159
160
  that waits on a run gets its wait added.
160
161
  max_retries: How many times to retry a connection error or a retryable response.
161
162
  default_headers: Headers to send with every request.
163
+ user_agent: Your app's name and version, such as `"zerogen-nodes/0.1"`, which the
164
+ `User-Agent` header names before this library's.
162
165
  http_client: An `httpx.Client` to send requests with. The client doesn't close it.
163
166
  """
164
167
  super().__init__(
@@ -167,6 +170,7 @@ class ZeroGen(_BaseClient):
167
170
  timeout=timeout,
168
171
  max_retries=max_retries,
169
172
  default_headers=default_headers,
173
+ user_agent=user_agent,
170
174
  )
171
175
  self._http = http_client if http_client is not None else httpx.Client()
172
176
  self._owns_http = http_client is None
@@ -330,6 +334,7 @@ class AsyncZeroGen(_BaseClient):
330
334
  timeout: float = 120.0,
331
335
  max_retries: int = 2,
332
336
  default_headers: Mapping[str, str] | None = None,
337
+ user_agent: str | None = None,
333
338
  http_client: httpx.AsyncClient | None = None,
334
339
  ) -> None:
335
340
  """Creates a client.
@@ -342,6 +347,8 @@ class AsyncZeroGen(_BaseClient):
342
347
  that waits on a run gets its wait added.
343
348
  max_retries: How many times to retry a connection error or a retryable response.
344
349
  default_headers: Headers to send with every request.
350
+ user_agent: Your app's name and version, such as `"zerogen-nodes/0.1"`, which the
351
+ `User-Agent` header names before this library's.
345
352
  http_client: An `httpx.AsyncClient` to send requests with. The client doesn't
346
353
  close it.
347
354
  """
@@ -351,6 +358,7 @@ class AsyncZeroGen(_BaseClient):
351
358
  timeout=timeout,
352
359
  max_retries=max_retries,
353
360
  default_headers=default_headers,
361
+ user_agent=user_agent,
354
362
  )
355
363
  self._http = http_client if http_client is not None else httpx.AsyncClient()
356
364
  self._owns_http = http_client is None
@@ -497,6 +505,17 @@ def _env(name: str) -> str | None:
497
505
  return os.environ.get(name) or None
498
506
 
499
507
 
508
+ def _user_agent(product: str | None) -> str:
509
+ """The `User-Agent` header: the caller's product, if any, then this library's."""
510
+ own = f"zerogen-python/{__version__}"
511
+ product = (product or "").strip()
512
+ if not product:
513
+ return own
514
+ if any(char < " " or char == "\x7f" for char in product):
515
+ raise ValueError("user_agent can't contain line breaks or other control characters.")
516
+ return f"{product} {own}"
517
+
518
+
500
519
  def _storage_request(
501
520
  method: str,
502
521
  url: str,
@@ -81,6 +81,17 @@ class ZeroGenConnectionError(Exception):
81
81
  """The request got no response: the connection failed or the request timed out."""
82
82
 
83
83
 
84
+ class WaitCancelledError(Exception):
85
+ """`ZeroGen.runs.wait_for` stopped waiting because its `cancel` event was set. The run
86
+ keeps running; to stop it, call `runs.cancel`."""
87
+
88
+ run_id: str
89
+
90
+ def __init__(self, run_id: str) -> None:
91
+ super().__init__(f"Stopped waiting for run {run_id}; it keeps running.")
92
+ self.run_id = run_id
93
+
94
+
84
95
  def _envelope(text: str) -> dict[str, Any] | None:
85
96
  """The error in ZeroGen's envelope, when the body is one."""
86
97
  try:
@@ -18,7 +18,7 @@ class RequestOptions(TypedDict, total=False):
18
18
 
19
19
 
20
20
  class PostRequestOptions(RequestOptions, total=False):
21
- """Options that every method sending a `POST` takes as keyword arguments."""
21
+ """Options that every method sending a `POST` or `DELETE` takes as keyword arguments."""
22
22
 
23
23
  idempotency_key: str
24
24
  """Each call sends a new random key by default and reuses it on that call's retries; pass
@@ -0,0 +1 @@
1
+ __version__ = "0.3.0"