Add FastStream example to docs

docs/examples/faststream.rst

@@ -0,0 +1,42 @@
+.. _faststream-example:
+
+FastStream example
+=============
+
+.. meta::
+   :keywords: Python,Dependency Injection,FastStream,Example
+   :description: This example demonstrates a usage of FastStream with Dependency Injector.
+
+
+This example shows how to use ``Dependency Injector`` with `FastStream <https://dummy.faststream.airt.ai/0.5/faststream/>`_.
+
+The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/faststream>`_.
+
+Despite ``FastStream`` uses ``FastDepends`` library for dependency injection, the integration between
+``Dependency injector`` and ``FastStream`` has a small difference from already existing :ref:`fastdepends` example.
+
+Since ``FastStream`` also leverages function signatures to determine input data types you have to use ``Depends()`` function
+with ``cast=False`` argument to make ``FastStream`` ignore your injected dependency argument in the function signature.
+
+Example below shows how to inject ``Counter`` class into ``FastStream`` redis handler so that it will distinguish between
+message schema (``User``) and injected dependency (``Counter``) and use them both correctly.
+
+Listing of ``consumer.py``:
+
+.. literalinclude:: ../../examples/miniapps/faststream/src/consumer.py
+   :language: python
+
+Listing of ``producer.py``:
+
+.. literalinclude:: ../../examples/miniapps/faststream/src/producer.py
+   :language: python
+
+Sources
+-------
+
+Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/faststream>`_.
+
+.. include:: ../sponsor.rst
+
+.. disqus::
+

examples/miniapps/faststream/Dockerfile.consumer

@@ -0,0 +1,11 @@
+FROM python:3.13-bookworm
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+COPY ./src ./src
+
+ENV PYTHONUNBUFFERED=1
+CMD ["python3", "-m", "src.consumer"]

examples/miniapps/faststream/Dockerfile.producer

@@ -0,0 +1,11 @@
+FROM python:3.13-bookworm
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+COPY ./src ./src
+
+ENV PYTHONUNBUFFERED=1
+CMD ["python3", "-m", "src.producer"]

examples/miniapps/faststream/README.rst

@@ -0,0 +1,40 @@
+FastStream + Dependency Injector Example
+=====================================
+
+This is a `FastStream <https://dummy.faststream.airt.ai/0.5/faststream/>`_ +
+`Dependency Injector <https://python-dependency-injector.ets-labs.org/>`_ example application.
+
+The example application is a simple consumer that counts messages sent to redis channel by producer.
+
+Counter is provided to faststream handler as a dependency injected by ``dependency_injector`` library.
+
+Run
+---
+
+Everything can be run via docker compose.
+
+A convenient ``run.sh`` script runs consumer, producer and redis services, prints logs from consumer
+and shuts down once producer exits.
+
+Ensure that ``run.sh`` has execution permission:
+
+.. code-block:: bash
+
+    sudo chmod +x ./run.sh
+
+Run the sciprt:
+
+.. code-block:: bash
+
+    ./run.sh
+
+The output should be something like:
+
+.. code-block::
+
+    faststream-example-consumer  | Message #1 from John: 'As you can see'
+    faststream-example-consumer  | Message #2 from John: 'messages are counted correctly'
+    faststream-example-consumer  | Message #3 from John: 'by the counter that is injected'
+    faststream-example-consumer  | Message #4 from John: 'into faststream handler'
+    faststream-example-consumer  | Message #5 from John: 'via awesome dependency_injector library.'
+

examples/miniapps/faststream/docker-compose.yml

@@ -0,0 +1,22 @@
+name: faststream-example
+
+services:
+
+  redis:
+    container_name: "${COMPOSE_PROJECT_NAME}-redis"
+    image: redis
+
+  consumer:
+    container_name: "${COMPOSE_PROJECT_NAME}-consumer"
+    build:
+      dockerfile: Dockerfile.consumer
+    depends_on:
+      - redis
+
+  producer:
+    container_name: "${COMPOSE_PROJECT_NAME}-producer"
+    build:
+      dockerfile: Dockerfile.producer
+    depends_on:
+      - consumer
+

examples/miniapps/faststream/faststream.rst

@@ -0,0 +1,42 @@
+.. _faststream-example:
+
+FastStream example
+=============
+
+.. meta::
+   :keywords: Python,Dependency Injection,FastStream,Example
+   :description: This example demonstrates a usage of FastStream with Dependency Injector.
+
+
+This example shows how to use ``Dependency Injector`` with `FastStream <https://dummy.faststream.airt.ai/0.5/faststream/>`_.
+
+The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/faststream>`_.
+
+Despite ``FastStream`` uses ``FastDepends`` library for dependency injection, the integration between
+``Dependency injector`` and ``FastStream`` has a small difference from already existing :ref:`fastdepends` example.
+
+Since ``FastStream`` also leverages function signatures to determine input data types you have to use ``Depends()`` function
+with ``cast=False`` argument to make ``FastStream`` ignore your injected dependency argument in the function signature.
+
+Example below shows how to inject ``Counter`` class into ``FastStream`` redis handler so that it will distinguish between
+message schema (``User``) and injected dependency (``Counter``) and use them both correctly.
+
+Listing of ``consumer.py``:
+
+.. literalinclude:: ../../examples/miniapps/faststream/src/consumer.py
+   :language: python
+
+Listing of ``producer.py``:
+
+.. literalinclude:: ../../examples/miniapps/faststream/src/producer.py
+   :language: python
+
+Sources
+-------
+
+Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/faststream>`_.
+
+.. include:: ../sponsor.rst
+
+.. disqus::
+

examples/miniapps/faststream/requirements.txt

@@ -0,0 +1,4 @@
+dependency_injector
+faststream
+pydantic
+redis

examples/miniapps/faststream/run.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+docker compose up \
+    --no-attach=redis \
+    --abort-on-container-exit \
+    --exit-code-from producer
+
+docker container rm \
+    faststream-example-producer \
+    faststream-example-consumer \
+    faststream-example-redis
+
+docker image rm \
+    faststream-example-producer \
+    faststream-example-consumer

examples/miniapps/faststream/src/consumer.py

@@ -0,0 +1,57 @@
+import asyncio
+from typing import Annotated
+
+from dependency_injector import containers, providers
+from dependency_injector.wiring import Provide, inject
+from faststream import Depends, FastStream
+from faststream.redis import RedisBroker
+from pydantic import BaseModel
+
+
+class Counter:
+    def __init__(self):
+        self.count = 0
+
+    def next(self) -> int:
+        self.count += 1
+        return self.count
+
+
+class Container(containers.DeclarativeContainer):
+    counter = providers.Singleton(Counter)
+
+
+broker = RedisBroker("redis://redis", logger=None)
+
+
+class Message(BaseModel):
+    user: str
+    text: str
+
+
+@broker.subscriber("messages")
+@inject
+async def handle_user_message(
+    message: Message,
+    counter: Annotated[
+        Counter,
+        Depends(
+            Provide[Container.counter],
+            cast=False,  # <-- this is the key part
+        ),
+    ],
+) -> None:
+    count = counter.next()
+    print(f"Message #{count} from {message.user}: '{message.text}'")
+
+
+async def main() -> None:
+    container = Container()
+    container.wire(modules=[__name__])
+
+    await FastStream(broker, logger=None).run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/miniapps/faststream/src/producer.py

@@ -0,0 +1,25 @@
+import json
+import time
+
+import redis
+
+
+def main():
+    client = redis.Redis(host="redis", port=6379)
+
+    for text in (
+        "As you can see",
+        "messages are counted correctly",
+        "by the counter that is injected",
+        "into faststream handler",
+        "via awesome dependency_injector library.",
+    ):
+        time.sleep(2)
+
+        message = {"user": "John", "text": text}
+        client.publish("messages", json.dumps(message))
+
+
+if __name__ == "__main__":
+    main()
+