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, StoragePath

location = StorageLocation(bucket="files", prefix="production")
path = StoragePath("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. StorageClientClass describes provider classes accepted by the generic factory. STORAGE_PROVIDER_ALIASES and STORAGE_PROVIDER_TARGETS are the canonical built-in registries. BufferedStorageWritableStream provides the portable in-memory writable-stream implementation.

Observability

Clients use StorageClientOptions.logger when provided. If no logger is provided and debug=True, events are emitted through Python's standard logging conventions under the storage_kernel logger. Otherwise clients are silent by default.

ObservedStorageClient applies the common behavior once at the public client boundary. Event contexts use StorageEventContext and contain provider, operation, optional logical path, optional destination_path, and an optional location limited to directory, bucket, and prefix. Provider SDK paths and location metadata are not logged by this boundary.

decorate_storage_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.