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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pixelvault
3
- Version: 0.2.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) |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pixelvault"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "Official Python SDK for PixelVault, agent-first image hosting"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -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.2.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
- return Request("POST", "/v1/images", json={"url": url, **fields})
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={k: str(v) for k, v in fields.items()},
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(page: Optional[int], per_page: Optional[int]) -> Request:
25
- return Request("GET", "/v1/images", params=drop_none({"page": page, "per_page": per_page}))
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(self, page: Optional[int] = None, per_page: Optional[int] = None) -> ImagePage:
198
- return r.page(self._c._send(r.list_images(page, per_page)), page, per_page)
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(self, per_page: Optional[int] = None) -> Iterator[Image]:
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, page: Optional[int] = None, per_page: Optional[int] = None
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(await self._c._send(r.list_images(page, per_page)), page, per_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(self, per_page: Optional[int] = None) -> AsyncIterator[Image]:
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}
@@ -516,7 +516,7 @@ wheels = [
516
516
 
517
517
  [[package]]
518
518
  name = "pixelvault"
519
- version = "0.2.0"
519
+ version = "0.3.0"
520
520
  source = { editable = "." }
521
521
  dependencies = [
522
522
  { name = "httpx" },
File without changes
File without changes