pixelvault 0.1.0__tar.gz

pixelvault-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run mypy
+      - run: uv run pytest -q
+      - run: uv build
+
+  spec-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python scripts/check_spec_coverage.py

pixelvault-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing, no stored token
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Tag must match pyproject version
+        run: |
+          v="$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          test "v$v" = "${GITHUB_REF_NAME}"
+      - run: uv sync
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pixelvault-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.DS_Store

pixelvault-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixelVault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pixelvault-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: pixelvault
+Version: 0.1.0
+Summary: Official Python SDK for PixelVault, agent-first image hosting
+Project-URL: Homepage, https://pixelvault.dev/docs
+Project-URL: Repository, https://github.com/pixelvault-dev/sdk-python
+Author: PixelVault
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,image-hosting,pixelvault,sdk,upload
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# pixelvault
+
+Official Python SDK for [PixelVault](https://pixelvault.dev), agent-first image hosting.
+Sync and asyncio clients on top of `httpx`. Python 3.9+.
+
+```bash
+pip install pixelvault
+```
+
+## Quick start
+
+```python
+from pixelvault import PixelVault
+
+pv = PixelVault()  # reads PIXELVAULT_API_KEY, or pass api_key="pv_live_..."
+
+# A path, bytes or a binary file object
+image = pv.images.upload("screenshot.png")
+print(image["url"])  # https://img.pixelvault.dev/...
+
+# Import from a URL, auto-delete after one hour
+pv.images.upload(url="https://example.com/a.png", expires_in=3600)
+```
+
+With no API key at all, `images.upload(file)` makes an anonymous upload that expires after 30 days.
+
+Asyncio:
+
+```python
+from pixelvault import AsyncPixelVault
+
+async with AsyncPixelVault() as pv:
+    image = await pv.images.upload("screenshot.png")
+    async for img in pv.images.list_all():
+        print(img["id"])
+```
+
+## API
+
+| Call | What it does |
+|---|---|
+| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=)` | Upload a file or import a URL |
+| `images.upload_batch(collection, images)` | Up to 50 images in one collection |
+| `images.list(page=, per_page=)` / `images.list_all()` | One page / iterator over all images |
+| `images.get(id)` / `images.delete(id)` | Fetch / delete one image |
+| `images.sign_url(id, expires_in=)` | Signed URL for a private image |
+| `usage.get()` | Plan, usage, limits and what is left this month |
+| `keys.list()` / `keys.create(label=, environment=)` / `keys.revoke(id)` | Manage your API keys (secret keys only) |
+| `register(email)` | Create an account, returns a first key once |
+| `device_login_start(email)` + `device_login_complete(email, code)` | Passwordless key minting |
+
+## Errors and retries
+
+Every failure raises `PixelVaultError` with `.status` (0 for network errors), `.code` (for example
+`upload_limit_reached`) and `.retry_after` (seconds, when sent).
+
+```python
+from pixelvault import PixelVault, PixelVaultError
+
+try:
+    pv.images.upload("big.png")
+except PixelVaultError as err:
+    if err.code == "upload_limit_reached":
+        print(err.message)  # links to the pricing page
+```
+
+The client retries `429` (honoring `Retry-After` up to 30 seconds) and, for `GET`/`DELETE` only, `5xx` and
+network errors. Uploads are never retried after a `5xx`, so a lost response cannot create a duplicate image.
+Tune with `max_retries` (default 2) and `timeout` (seconds, default 60).
+
+## License
+
+MIT

pixelvault-0.1.0/README.md

@@ -0,0 +1,73 @@
+# pixelvault
+
+Official Python SDK for [PixelVault](https://pixelvault.dev), agent-first image hosting.
+Sync and asyncio clients on top of `httpx`. Python 3.9+.
+
+```bash
+pip install pixelvault
+```
+
+## Quick start
+
+```python
+from pixelvault import PixelVault
+
+pv = PixelVault()  # reads PIXELVAULT_API_KEY, or pass api_key="pv_live_..."
+
+# A path, bytes or a binary file object
+image = pv.images.upload("screenshot.png")
+print(image["url"])  # https://img.pixelvault.dev/...
+
+# Import from a URL, auto-delete after one hour
+pv.images.upload(url="https://example.com/a.png", expires_in=3600)
+```
+
+With no API key at all, `images.upload(file)` makes an anonymous upload that expires after 30 days.
+
+Asyncio:
+
+```python
+from pixelvault import AsyncPixelVault
+
+async with AsyncPixelVault() as pv:
+    image = await pv.images.upload("screenshot.png")
+    async for img in pv.images.list_all():
+        print(img["id"])
+```
+
+## API
+
+| Call | What it does |
+|---|---|
+| `images.upload(file \| url=, folder=, visibility=, expires_in=, sign_expires_in=)` | Upload a file or import a URL |
+| `images.upload_batch(collection, images)` | Up to 50 images in one collection |
+| `images.list(page=, per_page=)` / `images.list_all()` | One page / iterator over all images |
+| `images.get(id)` / `images.delete(id)` | Fetch / delete one image |
+| `images.sign_url(id, expires_in=)` | Signed URL for a private image |
+| `usage.get()` | Plan, usage, limits and what is left this month |
+| `keys.list()` / `keys.create(label=, environment=)` / `keys.revoke(id)` | Manage your API keys (secret keys only) |
+| `register(email)` | Create an account, returns a first key once |
+| `device_login_start(email)` + `device_login_complete(email, code)` | Passwordless key minting |
+
+## Errors and retries
+
+Every failure raises `PixelVaultError` with `.status` (0 for network errors), `.code` (for example
+`upload_limit_reached`) and `.retry_after` (seconds, when sent).
+
+```python
+from pixelvault import PixelVault, PixelVaultError
+
+try:
+    pv.images.upload("big.png")
+except PixelVaultError as err:
+    if err.code == "upload_limit_reached":
+        print(err.message)  # links to the pricing page
+```
+
+The client retries `429` (honoring `Retry-After` up to 30 seconds) and, for `GET`/`DELETE` only, `5xx` and
+network errors. Uploads are never retried after a `5xx`, so a lost response cannot create a duplicate image.
+Tune with `max_retries` (default 2) and `timeout` (seconds, default 60).
+
+## License
+
+MIT

pixelvault-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pixelvault"
+version = "0.1.0"
+description = "Official Python SDK for PixelVault, agent-first image hosting"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "PixelVault" }]
+keywords = ["pixelvault", "image-hosting", "sdk", "upload", "agent"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "typing_extensions>=4.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://pixelvault.dev/docs"
+Repository = "https://github.com/pixelvault-dev/sdk-python"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pixelvault"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+files = ["src"]

pixelvault-0.1.0/scripts/check_spec_coverage.py

@@ -0,0 +1,43 @@
+"""Fail when the live API gains an operation this SDK neither wraps nor ignores.
+
+Run in CI on every push and weekly, so an API change turns this repo red
+until someone decides whether the SDK should cover it.
+"""
+
+import json
+import sys
+import urllib.request
+
+COVERED = {
+    "upload_image", "batch_upload", "list_images", "get_image", "delete_image",
+    "sign_image_url", "get_usage", "list_keys", "create_key", "revoke_key",
+    "register_account", "device_login_start", "device_login_complete",
+}
+# Not wrapped on purpose: dashboard-session endpoints, the public playground,
+# health, and surfaces the SDK does not cover yet.
+IGNORED = {
+    "claim_upload", "dashboard_upload", "playground_upload", "health_check", "serve_image",
+    "list_collections", "get_collection", "close_collection",
+    "start_export", "get_export_job", "download_export",
+}
+
+req = urllib.request.Request(
+    "https://api.pixelvault.dev/openapi.json",
+    headers={"User-Agent": "pixelvault-sdk-python-ci"},
+)
+with urllib.request.urlopen(req) as res:
+    spec = json.load(res)
+
+live = {
+    op["operationId"]
+    for item in spec["paths"].values()
+    for op in item.values()
+    if isinstance(op, dict) and "operationId" in op
+}
+new = sorted(live - COVERED - IGNORED)
+gone = sorted(COVERED - live)
+if new or gone:
+    print(f"New operations to cover or ignore: {new}")
+    print(f"Covered operations no longer in the API: {gone}")
+    sys.exit(1)
+print(f"spec coverage ok: {len(COVERED)} covered, {len(IGNORED)} ignored")

pixelvault-0.1.0/src/pixelvault/__init__.py

@@ -0,0 +1,5 @@
+from ._core import __version__
+from .client import AsyncPixelVault, PixelVault
+from .errors import PixelVaultError
+
+__all__ = ["PixelVault", "AsyncPixelVault", "PixelVaultError", "__version__"]

pixelvault-0.1.0/src/pixelvault/_core.py

@@ -0,0 +1,144 @@
+"""Transport-independent pieces shared by the sync and async clients."""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, List, Optional, Tuple, Union
+
+import httpx
+
+from .errors import PixelVaultError
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.pixelvault.dev"
+MAX_BACKOFF = 30.0
+
+#: Bytes, a path, or a binary file object.
+FileInput = Union[bytes, bytearray, str, "os.PathLike[str]", BinaryIO]
+
+
+@dataclass
+class Request:
+    method: str
+    path: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    json: Optional[Dict[str, Any]] = None
+    files: Optional[Dict[str, Tuple[str, Any, str]]] = None
+    data: Optional[Dict[str, str]] = None
+    no_auth: bool = False
+
+
+def drop_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def resolve_api_key(api_key: Optional[str]) -> Optional[str]:
+    return api_key or os.environ.get("PIXELVAULT_API_KEY") or None
+
+
+def headers_for(api_key: Optional[str], req: Request) -> Dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "X-PixelVault-Client": f"sdk-python/{__version__}",
+    }
+    if api_key and not req.no_auth:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def upload_request(
+    *,
+    file: Optional[FileInput],
+    url: Optional[str],
+    filename: Optional[str],
+    content_type: Optional[str],
+    folder: Optional[str],
+    visibility: Optional[str],
+    sign_expires_in: Optional[int],
+    expires_in: Optional[int],
+) -> Request:
+    if (file is None) == (url is None):
+        raise ValueError("pass exactly one of `file` or `url`")
+
+    fields = drop_none(
+        {
+            "folder": folder,
+            "visibility": visibility,
+            "sign_expires_in": sign_expires_in,
+            "expires_in": expires_in,
+        }
+    )
+
+    if url is not None:
+        return Request("POST", "/v1/images", json={"url": url, **fields})
+
+    assert file is not None
+    content: bytes
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        name = filename or path.name
+        content = path.read_bytes()
+    elif isinstance(file, (bytes, bytearray)):
+        name = filename or "upload"
+        content = bytes(file)
+    else:
+        name = filename or os.path.basename(getattr(file, "name", "") or "") or "upload"
+        content = file.read()
+    mime = content_type or mimetypes.guess_type(name)[0] or "application/octet-stream"
+    return Request(
+        "POST",
+        "/v1/images",
+        files={"file": (name, content, mime)},
+        data={k: str(v) for k, v in fields.items()},
+    )
+
+
+def batch_request(collection: Dict[str, Any], images: List[Dict[str, Any]]) -> Request:
+    return Request(
+        "POST", "/v1/images/batch", json={"collection": collection, "images": images}
+    )
+
+
+def retryable(method: str, status: int) -> bool:
+    """429 is always safe to retry (rejected before running). 5xx only for
+    idempotent methods, so a lost upload response can never duplicate an image."""
+    if status == 429:
+        return True
+    return method in ("GET", "DELETE") and status >= 500
+
+
+def retry_after(res: httpx.Response) -> Optional[float]:
+    raw = res.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    return value if value >= 0 else None
+
+
+def backoff(attempt: int, res: Optional[httpx.Response]) -> Optional[float]:
+    """Seconds to sleep, or None when the wait is too long to be worth it."""
+    after = retry_after(res) if res is not None else None
+    wait = after if after is not None else 0.5 * (2**attempt)
+    return wait if wait <= MAX_BACKOFF else None
+
+
+def error_from(res: httpx.Response) -> PixelVaultError:
+    code, message = "unknown_error", f"Request failed with status {res.status_code}"
+    try:
+        err = res.json().get("error") or {}
+        code = err.get("code") or code
+        message = err.get("message") or message
+    except Exception:
+        pass
+    return PixelVaultError(message, res.status_code, code, retry_after(res))
+
+
+def network_error(exc: Exception) -> PixelVaultError:
+    return PixelVaultError(f"Network error: {exc}", 0, "network_error")

pixelvault-0.1.0/src/pixelvault/_resources.py

@@ -0,0 +1,99 @@
+"""Request builders and response parsers. No I/O lives here."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, cast
+from urllib.parse import quote
+
+from ._core import Request, batch_request, drop_none, upload_request
+from .types import ImagePage, ListMeta
+
+
+def seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+def upload(**kwargs: Any) -> Request:
+    return upload_request(**kwargs)
+
+
+def batch(collection: Dict[str, Any], images: List[Dict[str, Any]]) -> Request:
+    return batch_request(collection, images)
+
+
+def list_images(page: Optional[int], per_page: Optional[int]) -> Request:
+    return Request("GET", "/v1/images", params=drop_none({"page": page, "per_page": per_page}))
+
+
+def get_image(image_id: str) -> Request:
+    return Request("GET", f"/v1/images/{seg(image_id)}")
+
+
+def delete_image(image_id: str) -> Request:
+    return Request("DELETE", f"/v1/images/{seg(image_id)}")
+
+
+def sign_url(image_id: str, expires_in: Optional[int]) -> Request:
+    body = drop_none({"expires_in": expires_in})
+    return Request("POST", f"/v1/images/{seg(image_id)}/sign-url", json=body)
+
+
+def get_usage() -> Request:
+    return Request("GET", "/v1/usage")
+
+
+def list_keys() -> Request:
+    return Request("GET", "/v1/keys")
+
+
+def create_key(label: Optional[str], environment: Optional[str]) -> Request:
+    return Request("POST", "/v1/keys", json=drop_none({"label": label, "environment": environment}))
+
+
+def revoke_key(key_id: str) -> Request:
+    return Request("DELETE", f"/v1/keys/{seg(key_id)}")
+
+
+def register(email: str, password: Optional[str]) -> Request:
+    return Request(
+        "POST",
+        "/v1/auth/register",
+        json=drop_none({"email": email, "password": password}),
+        no_auth=True,
+    )
+
+
+def device_start(email: str) -> Request:
+    return Request("POST", "/v1/auth/device/start", json={"email": email}, no_auth=True)
+
+
+def device_complete(
+    email: str, code: str, label: Optional[str], replace_existing: Optional[bool]
+) -> Request:
+    return Request(
+        "POST",
+        "/v1/auth/device/complete",
+        json=drop_none(
+            {"email": email, "code": code, "label": label, "replace_existing": replace_existing}
+        ),
+        no_auth=True,
+    )
+
+
+def data(body: Dict[str, Any]) -> Any:
+    return body["data"]
+
+
+def page(body: Dict[str, Any], page_no: Optional[int], per_page: Optional[int]) -> ImagePage:
+    meta = cast(
+        ListMeta,
+        body.get("meta") or {"total": 0, "page": page_no or 1, "per_page": per_page or 0},
+    )
+    return {"data": body.get("data") or [], "meta": meta}
+
+
+def has_more(result: ImagePage, page_no: int) -> bool:
+    meta = result["meta"]
+    per_page = meta.get("per_page") or len(result["data"])
+    return bool(result["data"]) and page_no * per_page < meta.get("total", 0)
+