Objectstore Client

The client is used to interface with the Objectstore backend. It handles responsibilities like transparent compression, and making sure that uploads and downloads are done as efficiently as possible.

Quick Start

from objectstore_client import Client, Usecase

client = Client("http://localhost:8888")
session = client.session(Usecase("attachments"), org=42, project=1337)

# Upload
key = session.put(b"Hello, world!")

# Download
result = session.get(key)
content = result.payload.read()

# Delete
session.delete(key)

Core Concepts

Usecases and Scopes

A Usecase represents a server-side namespace with its own configuration defaults. Its name must follow the naming rules documented on [Usecase]; invalid names raise ValueError during construction. Within a Usecase, Scopes provide further isolation — typically keyed by organization and project IDs. A Session ties a Client to a specific Usecase + Scope for operations.

Scope components form a hierarchical path, so their order matters: org=42;project=1337 and project=1337;org=42 are different scopes. We recommend using org and project as the first two components.

# Scope with org and project (recommended first components)
session = client.session(Usecase("attachments"), org=42, project=1337)

# Additional components are appended after org/project
session = client.session(Usecase("attachments"), org=42, project=1337, app_slug="email_app")

Expiration

Objects can expire automatically using Time To Live (from creation) or Time To Idle (from last access). Defaults are set at the Usecase level and can be overridden per-upload. Without an expiration policy, objects use manual expiration (no auto-deletion).

We strongly recommend setting an expiration policy on every Usecase to prevent unbounded storage growth. Choose TimeToIdle for cache-like data that should stay alive while actively used, or TimeToLive for data with a fixed retention period.

from datetime import timedelta
from objectstore_client import Usecase, TimeToIdle, TimeToLive

# Set default expiration on the Usecase
usecase = Usecase("attachments", expiration_policy=TimeToIdle(timedelta(days=30)))

# Override per-upload
session.put(b"payload", expiration_policy=TimeToLive(timedelta(hours=1)))

Use Session.extend_expiry to keep an existing object longer.

from objectstore_client import ExpiryExtensionRejected

try:
    session.extend_expiry(key, from_now=timedelta(days=30))
except ExpiryExtensionRejected:
    print("Object could not be extended")

See the Session.extend_expiry docs for target options and error handling.

Origin Tracking

We encourage setting the origin on every upload to track where the payload was originally obtained from (e.g., the IP address of the Sentry SDK or CLI). This is optional but helps with auditing and debugging.

session.put(b"payload", origin="203.0.113.42")

Compression

Uploads are compressed with Zstd by default, and downloads are transparently decompressed. The supported algorithms are "zstd" and "gzip", or "none" to disable compression. Compression can be set per-usecase or overridden per-upload:

# compress all uploads of this usecase with zstd (the default):
usecase = Usecase("my-usecase", compression="zstd")

# upload as-is and record no encoding:
session.put(video_data, compress="none")

# upload as-is, but record the encoding so that downloads still decompress:
session.put(zstd_data, precompressed="zstd")

Resumable Uploads

The client automatically uses resumable uploads when eligible and may create temporary files for spooling. See Session.put() for eligibility, configuration, and upload behavior.

Custom Metadata

Arbitrary key-value pairs can be attached to objects and retrieved on download.

session.put(b"payload", metadata={"source": "upload-service"})

Authentication

If your Objectstore instance enforces authorization, you must configure authentication via the token parameter on Client. It accepts either:

• A TokenGenerator — for internal services that have access to an EdDSA keypair. It wraps a SecretKey and signs a fresh JWT for each request, scoped to the specific usecase and scope being accessed. Its key can also sign pre-signed URLs. The generator's expiry_seconds and permissions are the defaults for every token it signs; per-token overrides can only narrow them.
• A str — a pre-signed JWT, used as-is for every request. Use this for external services that receive a token from another source.

from objectstore_client import Client, Usecase
from objectstore_client.auth import SecretKey, TokenGenerator

key = SecretKey(kid="my-service", secret_key="<private key>")

# Option 1: Internal service with a keypair
client = Client("http://localhost:8888", token=TokenGenerator(key))

# Option 2: External service with a pre-signed JWT
# Use TokenGenerator.token_for_scope() to obtain a static token from an
# internal service, then pass it to the external consumer:
from objectstore_client.scope import Scope

token = TokenGenerator(key, expiry_seconds=300).token_for_scope(
    "my_app", Scope(org=42, project=1337)
)

client = Client("http://localhost:8888", token=token)

Object URLs

Session.object_url returns a GET URL for an object. By default the URL carries no auth, so the recipient needs their own key to generate a token for it. Pass token_validity to embed a read-only token in the URL instead, valid for the given duration (requires TokenGenerator authentication - see above section).

from datetime import timedelta

url = session.object_url("my-key", token_validity=timedelta(hours=1))

Pre-signed URLs

Experimental: pre-signed URLs are an experimental feature and this API may change in a future release.

A pre-signed URL is a time-limited URL that authorizes a single request on one object without the recipient needing an auth token. This is useful for handing a download link to a browser or an external service, or for returning an HTTP redirect so that clients can download objects directly from Objectstore.

Pre-signed URLS currently only support GET and HEAD (a pre-signed URL for GET authorizes HEAD too, and viceversa), so for uploads you should use scoped JWTs, as described above.

Session.presigned_object_url signs the URL with the SecretKey of the session's TokenGenerator, so it requires a TokenGenerator and raises ValueError otherwise. Only GET and HEAD may be pre-signed, the granted permissions are those configured server-side for the signing key, and the validity may not exceed one week.

from datetime import timedelta

# The recipient can fetch this with any HTTP client, no auth header needed.
url = session.presigned_object_url("GET", "my-key", duration=timedelta(hours=1))

import urllib.request
with urllib.request.urlopen(url) as resp:
    content = resp.read()

Download response options

Both Session.object_url and Session.presigned_object_url accept a response_content_disposition option:

url = session.presigned_object_url(
    "GET",
    "my-key",
    response_content_disposition="inline",
)

Disposition accepts inline or attachment, defaulting to attachment when omitted. The stored filename is retained.

Configuration

In production, store the Client and Usecase at module level and reuse them. The following shows all available constructor options with their defaults:

from objectstore_client import Client, Usecase

client = Client(
    "http://localhost:8888",
    retries=3,               # default: 3 connect retries, no read retries
    timeout_ms=None,         # default: no read timeout (connect: 100ms)
    connection_kwargs={},    # default: empty (override urllib3.HTTPConnectionPool kwargs)
    # metrics_backend=...,   # default: no-op
    # token=...,             # see Authentication section
)

attachments = Usecase("attachments")

See the docstrings on Client, Usecase, and Session for full parameter documentation.

Tracing

When the Sentry SDK is initialized, every method that talks to Objectstore automatically emits a span, with no setup required on your side. If you also want a span for the underlying HTTP request, Sentry's StdlibIntegration covers that, it's enabled by default:

import sentry_sdk

sentry_sdk.init(
    dsn="...",
    traces_sample_rate=1.0,
    # Optional: controls which hosts get `sentry-trace`/`baggage` headers.
    # trace_propagation_targets=["http://objectstore"],
)

Development

Environment Setup

The considerations for setting up the development environment that can be found in the main README apply for this package as well.

Pre-commit hook

A configuration to set up a git pre-commit hook using pre-commit is available at the root of the repository.

To install it, run

pre-commit install

The hook will automatically run some checks before every commit, including the linters and formatters we run in CI.