pixelvault 0.2.0__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.
- {pixelvault-0.2.0 → pixelvault-0.3.0}/PKG-INFO +4 -3
- {pixelvault-0.2.0 → pixelvault-0.3.0}/README.md +3 -2
- {pixelvault-0.2.0 → pixelvault-0.3.0}/pyproject.toml +1 -1
- {pixelvault-0.2.0 → pixelvault-0.3.0}/scripts/check_spec_coverage.py +2 -2
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/_core.py +13 -3
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/_resources.py +17 -2
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/client.py +48 -8
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/types.py +2 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/tests/test_client.py +65 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/uv.lock +1 -1
- {pixelvault-0.2.0 → pixelvault-0.3.0}/.github/workflows/ci.yml +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/.github/workflows/release.yml +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/.gitignore +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/LICENSE +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/__init__.py +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/errors.py +0 -0
- {pixelvault-0.2.0 → pixelvault-0.3.0}/src/pixelvault/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pixelvault
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Official Python SDK for PixelVault, agent-first image hosting
|
|
5
5
|
Project-URL: Homepage, https://pixelvault.dev/docs
|
|
6
6
|
Project-URL: Repository, https://github.com/pixelvault-dev/sdk-python
|
|
@@ -64,10 +64,11 @@ async with AsyncPixelVault() as pv:
|
|
|
64
64
|
|
|
65
65
|
| Call | What it does |
|
|
66
66
|
|---|---|
|
|
67
|
-
| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=)` | Upload a file or import a URL |
|
|
67
|
+
| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=, metadata=)` | Upload a file or import a URL |
|
|
68
68
|
| `images.generate(prompt, model=, folder=, visibility=, expires_in=)` | Generate an image from a prompt and host it. Credits: `flux-1-schnell` and the SDXL models 1, Leonardo 20. Free plan: 10 credits a month, `flux-1-schnell` only |
|
|
69
69
|
| `images.upload_batch(collection, images)` | Up to 50 images in one collection |
|
|
70
|
-
| `images.list(page=, per_page=)` / `images.list_all()` | One page / iterator over all images |
|
|
70
|
+
| `images.list(page=, per_page=, metadata=)` / `images.list_all(metadata=)` | One page / iterator over all images, optionally filtered by custom metadata (all pairs must match) |
|
|
71
|
+
| `images.update_metadata(id, metadata \| None)` | Replace an image's custom metadata (replaces, not merges; `None` clears) |
|
|
71
72
|
| `images.get(id)` / `images.delete(id)` | Fetch / delete one image |
|
|
72
73
|
| `images.sign_url(id, expires_in=)` | Signed URL for a private image |
|
|
73
74
|
| `usage.get()` | Plan, usage, limits and what is left this month (including generation credits) |
|
|
@@ -47,10 +47,11 @@ async with AsyncPixelVault() as pv:
|
|
|
47
47
|
|
|
48
48
|
| Call | What it does |
|
|
49
49
|
|---|---|
|
|
50
|
-
| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=)` | Upload a file or import a URL |
|
|
50
|
+
| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=, metadata=)` | Upload a file or import a URL |
|
|
51
51
|
| `images.generate(prompt, model=, folder=, visibility=, expires_in=)` | Generate an image from a prompt and host it. Credits: `flux-1-schnell` and the SDXL models 1, Leonardo 20. Free plan: 10 credits a month, `flux-1-schnell` only |
|
|
52
52
|
| `images.upload_batch(collection, images)` | Up to 50 images in one collection |
|
|
53
|
-
| `images.list(page=, per_page=)` / `images.list_all()` | One page / iterator over all images |
|
|
53
|
+
| `images.list(page=, per_page=, metadata=)` / `images.list_all(metadata=)` | One page / iterator over all images, optionally filtered by custom metadata (all pairs must match) |
|
|
54
|
+
| `images.update_metadata(id, metadata \| None)` | Replace an image's custom metadata (replaces, not merges; `None` clears) |
|
|
54
55
|
| `images.get(id)` / `images.delete(id)` | Fetch / delete one image |
|
|
55
56
|
| `images.sign_url(id, expires_in=)` | Signed URL for a private image |
|
|
56
57
|
| `usage.get()` | Plan, usage, limits and what is left this month (including generation credits) |
|
|
@@ -9,14 +9,14 @@ import sys
|
|
|
9
9
|
import urllib.request
|
|
10
10
|
|
|
11
11
|
COVERED = {
|
|
12
|
-
"upload_image", "generate_image", "batch_upload", "list_images", "get_image", "delete_image",
|
|
12
|
+
"upload_image", "generate_image", "batch_upload", "list_images", "get_image", "update_image_metadata", "delete_image",
|
|
13
13
|
"sign_image_url", "get_usage", "list_keys", "create_key", "revoke_key",
|
|
14
14
|
"register_account", "device_login_start", "device_login_complete",
|
|
15
15
|
}
|
|
16
16
|
# Not wrapped on purpose: dashboard-session endpoints, the public playground,
|
|
17
17
|
# health, and surfaces the SDK does not cover yet.
|
|
18
18
|
IGNORED = {
|
|
19
|
-
"claim_upload", "dashboard_upload", "dashboard_delete_image", "playground_upload",
|
|
19
|
+
"claim_upload", "dashboard_upload", "dashboard_delete_image", "playground_upload", "playground_generate",
|
|
20
20
|
"health_check", "serve_image",
|
|
21
21
|
# Billing: a person pays or cancels, so it is a dashboard/portal flow, not an SDK call.
|
|
22
22
|
"start_checkout", "open_billing_portal",
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
+
import json
|
|
5
6
|
import mimetypes
|
|
6
7
|
import os
|
|
7
8
|
from dataclasses import dataclass, field
|
|
@@ -12,7 +13,7 @@ import httpx
|
|
|
12
13
|
|
|
13
14
|
from .errors import PixelVaultError
|
|
14
15
|
|
|
15
|
-
__version__ = "0.
|
|
16
|
+
__version__ = "0.3.0"
|
|
16
17
|
|
|
17
18
|
DEFAULT_BASE_URL = "https://api.pixelvault.dev"
|
|
18
19
|
MAX_BACKOFF = 30.0
|
|
@@ -60,6 +61,7 @@ def upload_request(
|
|
|
60
61
|
visibility: Optional[str],
|
|
61
62
|
sign_expires_in: Optional[int],
|
|
62
63
|
expires_in: Optional[int],
|
|
64
|
+
metadata: Optional[Dict[str, Any]] = None,
|
|
63
65
|
) -> Request:
|
|
64
66
|
if (file is None) == (url is None):
|
|
65
67
|
raise ValueError("pass exactly one of `file` or `url`")
|
|
@@ -73,8 +75,13 @@ def upload_request(
|
|
|
73
75
|
}
|
|
74
76
|
)
|
|
75
77
|
|
|
78
|
+
meta = metadata if metadata else None # an empty object means "no metadata"
|
|
79
|
+
|
|
76
80
|
if url is not None:
|
|
77
|
-
|
|
81
|
+
body: Dict[str, Any] = {"url": url, **fields}
|
|
82
|
+
if meta is not None:
|
|
83
|
+
body["metadata"] = meta
|
|
84
|
+
return Request("POST", "/v1/images", json=body)
|
|
78
85
|
|
|
79
86
|
assert file is not None
|
|
80
87
|
content: bytes
|
|
@@ -93,7 +100,10 @@ def upload_request(
|
|
|
93
100
|
"POST",
|
|
94
101
|
"/v1/images",
|
|
95
102
|
files={"file": (name, content, mime)},
|
|
96
|
-
data={
|
|
103
|
+
data={
|
|
104
|
+
**{k: str(v) for k, v in fields.items()},
|
|
105
|
+
**({"metadata": json.dumps(meta)} if meta is not None else {}),
|
|
106
|
+
},
|
|
97
107
|
)
|
|
98
108
|
|
|
99
109
|
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
+
import json
|
|
5
6
|
from typing import Any, Dict, List, Optional, cast
|
|
6
7
|
from urllib.parse import quote
|
|
7
8
|
|
|
@@ -21,8 +22,22 @@ def batch(collection: Dict[str, Any], images: List[Dict[str, Any]]) -> Request:
|
|
|
21
22
|
return batch_request(collection, images)
|
|
22
23
|
|
|
23
24
|
|
|
24
|
-
def list_images(
|
|
25
|
-
|
|
25
|
+
def list_images(
|
|
26
|
+
page: Optional[int], per_page: Optional[int], metadata: Optional[Dict[str, Any]] = None
|
|
27
|
+
) -> Request:
|
|
28
|
+
params = drop_none(
|
|
29
|
+
{
|
|
30
|
+
"page": page,
|
|
31
|
+
"per_page": per_page,
|
|
32
|
+
"metadata": json.dumps(metadata) if metadata else None,
|
|
33
|
+
}
|
|
34
|
+
)
|
|
35
|
+
return Request("GET", "/v1/images", params=params)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def update_metadata(image_id: str, metadata: Optional[Dict[str, Any]]) -> Request:
|
|
39
|
+
# Not drop_none: an explicit None must reach the API as JSON null (clears it).
|
|
40
|
+
return Request("PATCH", f"/v1/images/{seg(image_id)}", json={"metadata": metadata})
|
|
26
41
|
|
|
27
42
|
|
|
28
43
|
def get_image(image_id: str) -> Request:
|
|
@@ -149,10 +149,14 @@ class _Images:
|
|
|
149
149
|
visibility: Optional[str] = None,
|
|
150
150
|
sign_expires_in: Optional[int] = None,
|
|
151
151
|
expires_in: Optional[int] = None,
|
|
152
|
+
metadata: Optional[Dict[str, Any]] = None,
|
|
152
153
|
) -> Image:
|
|
153
154
|
"""Upload bytes, a path or a file object, or import a remote ``url``.
|
|
154
155
|
|
|
155
156
|
Without an API key the upload is anonymous and expires after 30 days.
|
|
157
|
+
``metadata`` (a JSON object, up to 50 top-level keys / 4 KB) is stored with the image
|
|
158
|
+
and filterable via ``list(metadata=...)``; it needs an API key and is ignored if the
|
|
159
|
+
upload returns an existing image (use ``update_metadata``).
|
|
156
160
|
"""
|
|
157
161
|
req = r.upload(
|
|
158
162
|
file=file,
|
|
@@ -163,6 +167,7 @@ class _Images:
|
|
|
163
167
|
visibility=visibility,
|
|
164
168
|
sign_expires_in=sign_expires_in,
|
|
165
169
|
expires_in=expires_in,
|
|
170
|
+
metadata=metadata,
|
|
166
171
|
)
|
|
167
172
|
return r.data(self._c._send(req)) # type: ignore[no-any-return]
|
|
168
173
|
|
|
@@ -194,14 +199,23 @@ class _Images:
|
|
|
194
199
|
"""Up to 50 images in one collection. Fields use the API's snake_case names."""
|
|
195
200
|
return r.data(self._c._send(r.batch(collection, images))) # type: ignore[no-any-return]
|
|
196
201
|
|
|
197
|
-
def list(
|
|
198
|
-
|
|
202
|
+
def list(
|
|
203
|
+
self,
|
|
204
|
+
page: Optional[int] = None,
|
|
205
|
+
per_page: Optional[int] = None,
|
|
206
|
+
metadata: Optional[Dict[str, Any]] = None,
|
|
207
|
+
) -> ImagePage:
|
|
208
|
+
"""One page of images. ``metadata`` keeps only images whose custom metadata contains
|
|
209
|
+
every key/value given (typed match; nested objects match by containment)."""
|
|
210
|
+
return r.page(self._c._send(r.list_images(page, per_page, metadata)), page, per_page)
|
|
199
211
|
|
|
200
|
-
def list_all(
|
|
212
|
+
def list_all(
|
|
213
|
+
self, per_page: Optional[int] = None, metadata: Optional[Dict[str, Any]] = None
|
|
214
|
+
) -> Iterator[Image]:
|
|
201
215
|
"""Iterate every image across pages."""
|
|
202
216
|
page_no = 1
|
|
203
217
|
while True:
|
|
204
|
-
result = self.list(page_no, per_page)
|
|
218
|
+
result = self.list(page_no, per_page, metadata)
|
|
205
219
|
yield from result["data"]
|
|
206
220
|
if not r.has_more(result, page_no):
|
|
207
221
|
return
|
|
@@ -210,6 +224,17 @@ class _Images:
|
|
|
210
224
|
def get(self, image_id: str) -> Image:
|
|
211
225
|
return r.data(self._c._send(r.get_image(image_id))) # type: ignore[no-any-return]
|
|
212
226
|
|
|
227
|
+
def update_metadata(
|
|
228
|
+
self, image_id: str, metadata: Optional[Dict[str, Any]]
|
|
229
|
+
) -> Optional[Dict[str, Any]]:
|
|
230
|
+
"""Replace an image's custom metadata and return the stored value.
|
|
231
|
+
|
|
232
|
+
The object REPLACES the stored one (it is not merged), so send every key to keep;
|
|
233
|
+
``None`` clears it.
|
|
234
|
+
"""
|
|
235
|
+
body = self._c._send(r.update_metadata(image_id, metadata))
|
|
236
|
+
return r.data(body).get("metadata") # type: ignore[no-any-return]
|
|
237
|
+
|
|
213
238
|
def delete(self, image_id: str) -> None:
|
|
214
239
|
self._c._send(r.delete_image(image_id))
|
|
215
240
|
|
|
@@ -327,6 +352,7 @@ class _AsyncImages:
|
|
|
327
352
|
visibility: Optional[str] = None,
|
|
328
353
|
sign_expires_in: Optional[int] = None,
|
|
329
354
|
expires_in: Optional[int] = None,
|
|
355
|
+
metadata: Optional[Dict[str, Any]] = None,
|
|
330
356
|
) -> Image:
|
|
331
357
|
req = r.upload(
|
|
332
358
|
file=file,
|
|
@@ -337,6 +363,7 @@ class _AsyncImages:
|
|
|
337
363
|
visibility=visibility,
|
|
338
364
|
sign_expires_in=sign_expires_in,
|
|
339
365
|
expires_in=expires_in,
|
|
366
|
+
metadata=metadata,
|
|
340
367
|
)
|
|
341
368
|
return r.data(await self._c._send(req)) # type: ignore[no-any-return]
|
|
342
369
|
|
|
@@ -359,14 +386,21 @@ class _AsyncImages:
|
|
|
359
386
|
return r.data(await self._c._send(r.batch(collection, images))) # type: ignore[no-any-return]
|
|
360
387
|
|
|
361
388
|
async def list(
|
|
362
|
-
self,
|
|
389
|
+
self,
|
|
390
|
+
page: Optional[int] = None,
|
|
391
|
+
per_page: Optional[int] = None,
|
|
392
|
+
metadata: Optional[Dict[str, Any]] = None,
|
|
363
393
|
) -> ImagePage:
|
|
364
|
-
return r.page(
|
|
394
|
+
return r.page(
|
|
395
|
+
await self._c._send(r.list_images(page, per_page, metadata)), page, per_page
|
|
396
|
+
)
|
|
365
397
|
|
|
366
|
-
async def list_all(
|
|
398
|
+
async def list_all(
|
|
399
|
+
self, per_page: Optional[int] = None, metadata: Optional[Dict[str, Any]] = None
|
|
400
|
+
) -> AsyncIterator[Image]:
|
|
367
401
|
page_no = 1
|
|
368
402
|
while True:
|
|
369
|
-
result = await self.list(page_no, per_page)
|
|
403
|
+
result = await self.list(page_no, per_page, metadata)
|
|
370
404
|
for image in result["data"]:
|
|
371
405
|
yield image
|
|
372
406
|
if not r.has_more(result, page_no):
|
|
@@ -376,6 +410,12 @@ class _AsyncImages:
|
|
|
376
410
|
async def get(self, image_id: str) -> Image:
|
|
377
411
|
return r.data(await self._c._send(r.get_image(image_id))) # type: ignore[no-any-return]
|
|
378
412
|
|
|
413
|
+
async def update_metadata(
|
|
414
|
+
self, image_id: str, metadata: Optional[Dict[str, Any]]
|
|
415
|
+
) -> Optional[Dict[str, Any]]:
|
|
416
|
+
body = await self._c._send(r.update_metadata(image_id, metadata))
|
|
417
|
+
return r.data(body).get("metadata") # type: ignore[no-any-return]
|
|
418
|
+
|
|
379
419
|
async def delete(self, image_id: str) -> None:
|
|
380
420
|
await self._c._send(r.delete_image(image_id))
|
|
381
421
|
|
|
@@ -20,6 +20,8 @@ class Image(TypedDict):
|
|
|
20
20
|
filename: str
|
|
21
21
|
folder: Optional[str]
|
|
22
22
|
created_at: str
|
|
23
|
+
#: Custom metadata set at upload or via ``images.update_metadata``; ``None`` when unset.
|
|
24
|
+
metadata: NotRequired[Optional[Dict[str, Any]]]
|
|
23
25
|
#: Keyed public raster images: the same image as WebP/AVIF, usually far smaller.
|
|
24
26
|
optimized_url: NotRequired[str]
|
|
25
27
|
#: Present only on auto-expiring uploads.
|
|
@@ -301,3 +301,68 @@ async def test_async_generate():
|
|
|
301
301
|
img = await pv.images.generate("a mountain", visibility="private")
|
|
302
302
|
assert seen["body"] == {"prompt": "a mountain", "visibility": "private"}
|
|
303
303
|
assert img["generation"]["model"] == "flux-1-schnell"
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def test_upload_metadata_multipart_and_json():
|
|
307
|
+
seen = []
|
|
308
|
+
|
|
309
|
+
def handler(req: httpx.Request):
|
|
310
|
+
seen.append(req)
|
|
311
|
+
return httpx.Response(201, json={"data": IMG})
|
|
312
|
+
|
|
313
|
+
pv = make(handler)
|
|
314
|
+
pv.images.upload(b"\x89PNG", filename="a.png", metadata={"env": "prod", "n": 3})
|
|
315
|
+
body = seen[0].read().decode("latin-1")
|
|
316
|
+
assert 'name="metadata"' in body and '{"env": "prod", "n": 3}' in body
|
|
317
|
+
|
|
318
|
+
pv.images.upload(url="https://example.com/a.png", metadata={"a": 1})
|
|
319
|
+
assert json.loads(seen[1].content)["metadata"] == {"a": 1}
|
|
320
|
+
|
|
321
|
+
pv.images.upload(url="https://example.com/a.png", metadata={})
|
|
322
|
+
assert "metadata" not in json.loads(seen[2].content)
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def test_list_metadata_filter_param_and_list_all():
|
|
326
|
+
seen = []
|
|
327
|
+
|
|
328
|
+
def handler(req: httpx.Request):
|
|
329
|
+
seen.append(req)
|
|
330
|
+
return httpx.Response(200, json={"data": [], "meta": {"total": 0, "page": 1, "per_page": 20}})
|
|
331
|
+
|
|
332
|
+
pv = make(handler)
|
|
333
|
+
pv.images.list(metadata={"env": "prod"})
|
|
334
|
+
assert json.loads(seen[0].url.params["metadata"]) == {"env": "prod"}
|
|
335
|
+
pv.images.list(metadata={})
|
|
336
|
+
assert "metadata" not in seen[1].url.params
|
|
337
|
+
list(pv.images.list_all(metadata={"a": 1}))
|
|
338
|
+
assert json.loads(seen[2].url.params["metadata"]) == {"a": 1}
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def test_update_metadata_patches_and_clears():
|
|
342
|
+
seen = []
|
|
343
|
+
|
|
344
|
+
def handler(req: httpx.Request):
|
|
345
|
+
seen.append(req)
|
|
346
|
+
return httpx.Response(200, json={"data": {"id": "img_1", "metadata": json.loads(req.content)["metadata"]}})
|
|
347
|
+
|
|
348
|
+
pv = make(handler)
|
|
349
|
+
assert pv.images.update_metadata("img_1", {"a": 1}) == {"a": 1}
|
|
350
|
+
assert seen[0].method == "PATCH" and seen[0].url.path == "/v1/images/img_1"
|
|
351
|
+
assert pv.images.update_metadata("img_1", None) is None
|
|
352
|
+
assert json.loads(seen[1].content) == {"metadata": None}
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
@pytest.mark.asyncio
|
|
356
|
+
async def test_async_metadata_roundtrip():
|
|
357
|
+
seen = []
|
|
358
|
+
|
|
359
|
+
def handler(req: httpx.Request):
|
|
360
|
+
seen.append(req)
|
|
361
|
+
if req.method == "PATCH":
|
|
362
|
+
return httpx.Response(200, json={"data": {"id": "img_1", "metadata": {"a": 1}}})
|
|
363
|
+
return httpx.Response(200, json={"data": [], "meta": {"total": 0, "page": 1, "per_page": 20}})
|
|
364
|
+
|
|
365
|
+
pv = amake(handler)
|
|
366
|
+
await pv.images.list(metadata={"env": "prod"})
|
|
367
|
+
assert json.loads(seen[0].url.params["metadata"]) == {"env": "prod"}
|
|
368
|
+
assert await pv.images.update_metadata("img_1", {"a": 1}) == {"a": 1}
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|