Metadata-Version: 2.5
Name: edd-kernel-provider-in-memory
Version: 0.2.0a2
Summary: In-memory provider for local development and tests.
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: edd-kernel-core==0.2.0a2
Description-Content-Type: text/markdown

# edd-kernel-provider-in-memory

In-memory provider for local development and tests.

This provider implements the EDD Kernel contracts without external
infrastructure. It is useful for local development, unit tests, examples and
contract validation.

It is not a durable broker and should not be used as production storage.

## Install

```bash
uv add edd-kernel-contracts edd-kernel-provider-in-memory
```

When provider selection should be driven by configuration, install `edd-kernel-factory`
in place of the contract. It brings the contract and re-exports it:

```bash
uv add edd-kernel-factory edd-kernel-provider-in-memory
```

## Usage

```python
from edd_kernel.contracts import EddClientOptions, EddQueueNameAddress
from edd_kernel.provider_in_memory import create_in_memory_client

client = create_in_memory_client(EddClientOptions(create_if_not_exists=True))

await client.send(EddQueueNameAddress(queue_name="events"), {"type": "user.created"})


async def handler(event: object, context: object) -> None:
    await context.ack()


consumer = await client.consume(EddQueueNameAddress(queue_name="events"), handler)
await consumer.stop()
await client.close()
```

## Provider Options

- `poll_interval_ms`: idle polling interval used by the shared consumer.
- `queues`: initial queue names and JSON values, encoded when the client is created.

`InMemoryEddClient` is public, directly constructible and subclassable. Its
class-level `provider_name` is `in-memory`.

## Factory Usage

```python
from edd_kernel.factory import CreateEddClientConfig, EddProviderName, create_edd_client

client = create_edd_client(
    CreateEddClientConfig(
        provider_name=EddProviderName.IN_MEMORY,
        create_if_not_exists=True,
    )
)
```

## Addressing

`InMemoryEventTarget` and `InMemoryEventQueue` accept
`EddQueueNameAddress(queue_name=…)`, a logical name joined with `env`, `project` and
`prefix`. Any other address is refused by the type checker, and at runtime with
`EddKernelConfigurationError`.

## Behavior

`send` appends a message to the channel its `queue_name` names, creating it when
`create_if_not_exists=True`.

`consume` reads from the channel with the same name.

`ack()` marks the message as terminal.

`nack()` requeues the message for retry.

When `create_if_not_exists=False`, consuming a missing queue raises an error.
When enabled globally or through `EddConsumeOptions`, the channel is created before
the consumer starts.

## Package Boundary

This provider contains only the in-memory transport behavior. Shared
serialization, lifecycle, error handling and polling behavior live in
`edd-kernel-contracts`.
