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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy