Type annotations for boto3 Kafka

Warnings

• breaking The underlying mypy-boto3-builder (version 8.12.0) has removed support for Python 3.8. Therefore, mypy-boto3-kafka no longer supports Python 3.8.
  Fix: Upgrade your Python environment to 3.9 or higher. The library specifies `requires_python: >=3.9`.
• breaking mypy-boto3-builder version 8.9.0 introduced breaking changes to `TypeDef` naming conventions. Type definitions for packed method arguments use shorter names (e.g., `CreateDistributionRequestRequestTypeDef` -> `CreateDistributionRequestTypeDef`), and conflicting `Extra` postfixes were moved (e.g., `CreateDistributionExtraRequestTypeDef` -> `CreateDistributionRequestExtraTypeDef`).
  Fix: Review explicit `TypeDef` imports and usage, updating names according to the new conventions if affected. Most users relying on IDE auto-completion for these should adapt automatically.
• gotcha This package provides only type stubs. For actual runtime functionality, you must also install and configure the `boto3` library.
  Fix: Ensure `boto3` is installed alongside `mypy-boto3-kafka` (e.g., `pip install boto3 mypy-boto3-kafka`).
• gotcha When using PyCharm, performance issues with `Literal` overloads might occur. It's recommended to disable PyCharm's internal type checker or use `boto3-stubs-lite` variants for better performance.
  Fix: For `mypy-boto3-kafka`, consider using the `types-boto3-lite[kafka]` package or disabling PyCharm's type checker and relying on an external tool like `mypy` or `pyright`.
• gotcha For Pylint compatibility and to avoid runtime dependencies on type stubs, it is common to guard imports with `if TYPE_CHECKING:` and set types to `object` in the `else` branch. Pylint might otherwise complain about undefined variables.
  Fix: Use a pattern like: ```python from typing import TYPE_CHECKING if TYPE_CHECKING: from mypy_boto3_kafka import KafkaClient else: KafkaClient = object # Use KafkaClient ```

Install

• pip install mypy-boto3-kafka Install specific Kafka service stubs
• pip install boto3-stubs[kafka] Install Kafka stubs as part of boto3-stubs extras

Imports

• KafkaClient

  from mypy_boto3_kafka import KafkaClient

  Import the specific client type for Kafka service.
• AmazonMskClusterTypeDef

  from mypy_boto3_kafka.type_defs import AmazonMskClusterTypeDef

  Import specific TypedDicts for request/response bodies.
• BrokerAZDistributionType

  from mypy_boto3_kafka.literals import BrokerAZDistributionType

  Import specific Literal types for allowed string values.

Quickstart

Demonstrates how to import and use the KafkaClient type stub with a standard boto3 session to get type-hinted AWS MSK operations.

import os
import boto3
from mypy_boto3_kafka import KafkaClient

# Ensure boto3 is configured, e.g., via AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME env vars

region = os.environ.get('AWS_REGION_NAME', 'us-east-1')

def get_kafka_client() -> KafkaClient:
    session = boto3.Session(region_name=region)
    client: KafkaClient = session.client('kafka')
    return client

kafka_client = get_kafka_client()
response = kafka_client.list_clusters_v2()

print(f"Kafka Clusters: {response.get('ClusterInfoList')}")