Metadata-Version: 2.5
Name: storage-kernel-core
Version: 0.1.0a1
Summary: Shared Storage Kernel implementation: paths, streams, observability and error normalization.
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: storage-kernel-contracts<0.2.0,>=0.1.0a1
Description-Content-Type: text/markdown

# storage-kernel-core

Shared Storage Kernel implementation: portable path handling, directory
selection, stream helpers, observability and provider error normalization.

This distribution belongs to the Storage Kernel package family. It sits
between `storage-kernel-contracts` and the provider distributions.

Install it when you build a provider or reuse the kernel helpers directly. If you
only need to type a storage client or catch storage errors, depend on
`storage-kernel-contracts` alone.

## Install

```bash
pip install storage-kernel-core storage-kernel-contracts
```

## Usage

```python
from storage_kernel.contracts import StoragePathNotFoundError
from storage_kernel.core import normalize_storage_path, normalize_storage_provider_error

key = normalize_storage_path("./reports//2026.csv")

try:
    read_object(key)
except Exception as error:
    raise normalize_storage_provider_error(error, "aws-s3", key) from error
```

## What it provides

| Module               | Responsibility                                                      |
| -------------------- | ------------------------------------------------------------------- |
| `utils`              | path normalization and joins, directory selection, event emission    |
| `streams`            | buffered writable stream used when multipart upload is disabled      |
| `observability`      | client decoration with lifecycle events and error normalization      |
| `error_normalization`| provider failures mapped onto the kernel error contract              |

## Error normalization

Not-found and permission failures are normalized, because a caller must branch on
them without knowing which provider is behind the contract. Every other failure
keeps the provider message and gains `provider`, `path` and `code`, with the
original exception preserved in `cause` and in the exception chain.

An exception that already is a `StorageKernelError` keeps its class and instance.
Only the context it is missing is filled in.

## License

MIT
