Add docs for passing config

airtai · Jun 10, 2024 · 62f0ee7 · 62f0ee7
1 parent 4640cfe
commit 62f0ee7
Show file tree

Hide file tree

Showing 8 changed files with 72 additions and 4 deletions.
diff --git a/docs/docs/SUMMARY.md b/docs/docs/SUMMARY.md
@@ -65,6 +65,7 @@ search:
         - [Acknowledgement](confluent/ack.md)
         - [Message Information](confluent/message.md)
         - [Security Configuration](confluent/security.md)
+        - [Additional Configuration](confluent/additional-configuration.md)
 - [RabbitMQ](rabbit/index.md)
     - [Subscription](rabbit/examples/index.md)
         - [Direct](rabbit/examples/direct.md)

diff --git a/docs/docs/en/confluent/additional-configuration.md b/docs/docs/en/confluent/additional-configuration.md
@@ -0,0 +1,27 @@
+---
+# 0.5 - API
+# 2 - Release
+# 3 - Contributing
+# 5 - Template Page
+# 10 - Default
+search:
+  boost: 10
+---
+
+# Passing Additional Configuration to confluent-kafka-python
+
+The `confluent-kafka-python` package is a Python wrapper around [librdkakfa](https://github.com/confluentinc/librdkafka), which is a C/C++ client library for Apache Kafka.
+
+`confluent-kafka-python` accepts a `config` dictionary that is then passed on to `librdkafka`. `librdkafka` provides plenty of [configuration properties](https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md) to configure the Kafka client.
+
+**FastStream** also provides users with the ability to pass the config dictionary to `librdkafka` to provide greater customizability.
+
+## Example
+
+In the following example, we are setting the parameter `topic.metadata.refresh.fast.interval.ms`'s value to `300` instead of the default value `100` via the `config` parameter.
+
+```python linenums="1" hl_lines="15 16"
+{! docs_src/confluent/additional_config/app.py !}
+```
+
+Similarly, you could use the `config` parameter to pass any [configuration properties](https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md) to `librdkafka`.
diff --git a/docs/docs/en/confluent/security.md b/docs/docs/en/confluent/security.md
@@ -22,7 +22,7 @@ This chapter discusses the security options available in **FastStream** and how
 
 **Usage:**
 
-```python linenums="1" hl_lines="4 7 9"
+```python linenums="1" hl_lines="2 4 6"
 {! docs_src/confluent/security/basic.py !}
 ```
 
@@ -33,7 +33,7 @@ This chapter discusses the security options available in **FastStream** and how
 **Usage:**
 
 ```python linenums="1"
-{! docs_src/confluent/security/plaintext.py [ln:1-10.25,11-] !}
+{! docs_src/confluent/security/plaintext.py !}
 ```
 
 **Using any SASL authentication without SSL:**
@@ -58,18 +58,20 @@ If the user does not want to use SSL encryption without the warning getting logg
 
 === "SCRAM256"
     ```python linenums="1"
-    {!> docs_src/confluent/security/sasl_scram256.py [ln:1-10.25,11-] !}
+    {!> docs_src/confluent/security/sasl_scram256.py [ln:1-6.25,7-] !}
     ```
 
 === "SCRAM512"
     ```python linenums="1"
-    {!> docs_src/confluent/security/sasl_scram512.py [ln:1-10.25,11-] !}
+    {!> docs_src/confluent/security/sasl_scram512.py [ln:1-6.25,7-] !}
     ```
 
 ### 4. Other security related usecases
 
 **Purpose**: If you want to pass additional values to `confluent-kafka-python`, you can pass a dictionary called `config` to `KafkaBroker`. For example, to pass your own certificate file:
 
+**Usage:**
+
 ```python
 from faststream.confluent import KafkaBroker
 from faststream.security import SASLPlaintext

diff --git a/docs/docs/navigation_template.txt b/docs/docs/navigation_template.txt
@@ -65,6 +65,7 @@ search:
         - [Acknowledgement](confluent/ack.md)
         - [Message Information](confluent/message.md)
         - [Security Configuration](confluent/security.md)
+        - [Additional Configuration](confluent/additional-configuration.md)
 - [RabbitMQ](rabbit/index.md)
     - [Subscription](rabbit/examples/index.md)
         - [Direct](rabbit/examples/direct.md)

diff --git a/docs/docs_src/confluent/additional_config/__init__.py b/docs/docs_src/confluent/additional_config/__init__.py
diff --git a/docs/docs_src/confluent/additional_config/app.py b/docs/docs_src/confluent/additional_config/app.py
@@ -0,0 +1,22 @@
+from pydantic import BaseModel, Field
+
+from faststream import FastStream, Logger
+from faststream.confluent import KafkaBroker
+
+
+class HelloWorld(BaseModel):
+    msg: str = Field(
+        ...,
+        examples=["Hello"],
+        description="Demo hello world message",
+    )
+
+
+config = {"topic.metadata.refresh.fast.interval.ms": 300}
+broker = KafkaBroker("localhost:9092", config=config)
+app = FastStream(broker)
+
+
+@broker.subscriber("hello_world")
+async def on_hello_world(msg: HelloWorld, logger: Logger):
+    logger.info(msg)
diff --git a/tests/docs/confluent/additional_config/__init__.py b/tests/docs/confluent/additional_config/__init__.py
diff --git a/tests/docs/confluent/additional_config/test_app.py b/tests/docs/confluent/additional_config/test_app.py
@@ -0,0 +1,15 @@
+import pytest
+
+from docs.docs_src.confluent.additional_config.app import (
+    HelloWorld,
+    broker,
+    on_hello_world,
+)
+from faststream.confluent import TestKafkaBroker
+
+
+@pytest.mark.asyncio()
+async def test_base_app():
+    async with TestKafkaBroker(broker):
+        await broker.publish(HelloWorld(msg="First Hello"), "hello_world")
+        on_hello_world.mock.assert_called_with(dict(HelloWorld(msg="First Hello")))