Metadata-Version: 2.4
Name: typedkafka
Version: 0.7.0
Summary: A well-documented, fully type-hinted Kafka client for Python
Project-URL: Homepage, https://github.com/Jgprog117/typedkafka
Project-URL: Documentation, https://Jgprog117.github.io/typedkafka
Project-URL: Repository, https://github.com/Jgprog117/typedkafka
Project-URL: Issues, https://github.com/Jgprog117/typedkafka/issues
Author: typedkafka contributors
License: MIT
License-File: LICENSE
Keywords: confluent-kafka,consumer,documentation,event-driven,kafka,messaging,producer,streaming,type-hints,typed
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
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
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: confluent-kafka>=2.0.0
Provides-Extra: all
Requires-Dist: confluent-kafka[avro]>=2.0.0; extra == 'all'
Requires-Dist: confluent-kafka[protobuf]>=2.0.0; extra == 'all'
Requires-Dist: protobuf>=4.0; extra == 'all'
Provides-Extra: avro
Requires-Dist: confluent-kafka[avro]>=2.0.0; extra == 'avro'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: protobuf
Requires-Dist: confluent-kafka[protobuf]>=2.0.0; extra == 'protobuf'
Requires-Dist: protobuf>=4.0; extra == 'protobuf'
Description-Content-Type: text/markdown

# typedkafka

A well-documented, fully type-hinted Kafka client for Python.

[![Python Version](https://img.shields.io/pypi/pyversions/typedkafka)](https://pypi.org/project/typedkafka/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

typedkafka provides a modern Python interface to Apache Kafka with comprehensive documentation, full type hints, and developer-friendly features. Built on confluent-kafka for performance and reliability.

**Key Features:**
- Full type hints and IDE autocomplete on every public method
- Type-safe topics with generic serialization/deserialization
- Transactions, async, retry, and batch operations built in
- Pluggable serializers: JSON, string, Protobuf, Avro/Schema Registry
- Structured logging, metrics, OpenTelemetry tracing, and dead letter queues
- Testing mocks with full API parity — no broker needed for unit tests
- Type-safe config builders with presets, validation, and security helpers

## Why typedkafka?

confluent-kafka is fast and reliable, but its Python API lacks type hints, has sparse docs, and surfaces raw C-level errors. typedkafka wraps it with a modern, Pythonic interface:

- **Type safety** — full type hints, generic `TypedTopic[T]`, and IDE autocomplete so you catch mistakes before runtime
- **Batteries included** — transactions, async, retry, serialization, logging, metrics, and dead letter queues out of the box
- **Testable** — mock producer/consumer with full API parity; write unit tests without Docker
- **Observable** — structured logging, OpenTelemetry tracing, and metrics collection built in

## Installation

```bash
pip install typedkafka

# With Avro/Schema Registry support
pip install typedkafka[avro]

# With Protobuf support
pip install typedkafka[protobuf]

# Everything
pip install typedkafka[all]
```

Requires Python 3.9+.

## Quick Start

```python
from typedkafka import KafkaProducer

with KafkaProducer({"bootstrap.servers": "localhost:9092"}) as producer:
    producer.send("my-topic", b"Hello, Kafka!")
    producer.send_json("events", {"user_id": 123, "action": "click"})
    producer.flush()
```

```python
from typedkafka import KafkaConsumer

with KafkaConsumer({"bootstrap.servers": "localhost:9092", "group.id": "my-group"}) as consumer:
    consumer.subscribe(["my-topic"])
    for msg in consumer:
        print(msg.value_as_json())
        consumer.commit(msg)
```

### Configuration Builders

```python
from typedkafka import ProducerConfig, KafkaProducer

config = (
    ProducerConfig()
    .bootstrap_servers("broker:9093")
    .sasl_scram("user", "password")
    .acks("all")
    .compression("gzip")
    .build(validate=True)
)

producer = KafkaProducer(config)
```

See the [`examples/`](examples/) directory for more: transactions, async, retry, serializers, batch send, testing mocks, config builders, metrics, and dead letter queues.

## Development

```bash
git clone https://github.com/Jgprog117/typedkafka.git
cd typedkafka
pip install -e ".[dev]"
pytest
ruff check .
mypy src
```

## License

MIT License - see LICENSE file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for the full release history.
