Metadata-Version: 2.5
Name: storage-kernel-contracts
Version: 0.1.0a1
Summary: Provider-agnostic contracts for Storage Kernel.
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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

```bash
uv add storage-kernel-contracts
```

## Usage

```python
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.
