riffsdk

Python SDK for the Riff Storage API. Provides sync and async clients for storing, retrieving, and managing objects.

Installation

uv add riffsdk
# or
pip install riffsdk

Or install from a branch (for pre-release testing):

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

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

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.

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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for martinal from gravatar.com martinal

Credits

Author: Martin Sandve Alnæs

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

riffsdk-0.16.1.tar.gz (108.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

riffsdk-0.16.1-py3-none-any.whl (36.7 kB view details)

Uploaded Python 3

File details

Details for the file riffsdk-0.16.1.tar.gz.

File metadata

  • Download URL: riffsdk-0.16.1.tar.gz
  • Upload date:
  • Size: 108.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for riffsdk-0.16.1.tar.gz
Algorithm Hash digest
SHA256 3e3e5e9a2cdde04aee73cc62cac7a0c8b801637ee56cdc5bf0fd72e95b6427b5
MD5 ff48037892879b49ceb8e97995549065
BLAKE2b-256 af7461f9209740ab876dbb95a6ff9c190474ef90d9e36d03c0dffb347289832e

See more details on using hashes here.

Provenance

The following attestation bundles were made for riffsdk-0.16.1.tar.gz:

Publisher: release.yml on databutton/riff-sdk-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file riffsdk-0.16.1-py3-none-any.whl.

File metadata

  • Download URL: riffsdk-0.16.1-py3-none-any.whl
  • Upload date:
  • Size: 36.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for riffsdk-0.16.1-py3-none-any.whl
Algorithm Hash digest
SHA256 42e1be38e4d060b9d9c092a3e52d56fc1d7d59d9f87dca38944eda81cd22479d
MD5 32c8964795237b4c95001c768a49f71f
BLAKE2b-256 0bd84f4fbec89ce4f76b01c89da73cc673bc787d7640801b39ec50dd4c0a0656

See more details on using hashes here.

Provenance

The following attestation bundles were made for riffsdk-0.16.1-py3-none-any.whl:

Publisher: release.yml on databutton/riff-sdk-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page