From 309e1d45e6bb3bc4d54b6c4135e6697250169cba Mon Sep 17 00:00:00 2001 From: Tim McCormack Date: Mon, 6 Feb 2023 22:03:30 +0000 Subject: [PATCH 1/3] docs: Add docs for all Django settings --- CHANGELOG.rst | 6 +++++ edx_event_bus_kafka/__init__.py | 2 +- edx_event_bus_kafka/internal/config.py | 30 ++++++++++++++++++++++++ edx_event_bus_kafka/internal/consumer.py | 4 ++++ 4 files changed, 41 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 69002a6..b2e170c 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,6 +14,12 @@ Change Log Unreleased ********** +[3.9.2] - 2023-02-07 +******************** +Fixed +===== +* Added documentation to all Django settings used in consumer and producer + [3.9.1] - 2023-02-07 ******************** There was no version 3.9.0, due to a release issue. (Ignore any ``v3.9.0`` tag.) diff --git a/edx_event_bus_kafka/__init__.py b/edx_event_bus_kafka/__init__.py index dd4a467..8fa8c62 100644 --- a/edx_event_bus_kafka/__init__.py +++ b/edx_event_bus_kafka/__init__.py @@ -9,4 +9,4 @@ from edx_event_bus_kafka.internal.consumer import KafkaEventConsumer from edx_event_bus_kafka.internal.producer import KafkaEventProducer, create_producer -__version__ = '3.9.1' +__version__ = '3.9.2' diff --git a/edx_event_bus_kafka/internal/config.py b/edx_event_bus_kafka/internal/config.py index f2b0743..5ffade6 100644 --- a/edx_event_bus_kafka/internal/config.py +++ b/edx_event_bus_kafka/internal/config.py @@ -38,12 +38,27 @@ def get_schema_registry_client(): warnings.warn('Library confluent-kafka not available. Cannot create schema registry client.') return None + # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL + # .. setting_default: None + # .. setting_description: URL of the Avro schema registry, required for managing the evolution + # of event bus data and ensuring that consumers are able to decode the events that + # are produced. This URL is required for both producers and consumers and must point + # to an instance of Confluent Schema Registry: + # https://docs.confluent.io/platform/current/schema-registry/index.html url = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL', None) if url is None: warnings.warn("Cannot configure event-bus-kafka: Missing setting EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL") return None + # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY + # .. setting_default: None + # .. setting_description: API key for talking to the Avro schema registry specified in + # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. key = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY', '') + # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET + # .. setting_default: None + # .. setting_description: API secret for talking to the Avro schema registry specified in + # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. secret = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET', '') return SchemaRegistryClient({ @@ -58,6 +73,11 @@ def load_common_settings() -> Optional[dict]: Warns and returns None if essential settings are missing. """ + # .. setting_name: EVENT_BUS_KAFKA_BOOTSTRAP_SERVERS + # .. setting_default: None + # .. setting_description: List of one or more Kafka bootstrap servers, a comma-separated + # list of hosts and optional ports, and is required for both producers and consumers. + # See https://kafka.apache.org/documentation/ for more info. bootstrap_servers = getattr(settings, 'EVENT_BUS_KAFKA_BOOTSTRAP_SERVERS', None) if bootstrap_servers is None: warnings.warn("Cannot configure event-bus-kafka: Missing setting EVENT_BUS_KAFKA_BOOTSTRAP_SERVERS") @@ -67,7 +87,17 @@ def load_common_settings() -> Optional[dict]: 'bootstrap.servers': bootstrap_servers, } + # .. setting_name: EVENT_BUS_KAFKA_API_KEY + # .. setting_default: None + # .. setting_description: Optional API key for connecting to the Kafka cluster + # via SASL/PLAIN over TLS. Used as the SASL username. If not specified, no + # authentication will be attempted. key = getattr(settings, 'EVENT_BUS_KAFKA_API_KEY', None) + # .. setting_name: EVENT_BUS_KAFKA_API_SECRET + # .. setting_default: None + # .. setting_description: Optional API secret for connecting to the Kafka cluster + # via SASL/PLAIN over TLS. Used as the SASL password. If not specified, no + # authentication will be attempted. secret = getattr(settings, 'EVENT_BUS_KAFKA_API_SECRET', None) if key and secret: diff --git a/edx_event_bus_kafka/internal/consumer.py b/edx_event_bus_kafka/internal/consumer.py index fff28b1..6cdaa1e 100644 --- a/edx_event_bus_kafka/internal/consumer.py +++ b/edx_event_bus_kafka/internal/consumer.py @@ -44,6 +44,10 @@ # .. toggle_creation_date: 2022-01-31 KAFKA_CONSUMERS_ENABLED = SettingToggle('EVENT_BUS_KAFKA_CONSUMERS_ENABLED', default=True) +# .. setting_name: EVENT_BUS_KAFKA_CONSUMER_POLL_TIMEOUT +# .. setting_default: 1.0 +# .. setting_description: How long the consumer should wait, in seconds, for the Kafka broker +# to respond to a poll() call. CONSUMER_POLL_TIMEOUT = getattr(settings, 'EVENT_BUS_KAFKA_CONSUMER_POLL_TIMEOUT', 1.0) # .. setting_name: EVENT_BUS_KAFKA_CONSUMER_POLL_FAILURE_SLEEP From 92fa310cf47cca796a8b4c6daf6b020122d37d4b Mon Sep 17 00:00:00 2001 From: Tim McCormack Date: Tue, 7 Feb 2023 21:28:56 +0000 Subject: [PATCH 2/3] fixup! Correct defaults for schema registry API key/secret --- edx_event_bus_kafka/internal/config.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/edx_event_bus_kafka/internal/config.py b/edx_event_bus_kafka/internal/config.py index 5ffade6..a7fe336 100644 --- a/edx_event_bus_kafka/internal/config.py +++ b/edx_event_bus_kafka/internal/config.py @@ -51,12 +51,12 @@ def get_schema_registry_client(): return None # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY - # .. setting_default: None + # .. setting_default: '' # .. setting_description: API key for talking to the Avro schema registry specified in # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. key = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY', '') # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET - # .. setting_default: None + # .. setting_default: '' # .. setting_description: API secret for talking to the Avro schema registry specified in # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. secret = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET', '') From 7bd1aa0147b635be3c7618da55be05165f0d5f20 Mon Sep 17 00:00:00 2001 From: Tim McCormack Date: Wed, 8 Feb 2023 18:57:14 +0000 Subject: [PATCH 3/3] fixup! Describe optionality of API key/scret for schema registry --- edx_event_bus_kafka/internal/config.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/edx_event_bus_kafka/internal/config.py b/edx_event_bus_kafka/internal/config.py index a7fe336..4eea607 100644 --- a/edx_event_bus_kafka/internal/config.py +++ b/edx_event_bus_kafka/internal/config.py @@ -45,6 +45,8 @@ def get_schema_registry_client(): # are produced. This URL is required for both producers and consumers and must point # to an instance of Confluent Schema Registry: # https://docs.confluent.io/platform/current/schema-registry/index.html + # If needed, auth information must be added to ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY`` + # and ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET``. url = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL', None) if url is None: warnings.warn("Cannot configure event-bus-kafka: Missing setting EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL") @@ -53,12 +55,12 @@ def get_schema_registry_client(): # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY # .. setting_default: '' # .. setting_description: API key for talking to the Avro schema registry specified in - # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. + # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. Optional. key = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_KEY', '') # .. setting_name: EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET # .. setting_default: '' # .. setting_description: API secret for talking to the Avro schema registry specified in - # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. + # ``EVENT_BUS_KAFKA_SCHEMA_REGISTRY_URL``. Optional. secret = getattr(settings, 'EVENT_BUS_KAFKA_SCHEMA_REGISTRY_API_SECRET', '') return SchemaRegistryClient({