Metadata-Version: 2.5
Name: storage-kernel-contracts
Version: 0.1.0a4
Summary: Provider-agnostic contracts for Storage Kernel.
Project-URL: Homepage, https://storage-kernel.foggia.zip/?code=py
Project-URL: Documentation, https://storage-kernel.foggia.zip/?code=py
Project-URL: Source, https://github.com/brunnofoggia/storage-kernel-py/tree/main/packages/contracts
Project-URL: Changelog, https://storage-kernel.foggia.zip/?code=py#changelog
Project-URL: Issues, https://github.com/brunnofoggia/storage-kernel-py/issues
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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

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