Skip to content

Commit 8162c2d

Browse files
rnpridgeonRyan P
rnpridgeon
authored and
Ryan P
committed
Prepare doc rendering for v1.4.0 release
1 parent c8e9d2a commit 8162c2d

File tree

10 files changed

+699
-387
lines changed

10 files changed

+699
-387
lines changed

‎confluent_kafka/deserializing_consumer.py‎

Lines changed: 45 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -43,59 +43,57 @@ class DeserializingConsumer(_ConsumerImpl):
4343
All configured callbacks are served from the application queue upon
4444
calling :py:func:`DeserializingConsumer.poll`
4545
46-
DeserializingConsumer configuration properties(* indicates required field)
47-
48-
+--------------------+-----------------+-----------------------------------------------------+
49-
| Property Name | Type | Description |
50-
+====================+=================+=====================================================+
51-
| bootstrap.servers* | str | Comma-separated list of brokers. |
52-
+--------------------+-----------------+-----------------------------------------------------+
53-
| | | Client group id string. |
54-
| group.id* | str | All clients sharing the same group.id belong to the |
55-
| | | same group. |
56-
+--------------------+-----------------+-----------------------------------------------------+
57-
| | | Callable(SerializationContext, bytes) -> obj |
58-
| key.deserializer | callable | |
59-
| | | Deserializer used for message keys. |
60-
+--------------------+-----------------+-----------------------------------------------------+
61-
| | | Callable(SerializationContext, bytes) -> obj |
62-
| value.deserializer | callable | |
63-
| | | Deserializer used for message values. |
64-
+--------------------+-----------------+-----------------------------------------------------+
65-
| | | Callable(KafkaError) |
66-
| | | |
67-
| error_cb | callable | Callback for generic/global error events. These |
68-
| | | errors are typically to be considered informational |
69-
| | | since the client will automatically try to recover. |
70-
+--------------------+-----------------+-----------------------------------------------------+
71-
| log_cb | logging.Handler | Logging handler to forward logs |
72-
+--------------------+-----------------+-----------------------------------------------------+
73-
| | | Callable(str) |
74-
| | | |
75-
| | | Callback for statistics. This callback is |
76-
| stats_cb | callable | added to the application queue every |
77-
| | | ``statistics.interval.ms`` (configured separately). |
78-
| | | The function argument is a JSON formatted str |
79-
| | | containing statistics data. |
80-
+--------------------+-----------------+-----------------------------------------------------+
81-
| | | Callable(ThrottleEvent) |
82-
| throttle_cb | callable | |
83-
| | | Callback for throttled request reporting. |
84-
+--------------------+-----------------+-----------------------------------------------------+
85-
86-
.. _See Client CONFIGURATION.md for a complete list of configuration properties:
87-
https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md
46+
Notable DeserializingConsumer configuration properties(* indicates required field)
47+
48+
+-------------------------+---------------------+-----------------------------------------------------+
49+
| Property Name | Type | Description |
50+
+=========================+=====================+=====================================================+
51+
| ``bootstrap.servers`` * | str | Comma-separated list of brokers. |
52+
+-------------------------+---------------------+-----------------------------------------------------+
53+
| | | Client group id string. |
54+
| ``group.id`` * | str | All clients sharing the same group.id belong to the |
55+
| | | same group. |
56+
+-------------------------+---------------------+-----------------------------------------------------+
57+
| | | Callable(SerializationContext, bytes) -> obj |
58+
| ``key.deserializer`` | callable | |
59+
| | | Deserializer used for message keys. |
60+
+-------------------------+---------------------+-----------------------------------------------------+
61+
| | | Callable(SerializationContext, bytes) -> obj |
62+
| ``value.deserializer`` | callable | |
63+
| | | Deserializer used for message values. |
64+
+-------------------------+---------------------+-----------------------------------------------------+
65+
| | | Callable(KafkaError) |
66+
| | | |
67+
| ``error_cb`` | callable | Callback for generic/global error events. These |
68+
| | | errors are typically to be considered informational |
69+
| | | since the client will automatically try to recover. |
70+
+-------------------------+---------------------+-----------------------------------------------------+
71+
| ``log_cb`` | ``logging.Handler`` | Logging handler to forward logs |
72+
+-------------------------+---------------------+-----------------------------------------------------+
73+
| | | Callable(str) |
74+
| | | |
75+
| | | Callback for statistics. This callback is |
76+
| ``stats_cb`` | callable | added to the application queue every |
77+
| | | ``statistics.interval.ms`` (configured separately). |
78+
| | | The function argument is a JSON formatted str |
79+
| | | containing statistics data. |
80+
+-------------------------+---------------------+-----------------------------------------------------+
81+
| | | Callable(ThrottleEvent) |
82+
| ``throttle_cb`` | callable | |
83+
| | | Callback for throttled request reporting. |
84+
+-------------------------+---------------------+-----------------------------------------------------+
85+
86+
See Also:
87+
- `CONFIGURATION.md <https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md>`_ for additional configuration property details.
88+
- `STATISTICS.md <https://github.com/edenhill/librdkafka/blob/master/STATISTICS.md>`_ for detailed information about the statistics handled by stats_cb
8889
8990
Args:
9091
conf (dict): DeserializingConsumer configuration.
9192
9293
Raises:
9394
ValueError: if configuration validation fails
9495
95-
.. _Statistics:
96-
https://github.com/edenhill/librdkafka/blob/master/STATISTICS.md
97-
98-
"""
96+
""" # noqa: E501
9997

10098
def __init__(self, conf):
10199
conf_copy = conf.copy()
@@ -154,7 +152,7 @@ def poll(self, timeout=-1):
154152

155153
def consume(self, num_messages=1, timeout=-1):
156154
"""
157-
:py:func:`Consumer.consume` not implemented,
155+
:py:func:`Consumer.consume` not implemented, use
158156
:py:func:`DeserializingConsumer.poll` instead
159157
"""
160158
raise NotImplementedError

‎confluent_kafka/schema_registry/avro.py‎

Lines changed: 29 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -73,20 +73,22 @@ class AvroSerializer(Serializer):
7373
AvroSerializer serializes objects in the Confluent Schema Registry binary
7474
format for Avro.
7575
76+
7677
AvroSerializer configuration properties:
77-
+-----------------------+----------+--------------------------------------------------+
78-
| Property Name | Type | Description |
79-
+=======================+==========+==================================================+
80-
| | | Registers schemas automatically if not |
81-
| auto.register.schemas | bool | previously associated with a particular subject. |
82-
| | | Defaults to True. |
83-
+-----------------------|----------+--------------------------------------------------+
84-
| | | Callable(SerializationContext, str) -> str |
85-
| | | |
86-
| subject.name.strategy | callable | Instructs the AvroSerializer on how to construct |
87-
| | | Schema Registry subject names. |
88-
| | | Defaults to topic_subject_name_strategy. |
89-
+-----------------------+----------+--------------------------------------------------+
78+
79+
+---------------------------+----------+--------------------------------------------------+
80+
| Property Name | Type | Description |
81+
+===========================+==========+==================================================+
82+
| | | Registers schemas automatically if not |
83+
| ``auto.register.schemas`` | bool | previously associated with a particular subject. |
84+
| | | Defaults to True. |
85+
+---------------------------+----------+--------------------------------------------------+
86+
| | | Callable(SerializationContext, str) -> str |
87+
| | | |
88+
| ``subject.name.strategy`` | callable | Instructs the AvroSerializer on how to construct |
89+
| | | Schema Registry subject names. |
90+
| | | Defaults to topic_subject_name_strategy. |
91+
+---------------------------+----------+--------------------------------------------------+
9092
9193
Schemas are registered to namespaces known as Subjects which define how a
9294
schema may evolve over time. By default the subject name is formed by
@@ -95,9 +97,10 @@ class AvroSerializer(Serializer):
9597
i.e. {topic name}-{message field}
9698
9799
Alternative naming strategies may be configured with the property
98-
`subject.name.strategy`.
100+
``subject.name.strategy``.
99101
100102
Supported subject name strategies:
103+
101104
+--------------------------------------+------------------------------+
102105
| Subject Name Strategy | Output Format |
103106
+======================================+==============================+
@@ -108,7 +111,7 @@ class AvroSerializer(Serializer):
108111
| record_subject_name_strategy | {record name} |
109112
+--------------------------------------+------------------------------+
110113
111-
See ``Subject name strategy`` for additional details.
114+
See `Subject name strategy <https://docs.confluent.io/current/schema-registry/serializer-formatter.html#subject-name-strategy>`_ for additional details.
112115
113116
Note:
114117
Prior to serialization all ``Complex Types`` must first be converted to
@@ -119,22 +122,14 @@ class AvroSerializer(Serializer):
119122
See ``avro_producer.py`` in the examples directory for example usage.
120123
121124
Args:
122-
schema_str (str): Avro Schema declaration.
125+
schema_str (str): Avro `Schema Declaration. <https://avro.apache.org/docs/current/spec.html#schemas>`_
123126
124-
schema_registry_client (SchemaRegistryClient): Schema Registry
125-
client instance.
127+
schema_registry_client (SchemaRegistryClient): Schema Registry client instance.
126128
127-
to_dict (callable, optional): Callable(object, SerializationContext) -> dict.
128-
Converts object to a dict.
129+
to_dict (callable, optional): Callable(object, SerializationContext) -> dict. Converts object to a dict.
129130
130131
conf (dict): AvroSerializer configuration.
131132
132-
.. _Subject name strategy:
133-
https://docs.confluent.io/current/schema-registry/serializer-formatter.html#subject-name-strategy
134-
135-
.. _Schema declaration:
136-
https://avro.apache.org/docs/current/spec.html#schemas
137-
138133
""" # noqa: E501
139134
__slots__ = ['_hash', '_auto_register', '_known_subjects', '_parsed_schema',
140135
'_registry', '_schema', '_schema_id', '_schema_name',
@@ -196,14 +191,13 @@ def __call__(self, obj, ctx):
196191
Args:
197192
obj (object): object instance to serializes.
198193
199-
ctx (SerializationContext): Metadata pertaining to the serialization
200-
operation.
194+
ctx (SerializationContext): Metadata pertaining to the serialization operation.
201195
202196
Note:
203197
None objects are represented as Kafka Null.
204198
205199
Raises:
206-
SerializerError if any error occurs serializing obj
200+
SerializerError: if any error occurs serializing obj
207201
208202
Returns:
209203
bytes: Confluent Schema Registry formatted Avro bytes
@@ -264,11 +258,10 @@ class AvroDeserializer(Deserializer):
264258
from_dict (callable, optional): Callable(dict, SerializationContext) -> object.
265259
Converts dict to an instance of some object.
266260
267-
.. _Schema declaration:
268-
https://avro.apache.org/docs/current/spec.html#schemas
261+
See Also:
262+
`Apache Avro Schema Declaration <https://avro.apache.org/docs/current/spec.html#schemas>`_
269263
270-
.. _Schema Resolution
271-
https://avro.apache.org/docs/1.8.2/spec.html#Schema+Resolution
264+
`Apache Avro Schema Resolution <https://avro.apache.org/docs/1.8.2/spec.html#Schema+Resolution>`_
272265
273266
"""
274267
__slots__ = ['_reader_schema', '_registry', '_from_dict', '_writer_schemas']
@@ -295,13 +288,12 @@ def __call__(self, value, ctx):
295288
operation.
296289
297290
Raises:
298-
SerializerError if an error occurs ready data.
291+
SerializerError: if an error occurs ready data.
299292
300293
Returns:
301-
object: if ``from_dict`` is set, otherwise dict.
302-
If no value is supplied None is returned.
294+
object: object if ``from_dict`` is set, otherwise dict. If no value is supplied None is returned.
303295
304-
"""
296+
""" # noqa: E501
305297
if value is None:
306298
return None
307299

‎confluent_kafka/schema_registry/error.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,17 @@ class SchemaRegistryError(Exception):
2525
Represents an error returned by the Confluent Schema Registry
2626
2727
Args:
28-
http_status_code (int) = HTTP status code
28+
http_status_code (int): HTTP status code
2929
30-
error_code (int) = Schema Registry error code; -1 represents an unknown
30+
error_code (int): Schema Registry error code; -1 represents an unknown
3131
error.
3232
33-
error_message (str) = Description of the error
33+
error_message (str): Description of the error
3434
3535
See Also:
36-
https://docs.confluent.io/current/schema-registry/develop/api.html#errors
36+
`API Error Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#errors>`_
3737
38-
"""
38+
""" # noqa: E501
3939
UNKNOWN = -1
4040

4141
def __init__(self, http_status_code, error_code, error_message):

0 commit comments

Comments
 (0)