feat: adds pydantic serialization, dependency injection and custom encoding/decoding

Author: matheusvnm

examples/basic_usage/e1_01_basic_subscriber.py

@@ -1,3 +1,18 @@
+"""Example: Basic subscriber setup.
+
+This example demonstrates the simplest way to create a message subscriber
+with FastPubSub. It shows how to:
+
+1. Create a PubSubBroker with your Google Cloud project ID
+2. Create a FastPubSub application
+3. Define a subscriber handler using the @broker.subscriber decorator
+4. Access the raw Message object in your handler
+
+Run with: fastpubsub run examples.basic_usage.e1_01_basic_subscriber:app
+"""
+
+import asyncio
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 
@@ -12,8 +27,14 @@
 )
 async def process_message(message: Message) -> None:
     logger.info(f"Processed message: {message}")
+    await asyncio.sleep(1)
 
 
 @app.after_startup
 async def test_publish() -> None:
-    await broker.publish("subscriber-topic", {"message": "streaming a message"})
+    sent = 0
+    max_messages = 100
+    while sent < max_messages:
+        await broker.publish("subscriber-topic", {"message": "streaming a message"})
+        sent += 1
+        # await asyncio.sleep(0.1)

examples/basic_usage/e1_02_multiple_subscribers.py

@@ -1,3 +1,12 @@
+"""Example: Multiple subscribers on different topics.
+
+This example shows how to define multiple subscribers within the same
+application, each listening to different topics or with different
+subscriptions. FastPubSub manages all subscribers concurrently.
+
+Run with: fastpubsub run examples.basic_usage.e1_02_multiple_subscribers:app
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e1_03_cross_project_subscribers.py

@@ -1,3 +1,12 @@
+"""Example: Cross-project subscribers.
+
+This example demonstrates how to subscribe to topics in different
+Google Cloud projects. Each subscriber can specify its own project_id,
+overriding the broker's default project.
+
+Run with: fastpubsub run examples.basic_usage.e1_03_cross_project_subscribers:app
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_01_basic_publisher.py

@@ -1,3 +1,12 @@
+"""Example: Basic message publishing.
+
+This example shows how to publish messages to a Pub/Sub topic using
+the broker's publish method. Messages can be dictionaries, strings,
+or bytes.
+
+Run with: fastpubsub run examples.basic_usage.e2_01_basic_publisher:app
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_02_basic_publisher.py

@@ -1,3 +1,12 @@
+"""Example: Publisher with explicit topic declaration.
+
+This example demonstrates creating a Publisher object for a specific
+topic, which can be reused for multiple publishes. This is useful when
+you need to publish to the same topic multiple times.
+
+Run with: fastpubsub run examples.basic_usage.e2_02_basic_publisher:app
+"""
+
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_03_basic_publisher.py

@@ -1,3 +1,13 @@
+"""Example: Publisher with explicit topic declaration.
+
+This example demonstrates creating a Publisher object for a specific
+topic, which can be reused for multiple publishes. Using an explicit
+Publisher object is useful when you need to publish multiple messages
+to the same topic.
+
+Run with: fastpubsub run examples.basic_usage.e2_03_basic_publisher:app
+"""
+
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_04_cross_project_publisher.py

@@ -1,6 +1,20 @@
-from fastpubsub import FastPubSub, Message, PubSubBroker
+"""Example: Cross-project publishing.
+
+This example demonstrates publishing messages to topics in different
+Google Cloud projects. Each publisher can specify its own project_id,
+overriding the broker's default project. This enables communication
+across multiple GCP projects from a single application.
+
+Flow:
+1. Message arrives at first project's topic
+2. Handler publishes to second project's topic
+3. Handler publishes to third project's topic via explicit Publisher
+
+Run with: fastpubsub run examples.basic_usage.e2_04_cross_project_publisher:app
+"""
+
+from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker
 from fastpubsub.logger import logger
-from fastpubsub.pubsub import Publisher
 
 DEFAULT_PROJECT_ID = "fastpubsub-pubsub-first-project"
 SECOND_PROJECT_ID = "fastpubsub-pubsub-second-project"

examples/basic_usage/e2_04_message_formats.py

@@ -1,3 +1,17 @@
+"""Example: Different message formats.
+
+This example shows the various data formats you can publish:
+- Pydantic models (automatically serialized via model_dump)
+- Dictionaries (JSON-serialized)
+- Strings (UTF-8 encoded)
+- Raw bytes (sent as-is)
+
+FastPubSub's serialization system automatically handles encoding
+based on the data type provided.
+
+Run with: fastpubsub run examples.basic_usage.e2_04_message_formats:app
+"""
+
 from pydantic import BaseModel
 
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker

examples/basic_usage/e3_01_linked_pubsub.py

@@ -1,3 +1,14 @@
+"""Example: Linked pub/sub (chaining topics).
+
+This example demonstrates a common pattern where a subscriber processes
+a message and then publishes to another topic, creating a processing
+pipeline. This is useful for building event-driven architectures.
+
+Flow: first-topic -> handle() -> second-topic -> handle_from_another_topic()
+
+Run with: fastpubsub run examples.basic_usage.e3_01_linked_pubsub:app
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e4_01_basic_fastapi_integration.py

@@ -1,3 +1,16 @@
+"""Example: FastAPI integration.
+
+This example shows how to integrate FastPubSub with a FastAPI application,
+allowing you to have both HTTP endpoints and Pub/Sub subscribers in the
+same application. FastPubSub extends FastAPI, so you can use decorators
+like @app.post() alongside @broker.subscriber().
+
+The HTTP endpoint receives a user message and publishes it to a topic,
+while the subscriber processes messages from that topic.
+
+Run with: fastpubsub run examples.basic_usage.e4_01_basic_fastapi_integration:app
+"""
+
 from pydantic import BaseModel
 
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker