pixelvault 0.1.0__py3-none-any.whl

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/_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/_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)
+

pixelvault/client.py

@@ -0,0 +1,374 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional
+
+import httpx
+
+from . import _resources as r
+from ._core import (
+    DEFAULT_BASE_URL,
+    FileInput,
+    Request,
+    backoff,
+    error_from,
+    headers_for,
+    network_error,
+    resolve_api_key,
+    retryable,
+)
+from .errors import PixelVaultError
+from .types import (
+    ApiKey,
+    CreatedKey,
+    DeviceLoginResult,
+    Image,
+    ImagePage,
+    JsonDict,
+    SignedUrl,
+    Usage,
+)
+
+
+class _Config:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+
+    def build(self, http: Any, req: Request) -> httpx.Request:
+        built: httpx.Request = http.build_request(
+            req.method,
+            self.base_url + req.path,
+            params=req.params or None,
+            json=req.json,
+            files=req.files,
+            data=req.data,
+            headers=headers_for(self.api_key, req),
+            timeout=self.timeout,
+        )
+        return built
+
+
+def _body(res: httpx.Response) -> Dict[str, Any]:
+    body: Dict[str, Any] = res.json()
+    return body
+
+
+class PixelVault:
+    """Synchronous client. Use as a context manager or call :meth:`close`."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._cfg = _Config(api_key, base_url, max_retries, timeout)
+        self._http = http_client or httpx.Client()
+        self.images = _Images(self)
+        self.usage = _Usage(self)
+        self.keys = _Keys(self)
+
+    def __enter__(self) -> "PixelVault":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _send(self, req: Request) -> Dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                res = self._http.send(self._cfg.build(self._http, req))
+            except httpx.HTTPError as exc:
+                if attempt < self._cfg.max_retries and req.method in ("GET", "DELETE"):
+                    time.sleep(backoff(attempt, None) or 0)
+                    attempt += 1
+                    continue
+                raise network_error(exc) from exc
+            if res.is_success:
+                return _body(res)
+            if attempt < self._cfg.max_retries and retryable(req.method, res.status_code):
+                wait = backoff(attempt, res)
+                if wait is not None:
+                    time.sleep(wait)
+                    attempt += 1
+                    continue
+            raise error_from(res)
+
+    def register(self, email: str, password: Optional[str] = None) -> JsonDict:
+        """Create an account. Returns a first live API key once; store it."""
+        return r.data(self._send(r.register(email, password)))  # type: ignore[no-any-return]
+
+    def device_login_start(self, email: str) -> None:
+        """Step 1 of device login: email a one-time code."""
+        self._send(r.device_start(email))
+
+    def device_login_complete(
+        self,
+        email: str,
+        code: str,
+        *,
+        label: Optional[str] = None,
+        replace_existing: Optional[bool] = None,
+    ) -> DeviceLoginResult:
+        """Step 2: trade the emailed code for an API key (shown once)."""
+        return r.data(  # type: ignore[no-any-return]
+            self._send(r.device_complete(email, code, label, replace_existing))
+        )
+
+
+class _Images:
+    def __init__(self, c: PixelVault) -> None:
+        self._c = c
+
+    def upload(
+        self,
+        file: Optional[FileInput] = None,
+        *,
+        url: Optional[str] = None,
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+        folder: Optional[str] = None,
+        visibility: Optional[str] = None,
+        sign_expires_in: Optional[int] = None,
+        expires_in: Optional[int] = None,
+    ) -> Image:
+        """Upload bytes, a path or a file object, or import a remote ``url``.
+
+        Without an API key the upload is anonymous and expires after 30 days.
+        """
+        req = r.upload(
+            file=file,
+            url=url,
+            filename=filename,
+            content_type=content_type,
+            folder=folder,
+            visibility=visibility,
+            sign_expires_in=sign_expires_in,
+            expires_in=expires_in,
+        )
+        return r.data(self._c._send(req))  # type: ignore[no-any-return]
+
+    def upload_batch(
+        self, collection: Dict[str, Any], images: List[Dict[str, Any]]
+    ) -> JsonDict:
+        """Up to 50 images in one collection. Fields use the API's snake_case names."""
+        return r.data(self._c._send(r.batch(collection, images)))  # type: ignore[no-any-return]
+
+    def list(self, page: Optional[int] = None, per_page: Optional[int] = None) -> ImagePage:
+        return r.page(self._c._send(r.list_images(page, per_page)), page, per_page)
+
+    def list_all(self, per_page: Optional[int] = None) -> Iterator[Image]:
+        """Iterate every image across pages."""
+        page_no = 1
+        while True:
+            result = self.list(page_no, per_page)
+            yield from result["data"]
+            if not r.has_more(result, page_no):
+                return
+            page_no += 1
+
+    def get(self, image_id: str) -> Image:
+        return r.data(self._c._send(r.get_image(image_id)))  # type: ignore[no-any-return]
+
+    def delete(self, image_id: str) -> None:
+        self._c._send(r.delete_image(image_id))
+
+    def sign_url(self, image_id: str, expires_in: Optional[int] = None) -> SignedUrl:
+        """Signed URL for a private image (60-2592000 seconds, default 3600)."""
+        return r.data(self._c._send(r.sign_url(image_id, expires_in)))  # type: ignore[no-any-return]
+
+
+class _Usage:
+    def __init__(self, c: PixelVault) -> None:
+        self._c = c
+
+    def get(self) -> Usage:
+        """Plan, usage, limits and what is left this month."""
+        return r.data(self._c._send(r.get_usage()))  # type: ignore[no-any-return]
+
+
+class _Keys:
+    def __init__(self, c: PixelVault) -> None:
+        self._c = c
+
+    def list(self) -> List[ApiKey]:
+        return r.data(self._c._send(r.list_keys()))  # type: ignore[no-any-return]
+
+    def create(
+        self, label: Optional[str] = None, environment: Optional[str] = None
+    ) -> CreatedKey:
+        """Mint a secret key. The raw key is in the response once and never again."""
+        return r.data(self._c._send(r.create_key(label, environment)))  # type: ignore[no-any-return]
+
+    def revoke(self, key_id: str) -> None:
+        """Revoke a key. The key making the request cannot revoke itself."""
+        self._c._send(r.revoke_key(key_id))
+
+
+class AsyncPixelVault:
+    """Asyncio client with the same surface as :class:`PixelVault`."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._cfg = _Config(api_key, base_url, max_retries, timeout)
+        self._http = http_client or httpx.AsyncClient()
+        self.images = _AsyncImages(self)
+        self.usage = _AsyncUsage(self)
+        self.keys = _AsyncKeys(self)
+
+    async def __aenter__(self) -> "AsyncPixelVault":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _send(self, req: Request) -> Dict[str, Any]:
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.send(self._cfg.build(self._http, req))
+            except httpx.HTTPError as exc:
+                if attempt < self._cfg.max_retries and req.method in ("GET", "DELETE"):
+                    await asyncio.sleep(backoff(attempt, None) or 0)
+                    attempt += 1
+                    continue
+                raise network_error(exc) from exc
+            if res.is_success:
+                return _body(res)
+            if attempt < self._cfg.max_retries and retryable(req.method, res.status_code):
+                wait = backoff(attempt, res)
+                if wait is not None:
+                    await asyncio.sleep(wait)
+                    attempt += 1
+                    continue
+            raise error_from(res)
+
+    async def register(self, email: str, password: Optional[str] = None) -> JsonDict:
+        return r.data(await self._send(r.register(email, password)))  # type: ignore[no-any-return]
+
+    async def device_login_start(self, email: str) -> None:
+        await self._send(r.device_start(email))
+
+    async def device_login_complete(
+        self,
+        email: str,
+        code: str,
+        *,
+        label: Optional[str] = None,
+        replace_existing: Optional[bool] = None,
+    ) -> DeviceLoginResult:
+        return r.data(  # type: ignore[no-any-return]
+            await self._send(r.device_complete(email, code, label, replace_existing))
+        )
+
+
+class _AsyncImages:
+    def __init__(self, c: AsyncPixelVault) -> None:
+        self._c = c
+
+    async def upload(
+        self,
+        file: Optional[FileInput] = None,
+        *,
+        url: Optional[str] = None,
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+        folder: Optional[str] = None,
+        visibility: Optional[str] = None,
+        sign_expires_in: Optional[int] = None,
+        expires_in: Optional[int] = None,
+    ) -> Image:
+        req = r.upload(
+            file=file,
+            url=url,
+            filename=filename,
+            content_type=content_type,
+            folder=folder,
+            visibility=visibility,
+            sign_expires_in=sign_expires_in,
+            expires_in=expires_in,
+        )
+        return r.data(await self._c._send(req))  # type: ignore[no-any-return]
+
+    async def upload_batch(
+        self, collection: Dict[str, Any], images: List[Dict[str, Any]]
+    ) -> JsonDict:
+        return r.data(await self._c._send(r.batch(collection, images)))  # type: ignore[no-any-return]
+
+    async def list(
+        self, page: Optional[int] = None, per_page: Optional[int] = None
+    ) -> ImagePage:
+        return r.page(await self._c._send(r.list_images(page, per_page)), page, per_page)
+
+    async def list_all(self, per_page: Optional[int] = None) -> AsyncIterator[Image]:
+        page_no = 1
+        while True:
+            result = await self.list(page_no, per_page)
+            for image in result["data"]:
+                yield image
+            if not r.has_more(result, page_no):
+                return
+            page_no += 1
+
+    async def get(self, image_id: str) -> Image:
+        return r.data(await self._c._send(r.get_image(image_id)))  # type: ignore[no-any-return]
+
+    async def delete(self, image_id: str) -> None:
+        await self._c._send(r.delete_image(image_id))
+
+    async def sign_url(self, image_id: str, expires_in: Optional[int] = None) -> SignedUrl:
+        return r.data(await self._c._send(r.sign_url(image_id, expires_in)))  # type: ignore[no-any-return]
+
+
+class _AsyncUsage:
+    def __init__(self, c: AsyncPixelVault) -> None:
+        self._c = c
+
+    async def get(self) -> Usage:
+        return r.data(await self._c._send(r.get_usage()))  # type: ignore[no-any-return]
+
+
+class _AsyncKeys:
+    def __init__(self, c: AsyncPixelVault) -> None:
+        self._c = c
+
+    async def list(self) -> List[ApiKey]:
+        return r.data(await self._c._send(r.list_keys()))  # type: ignore[no-any-return]
+
+    async def create(
+        self, label: Optional[str] = None, environment: Optional[str] = None
+    ) -> CreatedKey:
+        return r.data(await self._c._send(r.create_key(label, environment)))  # type: ignore[no-any-return]
+
+    async def revoke(self, key_id: str) -> None:
+        await self._c._send(r.revoke_key(key_id))
+
+
+__all__ = ["PixelVault", "AsyncPixelVault", "PixelVaultError"]

pixelvault/errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PixelVaultError(Exception):
+    """Raised for every non-2xx API response and for network failures."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        #: HTTP status, or 0 when the request never got a response.
+        self.status = status
+        #: Machine-readable code from the API, e.g. ``upload_limit_reached``.
+        self.code = code
+        #: Seconds to wait before retrying, when the API sent ``Retry-After``.
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        return f"{self.message} (status={self.status}, code={self.code})"

pixelvault/types.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired
+else:  # pragma: no cover
+    from typing_extensions import NotRequired
+
+
+class Image(TypedDict):
+    id: str
+    url: str
+    mime_type: str
+    size: int
+    width: Optional[int]
+    height: Optional[int]
+    filename: str
+    folder: Optional[str]
+    created_at: str
+    #: Present only on auto-expiring uploads.
+    expires_in: NotRequired[int]
+    temporary: NotRequired[bool]
+
+
+class ListMeta(TypedDict):
+    total: int
+    page: int
+    per_page: int
+
+
+class ImagePage(TypedDict):
+    data: List[Image]
+    meta: ListMeta
+
+
+class SignedUrl(TypedDict):
+    url: str
+    expires: int
+
+
+class UsageCounts(TypedDict):
+    storage_bytes: int
+    uploads: int
+
+
+class UsageLimits(TypedDict):
+    storage_bytes: int
+    uploads_per_month: int
+    bandwidth_bytes_per_month: int
+
+
+class Usage(TypedDict):
+    plan: str
+    period: str
+    resets_at: str
+    usage: UsageCounts
+    limits: UsageLimits
+    remaining: UsageCounts
+
+
+class ApiKey(TypedDict):
+    id: str
+    type: str
+    environment: str
+    label: Optional[str]
+    key_prefix: str
+    allowed_origins: Optional[List[str]]
+    created_at: str
+    last_used_at: Optional[str]
+    #: True for the key that authenticated this request.
+    current: bool
+
+
+class CreatedKey(TypedDict):
+    id: str
+    #: The raw key. Shown only in this response.
+    api_key: str
+    type: str
+    environment: str
+    label: Optional[str]
+    created_at: str
+
+
+class DeviceLoginResult(TypedDict):
+    account_id: str
+    key_id: str
+    api_key: str
+    project_id: str
+    email: str
+    email_verified: bool
+
+
+# Registration and batch responses are passed through as plain dicts.
+JsonDict = Dict[str, Any]

pixelvault-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+pixelvault/__init__.py,sha256=jBy_xkhrxiJ892FjGm-bvzrx6sk8vjHVtbwxM03Nxfc,194
+pixelvault/_core.py,sha256=N2su2mVy6clDN-4rw6_Y9baRP-WzEG4NmPaTembck_s,4358
+pixelvault/_resources.py,sha256=NaUALtZBUFr5ZZFNQpG_KZi8yEAYff3kM3GDq3fWTMs,2823
+pixelvault/client.py,sha256=iEI0NhueQytkDyJpKARNjkQQ9M3t7l-svK6kCYiwT6c,12377
+pixelvault/errors.py,sha256=43ibr-f2rvEI2KsUT-1kMmV3T_DWDToLmb-o6NKAzOg,817
+pixelvault/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pixelvault/types.py,sha256=3RPU7YaXUWl4vDOucybTL2fyah3jksPtwGYvvKi7FMs,1825
+pixelvault-0.1.0.dist-info/METADATA,sha256=w5oygkaxc0TZ5sK2A2PILA0WHZSBV6fVLg7CYDpiPCc,3075
+pixelvault-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pixelvault-0.1.0.dist-info/licenses/LICENSE,sha256=xcPCa_hXNL9ljovcuj2WSIKfF7Vwz1m9RDmN6IEiwLA,1067
+pixelvault-0.1.0.dist-info/RECORD,,

pixelvault-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pixelvault-0.1.0.dist-info/licenses/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.