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.
- {zerogen-0.2.1 → zerogen-0.3.0}/PKG-INFO +132 -7
- {zerogen-0.2.1 → zerogen-0.3.0}/README.md +131 -6
- {zerogen-0.2.1 → zerogen-0.3.0}/pyproject.toml +1 -1
- {zerogen-0.2.1 → zerogen-0.3.0}/pyproject.toml.orig +1 -1
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/__init__.py +6 -2
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_client.py +24 -5
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_errors.py +11 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_options.py +1 -1
- zerogen-0.3.0/src/zerogen/_version.py +1 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/assets.py +314 -55
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/folders.py +162 -5
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/runs.py +87 -6
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/uploads.py +84 -3
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/__init__.py +64 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/_requests.py +174 -2
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/types/_responses.py +207 -0
- zerogen-0.2.1/src/zerogen/_version.py +0 -1
- {zerogen-0.2.1 → zerogen-0.3.0}/LICENSE +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_models.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/_pagination.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/py.typed +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/__init__.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/labels.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/models.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/naming_presets.py +0 -0
- {zerogen-0.2.1 → zerogen-0.3.0}/src/zerogen/resources/projects.py +0 -0
- {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.
|
|
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
|
|
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
|
|
230
|
-
retried create never starts a second run. To retry safely across calls
|
|
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
|
|
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
|
|
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
|
|
200
|
-
retried create never starts a second run. To retry safely across calls
|
|
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
|
|
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
|
|
|
@@ -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
|
|
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"
|