storage-kernel-contracts

Provider-agnostic contracts for Storage Kernel.

This package owns the portable public API: storage paths, locations, operation options, async client protocols, provider aliases, shared helpers and normalized errors.

Install

uv add storage-kernel-contracts

Usage

from storage_kernel.contracts import StorageLocation

location = StorageLocation(bucket="files", prefix="production")
path = "documents/readme.md"

Provider packages depend on this package. This package does not import provider SDKs.

Directory reads default to recursive=True and include_directories=True. A signed URL defaults to DEFAULT_SIGNED_URL_ACTION, StorageSignedUrlAction.READ, and to DEFAULT_SIGNED_URL_EXPIRES_IN_SECONDS, 900. StorageClientClass describes provider classes accepted by the generic factory. STORAGE_PROVIDER_ALIASES and STORAGE_PROVIDER_TARGET_BY_NAME are the canonical built-in registries. StorageStreamSource is what a streaming write accepts: text, bytes or an async byte iterable.

Observability

Clients write to StorageClientOptions.logger and nowhere else. Without one, or without the method for a line's level, the line is dropped, so a client with no logger is silent. logger=logging.getLogger("my-app") is a drop-in: a log line is one descriptive string, with no identifier and no context argument.

ObservedStorageClient applies the common behavior once at the public client boundary. Each line says what happened and where — Reading invoices/2026.pdf from aws-s3 bucket reports — and the two languages write the same sentences. Provider SDK paths and location metadata are not logged by this boundary.

decorate_client(client, options, provider) is the direct Python equivalent of the JavaScript client decorator. It is idempotent, preserves provider extension attributes, and lets the generic factory apply the same behavior to injected provider classes without requiring inheritance.