Metadata-Version: 2.5
Name: edd-kernel-core
Version: 0.2.0a2
Summary: Shared EDD Kernel implementation: options, serialization, polling, lifecycle, observability and error normalization.
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: edd-kernel-contracts==0.2.0a2
Requires-Dist: uuid6>=2025.0.0
Description-Content-Type: text/markdown

# edd-kernel-core

Shared EDD Kernel implementation: client option validation, message
serialization, polling consumers, client lifecycle, observability and provider
error normalization.

This distribution belongs to the EDD Kernel package family. It sits
between `edd-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 an EDD client or catch EDD errors, depend on
`edd-kernel-contracts` alone.

## Install

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

## Usage

```python
from edd_kernel.contracts import EddClientOptions
from edd_kernel.core import normalize_client_options, run_provider_operation

options = normalize_client_options(EddClientOptions(concurrency=4))

# No raw SDK failure leaves here: it comes back as a kernel error carrying the
# provider, the target and the original object in ``cause``.
await run_provider_operation(lambda: publish(payload), "aws-sqs", "orders")
```

## What it provides

| Module                | Responsibility                                                 |
| --------------------- | -------------------------------------------------------------- |
| `options`             | client, consume and queue option normalization                  |
| `serialization`       | JSON and raw message serialization and idempotency keys         |
| `polling`             | the shared polling consumer used by pull-based providers        |
| `lifecycle`           | client lifecycle, consumer tracking and close semantics         |
| `logging`             | logger-aware event emission                                     |
| `error_normalization` | provider failures mapped onto the kernel error contract         |

## Error normalization

Target-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`, `target` and `code`, with
the original exception preserved in `cause`.

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

## License

MIT
