dbbyte 0.1.0__tar.gz → 0.2.0__tar.gz

{dbbyte-0.1.0/src/dbbyte.egg-info → dbbyte-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbbyte
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official DBByte SDK for Python
 Author: DBByte, LLC
 License: MIT
@@ -21,7 +21,7 @@ Official DBByte SDK for Python. A thin, typed wrapper over the DBByte v1 REST AP
 
 ## Status
 
-Covers object storage: upload, list, download, delete, versioning, and signed URLs. There is no bucket management, CDN cache control, or analytics API yet - those aren't part of the v1 REST API, so they aren't in the SDK.
+Covers object storage (upload, list, download, delete, versioning, signed URLs, signed upload URLs), bucket management, CDN cache purge, and Serve data APIs. There is no analytics API.
 
 ## Installation
 
@@ -161,3 +161,26 @@ except DBByteError as e:
 ## License
 
 MIT
+
+## Buckets, cache purge, upload links, and data APIs
+
+```python
+db.buckets.list()
+db.buckets.create("Media", "us-east", is_public=True)
+db.buckets.update("media", versioning_enabled=True)
+db.buckets.delete("media")
+
+# Needs a write-permission API key.
+db.cdn.purge("media", scope="file", path="logo.png")
+db.cdn.purge("media", scope="bucket")
+
+# Direct browser uploads without exposing your API key.
+link = db.objects.upload_url("media", "photo.jpg", content_type="image/jpeg", size=2_000_000)
+
+# Serve data APIs
+db.data.get("people", limit=20, filters={"city": "Oslo"})
+db.data.create("people", {"name": "Ada"})
+db.data.update("people", "record-id", {"name": "Ada L."})
+db.data.append_text("notes", "New line")
+db.data.delete("people", "record-id")
+```

{dbbyte-0.1.0 → dbbyte-0.2.0}/README.md

@@ -1,146 +1,169 @@
-# dbbyte
-
-Official DBByte SDK for Python. A thin, typed wrapper over the DBByte v1 REST API. Standard library only - no dependencies.
-
-## Status
-
-Covers object storage: upload, list, download, delete, versioning, and signed URLs. There is no bucket management, CDN cache control, or analytics API yet - those aren't part of the v1 REST API, so they aren't in the SDK.
-
-## Installation
-
-```bash
-pip install dbbyte
-```
-
-Requires Python 3.9+.
-
-## Usage
-
-```python
-import os
-from dbbyte import DBByte
-
-db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
-```
-
-| Argument | Type | Description |
-| --- | --- | --- |
-| `api_key` | `str` | Your DBByte API key. Required. |
-| `base_url` | `str` | Override the API base URL. Defaults to `https://api.dbbyte.com`. |
-| `timeout` | `float` | Request timeout in seconds. Defaults to `30.0`. |
-
-### Health check
-
-```python
-status = db.health()
-```
-
-### Upload
-
-```python
-with open("logo.png", "rb") as f:
-    body = f.read()
-
-obj = db.objects.upload(
-    "my-bucket",
-    key="images/logo.png",
-    body=body,
-    content_type="image/png",
-)
-
-# Re-uploading the same name fails with 409 unless you opt in:
-db.objects.upload("my-bucket", key="images/logo.png", body=body, overwrite=True)
-```
-
-### List
-
-```python
-result = db.objects.list("my-bucket")
-files = result["files"]
-
-# Paginate:
-next_page = db.objects.list("my-bucket", cursor=result["nextCursor"])
-```
-
-### Download
-
-```python
-result = db.objects.download("my-bucket", "images/logo.png")
-data = result["data"]  # bytes
-
-# A specific historical version:
-db.objects.download("my-bucket", "images/logo.png", version="some-version-key")
-
-# Every version, zipped:
-zip_result = db.objects.download_all_versions("my-bucket", "images/logo.png")
-```
-
-### Versions
-
-```python
-result = db.objects.versions("my-bucket", "images/logo.png")
-```
-
-### Signed URLs
-
-```python
-result = db.objects.sign("my-bucket", "images/logo.png", expires_in=3600)  # max 604800 (7 days)
-url = result["url"]
-```
-
-### Delete
-
-```python
-db.objects.delete("my-bucket", "images/logo.png")
-
-# A specific version only:
-db.objects.delete("my-bucket", "images/logo.png", version="some-version-key")
-
-# Every version, permanently:
-db.objects.delete_all_versions("my-bucket", "images/logo.png")
-```
-
-## Error handling
-
-All SDK methods raise a `DBByteError` on API errors.
-
-```python
-from dbbyte import DBByte, DBByteError
-
-db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
-
-try:
-    db.objects.download("my-bucket", "does-not-exist.png")
-except DBByteError as e:
-    print(e.status)   # e.g. 404
-    print(e.message)  # e.g. "File not found"
-    print(e.hint)     # present on some errors, e.g. upload conflicts
-```
-
-### Rate limits vs quota limits
-
-A `429` can mean two different things, and only one is worth retrying:
-
-- **Burst rate limit** - `e.retry_after` is set (seconds until you can retry). Transient, safe to retry after that delay.
-- **Plan API request quota exceeded** - `e.retry_after` is `None`. Retrying immediately won't help; you're out of quota until your billing period resets or you upgrade.
-
-```python
-except DBByteError as e:
-    if e.status == 429:
-        if e.retry_after is not None:
-            # wait e.retry_after seconds, then retry
-            pass
-        else:
-            # plan quota exceeded, don't retry blindly
-            pass
-```
-
-## Known limitations
-
-- **Upload allowed types**: the server enforces a fixed MIME type whitelist (common image, video, audio, PDF, Word, and plain-text formats). Uploading anything else returns a `400` from the server - the SDK doesn't pre-validate this client-side.
-- **50MB max file size**, enforced server-side.
-- **Synchronous only.** No async client yet.
-
-## License
-
-MIT
+# dbbyte
+
+Official DBByte SDK for Python. A thin, typed wrapper over the DBByte v1 REST API. Standard library only - no dependencies.
+
+## Status
+
+Covers object storage (upload, list, download, delete, versioning, signed URLs, signed upload URLs), bucket management, CDN cache purge, and Serve data APIs. There is no analytics API.
+
+## Installation
+
+```bash
+pip install dbbyte
+```
+
+Requires Python 3.9+.
+
+## Usage
+
+```python
+import os
+from dbbyte import DBByte
+
+db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
+```
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `api_key` | `str` | Your DBByte API key. Required. |
+| `base_url` | `str` | Override the API base URL. Defaults to `https://api.dbbyte.com`. |
+| `timeout` | `float` | Request timeout in seconds. Defaults to `30.0`. |
+
+### Health check
+
+```python
+status = db.health()
+```
+
+### Upload
+
+```python
+with open("logo.png", "rb") as f:
+    body = f.read()
+
+obj = db.objects.upload(
+    "my-bucket",
+    key="images/logo.png",
+    body=body,
+    content_type="image/png",
+)
+
+# Re-uploading the same name fails with 409 unless you opt in:
+db.objects.upload("my-bucket", key="images/logo.png", body=body, overwrite=True)
+```
+
+### List
+
+```python
+result = db.objects.list("my-bucket")
+files = result["files"]
+
+# Paginate:
+next_page = db.objects.list("my-bucket", cursor=result["nextCursor"])
+```
+
+### Download
+
+```python
+result = db.objects.download("my-bucket", "images/logo.png")
+data = result["data"]  # bytes
+
+# A specific historical version:
+db.objects.download("my-bucket", "images/logo.png", version="some-version-key")
+
+# Every version, zipped:
+zip_result = db.objects.download_all_versions("my-bucket", "images/logo.png")
+```
+
+### Versions
+
+```python
+result = db.objects.versions("my-bucket", "images/logo.png")
+```
+
+### Signed URLs
+
+```python
+result = db.objects.sign("my-bucket", "images/logo.png", expires_in=3600)  # max 604800 (7 days)
+url = result["url"]
+```
+
+### Delete
+
+```python
+db.objects.delete("my-bucket", "images/logo.png")
+
+# A specific version only:
+db.objects.delete("my-bucket", "images/logo.png", version="some-version-key")
+
+# Every version, permanently:
+db.objects.delete_all_versions("my-bucket", "images/logo.png")
+```
+
+## Error handling
+
+All SDK methods raise a `DBByteError` on API errors.
+
+```python
+from dbbyte import DBByte, DBByteError
+
+db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
+
+try:
+    db.objects.download("my-bucket", "does-not-exist.png")
+except DBByteError as e:
+    print(e.status)   # e.g. 404
+    print(e.message)  # e.g. "File not found"
+    print(e.hint)     # present on some errors, e.g. upload conflicts
+```
+
+### Rate limits vs quota limits
+
+A `429` can mean two different things, and only one is worth retrying:
+
+- **Burst rate limit** - `e.retry_after` is set (seconds until you can retry). Transient, safe to retry after that delay.
+- **Plan API request quota exceeded** - `e.retry_after` is `None`. Retrying immediately won't help; you're out of quota until your billing period resets or you upgrade.
+
+```python
+except DBByteError as e:
+    if e.status == 429:
+        if e.retry_after is not None:
+            # wait e.retry_after seconds, then retry
+            pass
+        else:
+            # plan quota exceeded, don't retry blindly
+            pass
+```
+
+## Known limitations
+
+- **Upload allowed types**: the server enforces a fixed MIME type whitelist (common image, video, audio, PDF, Word, and plain-text formats). Uploading anything else returns a `400` from the server - the SDK doesn't pre-validate this client-side.
+- **50MB max file size**, enforced server-side.
+- **Synchronous only.** No async client yet.
+
+## License
+
+MIT
+
+## Buckets, cache purge, upload links, and data APIs
+
+```python
+db.buckets.list()
+db.buckets.create("Media", "us-east", is_public=True)
+db.buckets.update("media", versioning_enabled=True)
+db.buckets.delete("media")
+
+# Needs a write-permission API key.
+db.cdn.purge("media", scope="file", path="logo.png")
+db.cdn.purge("media", scope="bucket")
+
+# Direct browser uploads without exposing your API key.
+link = db.objects.upload_url("media", "photo.jpg", content_type="image/jpeg", size=2_000_000)
+
+# Serve data APIs
+db.data.get("people", limit=20, filters={"city": "Oslo"})
+db.data.create("people", {"name": "Ada"})
+db.data.update("people", "record-id", {"name": "Ada L."})
+db.data.append_text("notes", "New line")
+db.data.delete("people", "record-id")
+```

{dbbyte-0.1.0 → dbbyte-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dbbyte"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official DBByte SDK for Python"
 readme = "README.md"
 license = { text = "MIT" }

{dbbyte-0.1.0 → dbbyte-0.2.0}/src/dbbyte/__init__.py

@@ -1,49 +1,77 @@
-from __future__ import annotations
-
-from typing import Optional
-
-from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DBByteClient
-from .errors import DBByteError
-from .objects import ObjectsResource
-from .types import (
-    DeleteResponse,
-    DownloadResult,
-    FileListItem,
-    FileVersionPreview,
-    HealthResponse,
-    ListObjectsResponse,
-    ListVersionsResponse,
-    SignedUrlResponse,
-    UploadedObject,
-    VersionEntry,
-)
-
-__all__ = [
-    "DBByte",
-    "DBByteError",
-    "HealthResponse",
-    "UploadedObject",
-    "ListObjectsResponse",
-    "FileListItem",
-    "FileVersionPreview",
-    "SignedUrlResponse",
-    "ListVersionsResponse",
-    "VersionEntry",
-    "DeleteResponse",
-    "DownloadResult",
-]
-
-
-class DBByte:
-    def __init__(
-        self,
-        api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout: float = DEFAULT_TIMEOUT,
-    ) -> None:
-        self._client = DBByteClient(api_key, base_url, timeout)
-        self.objects = ObjectsResource(self._client)
-
-    def health(self) -> HealthResponse:
-        result = self._client.request_json("GET", "/health")
-        return result  # type: ignore[no-any-return]
+from __future__ import annotations
+
+from typing import Optional
+
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DBByteClient
+from .errors import DBByteError
+from .buckets import BucketsResource
+from .cdn import CdnResource
+from .data import DataResource
+from .objects import ObjectsResource
+from .types import (
+    AppendTextResponse,
+    Bucket,
+    BucketDeleteResponse,
+    BucketListResponse,
+    BucketResponse,
+    DataDeleteResponse,
+    DataPage,
+    DataRecord,
+    DataRecordResponse,
+    PurgeResponse,
+    UploadUrlResponse,
+    DeleteResponse,
+    DownloadResult,
+    FileListItem,
+    FileVersionPreview,
+    HealthResponse,
+    ListObjectsResponse,
+    ListVersionsResponse,
+    SignedUrlResponse,
+    UploadedObject,
+    VersionEntry,
+)
+
+__all__ = [
+    "DBByte",
+    "DBByteError",
+    "HealthResponse",
+    "UploadedObject",
+    "ListObjectsResponse",
+    "FileListItem",
+    "FileVersionPreview",
+    "SignedUrlResponse",
+    "ListVersionsResponse",
+    "VersionEntry",
+    "DeleteResponse",
+    "DownloadResult",
+    "Bucket",
+    "BucketListResponse",
+    "BucketResponse",
+    "BucketDeleteResponse",
+    "PurgeResponse",
+    "DataRecord",
+    "DataPage",
+    "DataRecordResponse",
+    "AppendTextResponse",
+    "DataDeleteResponse",
+    "UploadUrlResponse",
+]
+
+
+class DBByte:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._client = DBByteClient(api_key, base_url, timeout)
+        self.buckets = BucketsResource(self._client)
+        self.cdn = CdnResource(self._client)
+        self.data = DataResource(self._client)
+        self.objects = ObjectsResource(self._client)
+
+    def health(self) -> HealthResponse:
+        result = self._client.request_json("GET", "/health")
+        return result  # type: ignore[no-any-return]

dbbyte-0.2.0/src/dbbyte/buckets.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+from .client import DBByteClient
+from .types import (
+    BucketDeleteResponse,
+    BucketListResponse,
+    BucketResponse,
+)
+
+
+class BucketsResource:
+    def __init__(self, client: DBByteClient) -> None:
+        self._client = client
+
+    def list(self) -> BucketListResponse:
+        return self._client.request_json("GET", "/buckets")  # type: ignore[no-any-return]
+
+    def get(self, slug: str) -> BucketResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "GET", f"/buckets/{quote(slug, safe='')}"
+        )
+
+    def create(
+        self,
+        name: str,
+        region: str,
+        replica_count: Optional[int] = None,
+        is_public: Optional[bool] = None,
+        cdn: Optional[bool] = None,
+    ) -> BucketResponse:
+        body: Dict[str, Any] = {"name": name, "region": region}
+        if replica_count is not None:
+            body["replicaCount"] = replica_count
+        if is_public is not None:
+            body["isPublic"] = is_public
+        if cdn is not None:
+            body["cdn"] = cdn
+        return self._client.request_json("POST", "/buckets", body=body)  # type: ignore[no-any-return]
+
+    def update(
+        self,
+        slug: str,
+        versioning_enabled: Optional[bool] = None,
+        is_public: Optional[bool] = None,
+        cdn: Optional[bool] = None,
+    ) -> BucketResponse:
+        body: Dict[str, Any] = {}
+        if versioning_enabled is not None:
+            body["versioningEnabled"] = versioning_enabled
+        if is_public is not None:
+            body["isPublic"] = is_public
+        if cdn is not None:
+            body["cdn"] = cdn
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "PATCH", f"/buckets/{quote(slug, safe='')}", body=body
+        )
+
+    def delete(self, slug: str) -> BucketDeleteResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "DELETE", f"/buckets/{quote(slug, safe='')}"
+        )

dbbyte-0.2.0/src/dbbyte/cdn.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .client import DBByteClient
+from .types import PurgeResponse
+
+
+class CdnResource:
+    def __init__(self, client: DBByteClient) -> None:
+        self._client = client
+
+    def purge(
+        self, slug: str, scope: str = "bucket", path: Optional[str] = None
+    ) -> PurgeResponse:
+        """Purge one public file (scope="file", with path) or every public
+        file in a bucket (scope="bucket"). The API key needs write
+        permission."""
+        if scope not in ("file", "bucket"):
+            raise ValueError('scope must be "file" or "bucket"')
+        if scope == "file" and not path:
+            raise ValueError('path is required when scope is "file"')
+        body: Dict[str, Any] = {"slug": slug, "scope": scope}
+        if path:
+            body["path"] = path
+        return self._client.request_json("POST", "/purge", body=body)  # type: ignore[no-any-return]

dbbyte-0.2.0/src/dbbyte/data.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from .client import DBByteClient
+from .types import (
+    AppendTextResponse,
+    DataDeleteResponse,
+    DataPage,
+    DataRecord,
+    DataRecordResponse,
+)
+
+
+def _seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+class DataResource:
+    """Serve data APIs published from CSV, JSON, or Google Docs."""
+
+    def __init__(self, client: DBByteClient) -> None:
+        self._client = client
+
+    def get(
+        self,
+        slug: str,
+        fields: Optional[List[str]] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        filters: Optional[Dict[str, str]] = None,
+    ) -> DataPage:
+        query: Dict[str, Any] = dict(filters or {})
+        if fields:
+            query["fields"] = ",".join(fields)
+        query["cursor"] = cursor
+        query["limit"] = limit
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "GET", f"/v1/data/{_seg(slug)}", query=query
+        )
+
+    def create(self, slug: str, record: DataRecord) -> DataRecordResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "POST", f"/v1/data/{_seg(slug)}", body=record
+        )
+
+    def append_text(self, slug: str, text: str) -> AppendTextResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "POST", f"/v1/data/{_seg(slug)}", body={"appendText": text}
+        )
+
+    def update(
+        self, slug: str, record_id: str, patch: DataRecord
+    ) -> DataRecordResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "PATCH", f"/v1/data/{_seg(slug)}/{_seg(record_id)}", body=patch
+        )
+
+    def delete(self, slug: str, record_id: str) -> DataDeleteResponse:
+        return self._client.request_json(  # type: ignore[no-any-return]
+            "DELETE", f"/v1/data/{_seg(slug)}/{_seg(record_id)}"
+        )