riffsdk 0.1.0__tar.gz

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

@@ -0,0 +1,27 @@
+---
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check src tests
+      - name: Run tests
+        run: uv run pytest

riffsdk-0.1.0/.github/workflows/pr-comment.yml

@@ -0,0 +1,31 @@
+---
+name: PR Install Instructions
+on:
+  pull_request:
+    types: [opened, synchronize]
+permissions:
+  pull-requests: write
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post or update install instructions
+        uses: marocchino/sticky-pull-request-comment@v3
+        with:
+          header: install-instructions
+          message: |-
+            ### Install pre-release version
+            ```bash
+            # With pip
+            pip install git+https://github.com/databutton/riff-sdk-python.git@${{ github.head_ref }}
+
+            # With uv
+            uv pip install git+https://github.com/databutton/riff-sdk-python.git@${{ github.head_ref }}
+            ```
+            Or as a dependency in `pyproject.toml`:
+            ```toml
+            dependencies = [
+                "riffsdk @ git+https://github.com/databutton/riff-sdk-python.git@${{ github.head_ref }}",
+            ]
+            ```
+            <sub>Commit: ${{ github.event.pull_request.head.sha }}</sub>

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

@@ -0,0 +1,95 @@
+---
+name: Release
+on:
+  push:
+    branches: [main]
+concurrency:
+  group: release
+  cancel-in-progress: false
+permissions:
+  contents: read
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.ref_name }}
+      - run: git reset --hard ${{ github.sha }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+      - run: uv python install 3.11
+      - run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check src tests
+      - name: Run tests
+        run: uv run pytest
+      - name: Check for new version
+        id: check
+        run: |
+          NEXT=$(uv run semantic-release version --print 2>/dev/null || true)
+          LAST=$(uv run semantic-release version --print-last-released 2>/dev/null || true)
+          echo "next=$NEXT" >> "$GITHUB_OUTPUT"
+          echo "last=$LAST" >> "$GITHUB_OUTPUT"
+          if [ -n "$NEXT" ] && [ "$NEXT" != "$LAST" ]; then
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Create version and tag
+        if: steps.check.outputs.should_release == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Stamp version, build, commit locally, tag — but don't push the commit
+          # (branch protection blocks direct pushes to main)
+          uv run semantic-release -v version --no-push --no-vcs-release
+      - name: Push tag
+        if: steps.check.outputs.should_release == 'true'
+        run: |
+          TAG="v${{ steps.check.outputs.next }}"
+          # Push only the tag — tags are not subject to branch protection
+          git push origin "$TAG"
+      - name: Create GitHub release
+        id: release
+        if: steps.check.outputs.should_release == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="v${{ steps.check.outputs.next }}"
+          uv run semantic-release -v publish --tag "$TAG"
+          echo "released=true" >> "$GITHUB_OUTPUT"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+      - name: No release needed
+        if: steps.check.outputs.should_release != 'true'
+        run: |
+          echo "No version bump detected, skipping release"
+      - name: Upload dist artifacts
+        if: steps.check.outputs.should_release == 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+  publish:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

riffsdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/

riffsdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

riffsdk-0.1.0/AGENTS.md

@@ -0,0 +1,80 @@
+# Agent guide
+
+Instructions for AI agents and human developers working on this repo.
+
+## Setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management and [mise](https://mise.jdx.dev/) as a task runner. Python commands must be run through `uv run` (or the mise tasks that wrap it) so they execute in the correct virtualenv.
+
+```bash
+uv sync --dev    # Install all dependencies including dev tools
+```
+
+## Commands
+
+Use `mise run <task>` for all common operations:
+
+| Command | What it does |
+|---|---|
+| `mise run test` | Run unit tests (`uv run pytest`) |
+| `mise run test:integration` | Run integration tests against local riff-api |
+| `mise run lint` | Lint with ruff (`uv run ruff check src tests`) |
+| `mise run lint:fix` | Lint and auto-fix |
+| `mise run format` | Format code (`uv run ruff format src tests`) |
+
+If you need to run something not covered by a mise task, prefix it with `uv run`:
+
+```bash
+uv run pytest tests/test_client.py -k "test_put" -v
+uv run ruff check --fix src
+```
+
+Do **not** run bare `pytest`, `ruff`, or `python` -- they won't use the project's virtualenv or dependencies.
+
+## Integration tests
+
+Integration tests require a running riff-api server and are skipped by default. To run them:
+
+```bash
+# Start the server first (in the riff-api repo)
+cd ../riff-api && mise run dev:local
+
+# Then run integration tests
+mise run test:integration
+```
+
+The integration test task sets `RIFF_BASE_URL=http://localhost:8080/riff-api` and `RIFF_INTEGRATION_TEST=true` automatically.
+
+## Repository structure
+
+```
+src/riffsdk/
+  __init__.py              # Public API re-exports (everything users import)
+  _internal/
+    auth.py                # RiffAuth - authentication
+    config.py              # Configuration handling
+  storage/
+    __init__.py            # Re-exports from submodules
+    _client.py             # StorageClient (sync)
+    _async_client.py       # AsyncStorageClient (async)
+    _http.py               # HTTP transport layer
+    _models.py             # Pydantic models (ObjectMeta, Scope, etc.)
+    _session.py            # Session management
+    _streaming.py          # StorageReader, StorageWriter
+    _upload.py             # ResumableUpload, AsyncResumableUpload
+    exceptions.py          # Exception hierarchy (StorageError and subclasses)
+
+tests/                     # pytest tests (mirrors src structure)
+examples/                  # Runnable example scripts
+
+.github/workflows/
+  ci.yml                   # Lint + test on PRs and main (Python 3.11/3.12/3.13)
+  release.yml              # Semantic versioning + PyPI publish on merge to main
+  pr-comment.yml           # Posts git-install instructions on PRs
+```
+
+## Conventions
+
+- **Commits**: use [conventional commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `chore:`, etc.). Versioning is automatic -- `fix:` bumps patch, `feat:` bumps minor.
+- **Underscore-prefixed modules** (`_client.py`, `_http.py`) are internal. Public API is re-exported through `__init__.py`.
+- **Tests**: unit tests run without external services. Integration tests are gated by the `RIFF_INTEGRATION_TEST` env var and skip automatically in CI.

riffsdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.0 (2026-06-01)
+
+- Initial Release

riffsdk-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@./AGENTS.md

riffsdk-0.1.0/LICENCE

@@ -0,0 +1,7 @@
+Copyright 2026 Databutton AS
+
+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.

riffsdk-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: riffsdk
+Version: 0.1.0
+Summary: Python SDK for the Riff Storage API
+License-File: LICENCE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: tenacity>=8.3

riffsdk-0.1.0/README.md

@@ -0,0 +1,113 @@
+# riffsdk
+
+Python SDK for the Riff Storage API. Provides sync and async clients for storing, retrieving, and managing objects.
+
+## Installation
+
+```bash
+uv add riffsdk
+# or
+pip install riffsdk
+```
+
+Or install from a branch (for pre-release testing):
+
+```bash
+uv add git+https://github.com/databutton/riff-sdk-python.git@main
+# or
+pip install git+https://github.com/databutton/riff-sdk-python.git@main
+```
+
+## Quick start
+
+```python
+from riffsdk.storage import StorageClient
+
+client = StorageClient()
+
+# Upload
+meta = client.put("hello.txt", "Hello, world!")
+
+# Download
+data = client.get("hello.txt")
+
+# List
+for obj in client.list("hello"):
+    print(f"{obj.key} ({obj.size} bytes)")
+
+# Delete
+client.delete("hello.txt")
+
+client.close()
+```
+
+### Async
+
+```python
+from riffsdk.storage import AsyncStorageClient
+
+async with AsyncStorageClient() as client:
+    await client.put("key", b"data", content_type="application/octet-stream")
+    data = await client.get("key")
+```
+
+## Authentication
+
+Set the `RIFF_TOKEN` environment variable. The SDK picks it up automatically.
+
+## API
+
+### Clients
+
+- `StorageClient` -- sync client
+- `AsyncStorageClient` -- async client
+
+Both support: `put`, `get`, `stat`, `exists`, `list`, `delete`, `close`, and context manager usage.
+
+### Models
+
+- `ObjectMeta` -- metadata for a stored object (key, version, size, content_type, timestamps)
+- `UploadResult`, `DownloadResult` -- operation results
+- `ListPage` -- paginated listing
+- `Scope` -- access scope (use `account_scope()`, `project_scope()`, `session_scope()`)
+
+### Uploads
+
+- `ResumableUpload` / `AsyncResumableUpload` -- multipart resumable uploads for large files
+- `StorageReader` / `StorageWriter` -- streaming read/write
+
+### Exceptions
+
+All exceptions inherit from `StorageError`:
+
+- `AuthorisationError`
+- `ObjectNotFoundError`
+- `VersionConflictError`
+- `AlreadyExistsError`
+- `LeaseConflictError`
+- `UploadNotFoundError`
+- `QuotaExceededError`
+- `PartMismatchError`
+- `StorageTransportError`
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `basic_crud.py` -- put, get, list, delete
+- `async_client.py` -- async usage with asyncio
+- `file_upload_download.py` -- file uploads with progress
+- `optimistic_concurrency.py` -- version-based conflict handling
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync --dev        # Install dependencies
+mise run test        # Run tests
+mise run lint        # Lint
+mise run format      # Format code
+```
+
+See `AGENTS.md` for full development workflow details.

riffsdk-0.1.0/examples/async_client.py

@@ -0,0 +1,32 @@
+"""Async client usage with asyncio.
+
+Requires RIFF_TOKEN environment variable to be set.
+"""
+
+import asyncio
+
+from riffsdk.storage import AsyncStorageClient
+
+
+async def main() -> None:
+    async with AsyncStorageClient() as client:
+        # Upload
+        meta = await client.put(
+            "async-demo.txt", b"async hello!", content_type="text/plain"
+        )
+        print(f"Uploaded {meta.key} (version={meta.version})")
+
+        # Read
+        data = await client.get("async-demo.txt")
+        print(f"Contents: {data.decode()}")
+
+        # List
+        async for obj in client.list("async-"):
+            print(f"  {obj.key} ({obj.size} bytes)")
+
+        # Cleanup
+        await client.delete("async-demo.txt")
+        print("Deleted async-demo.txt")
+
+
+asyncio.run(main())

riffsdk-0.1.0/examples/basic_crud.py

@@ -0,0 +1,34 @@
+"""Basic CRUD operations: put, get, list, delete.
+
+Requires RIFF_TOKEN environment variable to be set.
+"""
+
+from riffsdk.storage import StorageClient
+
+client = StorageClient()
+
+# Upload bytes
+meta = client.put("hello.txt", b"Hello, world!", content_type="text/plain")
+print(f"Uploaded {meta.key} (version={meta.version}, size={meta.size})")
+
+# Read it back
+data = client.get("hello.txt")
+print(f"Contents: {data.decode()}")
+
+# Check metadata
+meta = client.stat("hello.txt")
+print(f"Content-Type: {meta.content_type}, Updated: {meta.updated_at}")
+
+# Check existence
+print(f"Exists: {client.exists('hello.txt')}")
+print(f"Missing: {client.exists('no-such-key.txt')}")
+
+# List objects with a prefix
+for obj in client.list("hello"):
+    print(f"  {obj.key} ({obj.size} bytes)")
+
+# Delete
+client.delete("hello.txt")
+print("Deleted hello.txt")
+
+client.close()

riffsdk-0.1.0/examples/file_upload_download.py

@@ -0,0 +1,48 @@
+"""Upload and download files with progress reporting.
+
+Requires RIFF_TOKEN environment variable to be set.
+"""
+
+import tempfile
+from pathlib import Path
+
+from riffsdk.storage import StorageClient
+
+
+def show_progress(bytes_done: int, total: int) -> None:
+    pct = bytes_done * 100 // total
+    print(f"\r  {pct}% ({bytes_done}/{total} bytes)", end="", flush=True)
+
+
+with StorageClient() as client:
+    # Create a sample file
+    src = Path(tempfile.mkstemp(suffix=".bin")[1])
+    src.write_bytes(b"x" * 1_000_000)
+
+    # Upload with progress
+    print("Uploading...")
+    result = client.upload_file(
+        "example/large.bin",
+        src,
+        on_progress=show_progress,
+    )
+    print(f"\nUploaded {result.key} (version={result.version})")
+
+    # Download with progress
+    dst = Path(tempfile.mkstemp(suffix=".bin")[1])
+    print("Downloading...")
+    dl = client.download_file(
+        "example/large.bin",
+        dst,
+        on_progress=show_progress,
+    )
+    print(f"\nDownloaded {dl.key} ({dl.size} bytes)")
+
+    # Verify
+    assert src.read_bytes() == dst.read_bytes()
+    print("Content verified!")
+
+    # Cleanup
+    client.delete("example/large.bin")
+    src.unlink()
+    dst.unlink()

riffsdk-0.1.0/examples/optimistic_concurrency.py

@@ -0,0 +1,55 @@
+"""Optimistic concurrency: conditional writes, atomic update, and leases.
+
+Requires RIFF_TOKEN environment variable to be set.
+"""
+
+import json
+
+from riffsdk.storage import StorageClient
+from riffsdk.storage.exceptions import AlreadyExistsError, VersionConflictError
+
+with StorageClient() as client:
+    # -- Create-if-not-exists --
+    meta = client.put("config.json", b'{"count": 0}', if_not_exists=True)
+    print(f"Created config.json (version={meta.version})")
+
+    try:
+        client.put("config.json", b'{"count": 0}', if_not_exists=True)
+    except AlreadyExistsError:
+        print("Already exists, as expected")
+
+    # -- Conditional update (compare-and-swap) --
+    data, version = client.get_with_version("config.json")
+    config = json.loads(data)
+    config["count"] += 1
+
+    try:
+        meta = client.put(
+            "config.json",
+            json.dumps(config).encode(),
+            if_version_matches=version,
+        )
+        print(f"Updated to version {meta.version}")
+    except VersionConflictError:
+        print("Someone else modified it first!")
+
+    # -- Atomic read-modify-write with automatic retries --
+    def increment(data: bytes) -> bytes:
+        config = json.loads(data)
+        config["count"] += 1
+        return json.dumps(config).encode()
+
+    meta = client.update("config.json", increment)
+    print(f"After atomic update: version={meta.version}")
+
+    # -- Lease for exclusive access --
+    with client.lease("config.json", ttl=30) as lease:
+        print(f"Acquired lease (expires {lease.expires_at})")
+        data = client.get("config.json")
+        config = json.loads(data)
+        config["count"] += 10
+        client.put("config.json", json.dumps(config).encode())
+    print("Lease released")
+
+    # Cleanup
+    client.delete("config.json")

riffsdk-0.1.0/mise.toml

@@ -0,0 +1,24 @@
+[tools]
+python = "3.13"
+uv = "latest"
+
+[tasks.test]
+description = "Run tests"
+run = "uv run pytest"
+
+[tasks.format]
+description = "Format code"
+run = "uv run ruff format src tests"
+
+[tasks.lint]
+description = "Lint code"
+run = "uv run ruff check src tests"
+
+[tasks."lint:fix"]
+description = "Lint and auto-fix"
+run = "uv run ruff check --fix src tests"
+
+[tasks."test:integration"]
+description = "Run integration tests against local riff-api"
+env = { RIFF_BASE_URL = "http://localhost:8080/riff-api", RIFF_INTEGRATION_TEST = "true" }
+run = "uv run pytest tests/test_integration.py -v"

riffsdk-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riffsdk"
+version = "0.1.0"
+description = "Python SDK for the Riff Storage API"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27", "pydantic>=2.6", "tenacity>=8.3"]
+
+[dependency-groups]
+dev = [
+  "pytest>=9.0",
+  "pytest-asyncio>=0.25",
+  "python-semantic-release>=10.5.3",
+  "ruff>=0.15",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.semantic_release]
+commit_parser = "conventional"
+version_toml = ["pyproject.toml:project.version"]
+allow_zero_version = true
+major_on_zero = false
+build_command = """
+    uv lock --upgrade-package riffsdk
+    git add uv.lock
+    uv build
+"""
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.semantic_release.remote.token]
+env = "GH_TOKEN"
+
+[tool.semantic_release.publish]
+dist_glob_patterns = ["dist/*"]
+upload_to_vcs_release = true