fix: correct logger type from logging.Handler to logging.Logger

[Turan Almammadov (turanalmammadov)]

Problem

Closes #1668

The documentation in docs/index.rst (and the corresponding online Kafka Client Configuration reference) documents the logger keyword argument as accepting a logging.Handler instance:

logger=logging.Handler kwarg: forward logs from the Kafka client to the provided logging.Handler instance.

However, the C implementation in src/confluent_kafka/src/confluent_kafka.c calls:

PyObject_CallMethod(h->logger, "log", "issss", level_map[level], "%s [%s] %s", fac, rd_kafka_name(rk), buf);

This is calling .log(level, msg, *args), which is a method on logging.Logger — not logging.Handler. logging.Handler exposes .emit(record), not .log(...).

The existing example code in the docs already uses logging.getLogger() (which returns a Logger), confirming the docs description was wrong.

Changes

• docs/index.rst: Changed logging.Handler → logging.Logger in the logger kwarg description. Added a clarifying note about the internal .log(level, msg, *args) call pattern.
• src/confluent_kafka/cimpl.pyi: Added import logging and explicitly typed the logger parameter as Optional[logging.Logger] in the Producer and Consumer constructor overloads. This makes IDEs and type checkers surface the correct type rather than accepting Any via **kwargs.

Testing

The fix is documentation/type-stub only — no behavioral change. The existing examples in the docs already demonstrate the correct usage.

Made with Cursor

[confluent-cla-assistant]

Please sign the Contributor License Agreement here before this PR can be approved.
❌ turanalmammadov
_{Please push an empty commit if you would like to re-run the checks to verify CLA status for all contributors.}