Metadata-Version: 2.4
Name: typedkafka
Version: 0.6.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 comprehensive docstrings on every public method
- JSON, string, bytes, Protobuf, and Avro/Schema Registry serialization
- Transaction support with context managers
- Async producer and consumer (`asyncio`) with batch consumption
- Retry utilities with exponential backoff
- OpenTelemetry tracing (`KafkaTracer`) with graceful no-op fallback
- Metrics collection and statistics tracking (`KafkaMetrics`, `KafkaStats`)
- Dead letter queue (`DeadLetterQueue`, `process_with_dlq`)
- Type-safe configuration builders with presets, validation, env loading, and security helpers
- Testing utilities (`MockProducer`, `MockConsumer`, `MockDeadLetterQueue`) with full API parity
- Structured exception hierarchy with error context
- Admin client for topic management
- Consumer offset management, batch polling, and message headers

## Why typedkafka?

confluent-kafka is fast and reliable, but working with it in Python often means guessing at argument types, cross-referencing C library docs, and getting cryptic error messages. typedkafka fixes that:

- **IDE autocomplete that works** — full type hints and parameter docs on every method, so you're not guessing at argument types or return values
- **Clear error messages** — a proper exception hierarchy instead of cryptic confluent-kafka errors
- **Test without a broker** — MockProducer and MockConsumer let you write unit tests without Docker or flaky integration setups
- **Less boilerplate** — transactions, async, retry, and serialization are built in instead of requiring manual wiring

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