Skip to content

Commit ba00d79

Browse files
dpkpdpkp
committed
docs: reorg/update apidocs
1 parent ef8aa48 commit ba00d79

14 files changed

Lines changed: 162 additions & 12 deletions

‎docs/apidoc/KafkaConnection.rst‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎docs/apidoc/KafkaConnectionManager.rst‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

docs/apidoc/ClusterMetadata.rst renamed to docs/apidoc/misc/ClusterMetadata.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1+
ClusterMetadata
2+
===============
3+
14
.. autoclass:: kafka.cluster.ClusterMetadata
25
:members:
6+
:undoc-members:

‎docs/apidoc/misc/IsolationLevel.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
IsolationLevel
2+
==============
3+
4+
.. autoclass:: kafka.IsolationLevel
5+
:members:
6+
:undoc-members:

docs/apidoc/OffsetAndMetadata.rst renamed to docs/apidoc/misc/OffsetAndMetadata.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
1+
OffsetAndMetadata
2+
=================
3+
14
.. autoclass:: kafka.OffsetAndMetadata
25
:members:

‎docs/apidoc/misc/OffsetSpec.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
OffsetSpec
2+
==========
3+
4+
.. autoclass:: kafka.OffsetSpec
5+
:members:
6+
:undoc-members:

docs/apidoc/TopicPartition.rst renamed to docs/apidoc/misc/TopicPartition.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
1+
TopicPartition
2+
==============
3+
14
.. autoclass:: kafka.TopicPartition
25
:members:

‎docs/apidoc/modules.rst‎

Lines changed: 86 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,92 @@
11
kafka-python API
22
****************
33

4+
The :mod:`kafka` package exposes a small set of public classes for working
5+
with Apache Kafka. The following sections group them by role; each class
6+
links to its own API reference page.
7+
8+
9+
kafka
10+
=====
11+
12+
Application code typically interacts with one of three top-level clients.
13+
Each owns a background IO thread and a shared async networking layer.
14+
15+
- :class:`~kafka.KafkaConsumer` — high-level, group-aware message consumer.
16+
Iterable, with manual or automatic offset commits, cooperative rebalance,
17+
pluggable deserializers, and transactional-read isolation.
18+
- :class:`~kafka.KafkaProducer` — high-level, asynchronous message producer.
19+
Batches records into a background sender thread, with optional
20+
idempotence, transactions, compression, and pluggable serializers.
21+
- :class:`~kafka.KafkaAdminClient` — admin operations: topic, ACL, config,
22+
consumer group, partition, quota, log-directory, and quorum management.
23+
24+
.. toctree::
25+
:maxdepth: 1
26+
:hidden:
27+
28+
KafkaConsumer <KafkaConsumer>
29+
KafkaProducer <KafkaProducer>
30+
KafkaAdminClient <KafkaAdminClient>
31+
32+
33+
kafka.net
34+
=========
35+
36+
The clients share a single async networking layer (``kafka.net``). These
37+
classes are exposed for advanced use cases — embedding the connection
38+
pool, building a custom client on top of the kafka.net event loop, or
39+
driving the protocol layer directly from the REPL.
40+
41+
- :mod:`~kafka.net.manager` — connection pool and
42+
high-level facade over the shared IO event loop. Each top-level client
43+
owns one.
44+
- :mod:`~kafka.net.connection` — per-broker async
45+
connection: state machine, request/response correlation, and SASL
46+
handshake.
47+
- :mod:`~kafka.net.transport` - Async socket I/O with write buffering,
48+
pause/resume hooks, and the asyncio-shaped protocol callback surface.
49+
- :mod:`~kafka.net.inet` - DNS lookup + non-blocking connect, plus a
50+
URL-scheme registry that resolves ``proxy_url`` to socket factories.
51+
- :mod:`~kafka.net.http_connect` - Tunnels broker connections through
52+
an HTTP CONNECT proxy (RFC 7231).
53+
- :mod:`~kafka.net.socks5` - SOCKS5 client with optional username/password
54+
authentication.
55+
56+
.. toctree::
57+
:maxdepth: 1
58+
:hidden:
59+
60+
manager <net/manager>
61+
connection <net/connection>
62+
transport <net/transport>
63+
inet <net/inet>
64+
http_connect <net/http_connect>
65+
socks5 <net/socks5>
66+
67+
68+
other / misc
69+
============
70+
71+
Lightweight data types used throughout the client APIs (and useful when
72+
working with the lower-level protocol layer).
73+
74+
- :class:`~kafka.cluster.ClusterMetadata` — in-memory cache of brokers,
75+
topics, partitions, and the active controller. Refreshes itself on the
76+
shared IO thread.
77+
- :class:`~kafka.TopicPartition` — namedtuple identifying a partition as
78+
``(topic, partition)``.
79+
- :class:`~kafka.OffsetAndMetadata` — committed-offset record
80+
``(offset, metadata, leader_epoch)``.
81+
- :class:`~kafka.OffsetSpec` - enum for partition offset queries.
82+
- :class:`~kafka.IsolationLevel` - enum for transactional isolation.
83+
484
.. toctree::
585
:maxdepth: 1
86+
:hidden:
687

7-
KafkaConsumer
8-
KafkaProducer
9-
KafkaAdminClient
10-
KafkaConnectionManager
11-
KafkaConnection
12-
ClusterMetadata
13-
OffsetAndMetadata
14-
TopicPartition
88+
ClusterMetadata <misc/ClusterMetadata>
89+
TopicPartition <misc/TopicPartition>
90+
OffsetAndMetadata <misc/OffsetAndMetadata>
91+
OffsetSpec <misc/OffsetSpec>
92+
IsolationLevel <misc/IsolationLevel>

‎docs/apidoc/net/connection.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
kafka.net.connection
2+
====================
3+
4+
.. module:: kafka.net.connection
5+
6+
.. autoclass:: kafka.net.connection.KafkaConnection
7+
:members:
8+
:undoc-members:

‎docs/apidoc/net/http_connect.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
kafka.net.http_connect
2+
======================
3+
4+
.. module:: kafka.net.http_connect
5+
6+
.. autoclass:: kafka.net.http_connect.HttpConnectProxy
7+
:members:
8+
:undoc-members:

0 commit comments

Comments
 (0)