Metadata-Version: 2.5
Name: storage-kernel-core
Version: 0.1.0a4
Summary: Shared Storage Kernel implementation: paths, streams, observability and error normalization.
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/core
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
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_provider_error

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

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

## What it provides

| Module                | Responsibility                                                       |
| --------------------- | -------------------------------------------------------------------- |
| `options`             | client option defaults, location and overwrite resolution            |
| `path`                | portable path normalization, traversal rejection, path and URL joins |
| `text`                | text encoding and line handling                                      |
| `content_type`        | content type inferred from the path extension                        |
| `directory`           | recursive and non-recursive directory entry selection                |
| `streams`             | the readable stream providers return, the shared `send_stream`, stream collection, buffered upload stream |
| `logging`             | one log line written to the logger's method for its level            |
| `error_normalization` | provider failures mapped onto the kernel error contract              |
| `client_behavior`     | client decoration with observability and error normalization         |

## 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
