Metadata-Version: 2.3
Name: kfk_mng
Version: 1.0.0
Summary: Kafka connection manager — atomic registry with SSL/SASL support
License: MIT
Keywords: kafka,aiokafka,connection,manager,async
Author: Aleksandr Yurlov
Author-email: Sasha.yur@mail.ru
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: aiokafka (>=0.11.0,<0.12.0)
Description-Content-Type: text/markdown

# kfk_mng

Atomic Kafka connection manager. Регистрирует Kafka producers / consumers по alias, скрывает aiokafka boilerplate.

## Установка

```bash
pip install kfk_mng
```

## Возможности

- ✅ Регистрация Kafka подключений по alias
- ✅ Producer + Consumer пара (`KafkaComponents`) под одним alias
- ✅ Поддержка SSL / SASL
- ✅ Lazy start adapters (нет старта пока не вызвал send/getmany)
- ✅ Async API через `aiokafka`
- ✅ Manual offset commit по умолчанию (надёжность)

## Быстрый старт

```python
import kfk_mng

# Регистрация (один раз при старте процесса)
kfk_mng.register(
    alias="default",
    bootstrap_servers="kafka:9092",
    enable_producer=True,
    enable_consumer=True,
    consumer_topics=["events"],
    consumer_group_id="my-workers",
)

# Получение
components = kfk_mng.get("default")
producer = components.producer
consumer = components.consumer

# Использование
metadata = await producer.send(topic="events", value=b"hello")
records = await consumer.getmany(timeout_ms=1000, max_records=10)
await consumer.commit()

# Закрытие
await kfk_mng.close("default")
```

## С SSL и SASL

```python
kfk_mng.register(
    alias="prod",
    bootstrap_servers="kafka.prod:9093",
    security_protocol="SASL_SSL",
    ssl_conf={"cafile": "/path/ca.pem"},
    sasl_conf={
        "mechanism": "PLAIN",
        "username": "user",
        "password": "secret",
    },
    enable_producer=True,
)
```

## Multi-instance

```python
kfk_mng.register(alias="default", bootstrap_servers="kafka:9092", enable_producer=True)
kfk_mng.register(alias="dlq", bootstrap_servers="dlq-kafka:9092", enable_producer=True)

await kfk_mng.get("default").producer.send("events", b"x")
await kfk_mng.get("dlq").producer.send("dead-letters", b"y")
```

## Одноразовое подключение (без регистрации)

```python
components = kfk_mng.connect(
    bootstrap_servers="kafka:9092",
    enable_producer=True,
)
await components.producer.start()
# ... use ...
await components.producer.stop()
```

## API

| Функция | Описание |
|---|---|
| `register(alias, bootstrap_servers, ...)` | Зарегистрировать producer / consumer под alias |
| `get(alias)` | Вернуть `KafkaComponents` по alias |
| `connect(bootstrap_servers, ...)` | Создать `KafkaComponents` без регистрации |
| `close(alias)` | Остановить и удалить из реестра |
| `close_all()` | Остановить все зарегистрированные |

| Класс | Описание |
|---|---|
| `KafkaComponents` | dataclass с `producer` / `consumer` |
| `KafkaProducerAdapter` | Обёртка над `AIOKafkaProducer` (lazy start, send) |
| `KafkaConsumerAdapter` | Обёртка над `AIOKafkaConsumer` (lazy start, getmany, commit) |

## Сопутствующие библиотеки

- [`kafka_rpc_pubsub`](https://pypi.org/project/kafka_rpc_pubsub/) — Pydantic-typed Kafka pub/sub поверх `kfk_mng`

## License

MIT

