Merge pull request #68 from matheusvnm/dev

feat: PubSubTestClient and example docs

Author: matheusvnm

AGENTS.md

@@ -1,3 +1,23 @@
+"""Title: Basic Subscriber Setup
+
+Demonstrates the simplest way to create a Pub/Sub subscriber with FastPubSub.
+
+This example shows:
+- Creating a PubSubBroker with a project ID
+- Defining a subscriber using the @broker.subscriber decorator
+- Handling incoming messages with an async handler function
+- Publishing a test message on application startup
+
+The subscriber listens to 'subscriber-topic' and logs each received message.
+
+Run with:
+    fastpubsub run examples.basic_usage.e1_01_basic_subscriber:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e1_01_basic_subscriber.py

@@ -1,3 +1,26 @@
+"""Title: Multiple Subscribers on Different Topics
+
+Demonstrates how to create multiple subscribers within a single FastPubSub application.
+
+This example shows:
+- Creating multiple subscribers with different aliases
+- Subscribing to the same topic with different subscription names
+- Subscribing to different topics
+- How messages are routed to the appropriate handlers
+
+The example creates three subscribers:
+1. 'first-alias' - listens to 'first-topic'
+2. 'second-alias' - also listens to 'first-topic' (different subscription)
+3. 'third-alias' - listens to 'second-topic'
+
+Run with:
+    fastpubsub run examples.basic_usage.e1_02_multiple_subscribers:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e1_02_multiple_subscribers.py

@@ -1,3 +1,25 @@
+"""Title: Cross-Project Subscription
+
+Demonstrates how to subscribe to topics in different Google Cloud projects.
+
+This example shows:
+- Creating subscribers that listen to topics in different GCP projects
+- Using the project_id parameter on @broker.subscriber to override the default project
+- Publishing messages to topics in different projects
+
+The example creates two subscribers:
+1. One listening to the default project's topic
+2. Another listening to the same topic name but in an alternative project
+
+Run with:
+    fastpubsub run examples.basic_usage.e1_03_cross_project_subscribers:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+    - Ensure both projects exist and are accessible (Only for GCP on Cloud)
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e1_03_cross_project_subscribers.py

@@ -1,3 +1,23 @@
+"""Title: Basic Message Publishing
+
+Demonstrates the simplest way to publish messages using broker.publish().
+
+This example shows:
+- Publishing messages directly via broker.publish()
+- Passing the topic name and data as arguments
+- Using the after_startup hook to publish a test message
+
+The example publishes a dictionary message to 'test-topic' which is then
+received by the subscriber handler.
+
+Run with:
+    fastpubsub run examples.basic_usage.e2_01_basic_publisher:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_01_basic_publisher.py

@@ -1,3 +1,23 @@
+"""Title: Publisher Instance API
+
+Demonstrates creating a reusable Publisher instance bound to a specific topic.
+
+This example shows:
+- Creating a Publisher instance with broker.publisher()
+- Binding the publisher to a specific topic at creation time
+- Publishing messages without specifying the topic each time
+
+Using a Publisher instance is useful when you need to publish multiple messages
+to the same topic, as it avoids repeating the topic name.
+
+Run with:
+    fastpubsub run examples.basic_usage.e2_02_basic_publisher:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_02_basic_publisher.py

@@ -1,3 +1,24 @@
+"""Title: Publisher in Startup Hook
+
+Demonstrates creating a Publisher instance inside the startup hook.
+
+This example shows:
+- Deferring Publisher instantiation until application startup
+- Creating a Publisher within the after_startup hook
+- Publishing messages immediately after the publisher is created
+
+This pattern is useful when you need the application to be fully initialized
+before creating publishers, or when publisher configuration depends on
+runtime state.
+
+Run with:
+    fastpubsub run examples.basic_usage.e2_03_basic_publisher:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker
 from fastpubsub.logger import logger
 

examples/basic_usage/e2_03_basic_publisher.py

@@ -1,3 +1,27 @@
+"""Title: Cross-Project Publishing
+
+Demonstrates publishing messages across multiple Google Cloud projects.
+
+This example shows:
+- Creating publishers and subscribers across three different GCP projects
+- Using project_id parameter on broker.publisher() to target different projects
+- Message flow across projects: first -> second -> third
+- Chaining message processing across project boundaries
+
+The flow:
+1. Message published to first project triggers subscriber
+2. First subscriber publishes to second project
+3. Second subscriber publishes to third project using a Publisher instance
+
+Run with:
+    fastpubsub run examples.basic_usage.e2_04_cross_project_publisher:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+    - Ensure all three projects exist and are accessible
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger
 from fastpubsub.pubsub import Publisher

examples/basic_usage/e2_04_cross_project_publisher.py

@@ -1,3 +1,25 @@
+"""Title: Different Message Format Support
+
+Demonstrates publishing messages in various formats supported by FastPubSub.
+
+This example shows:
+- Publishing Pydantic models (automatically serialized to JSON)
+- Publishing dictionaries (serialized to JSON)
+- Publishing strings (encoded to bytes)
+- Publishing raw bytes
+
+FastPubSub automatically handles serialization for different data types,
+making it easy to work with structured data using Pydantic models while
+also supporting simple string and bytes payloads.
+
+Run with:
+    fastpubsub run examples.basic_usage.e2_04_message_formats:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from pydantic import BaseModel
 
 from fastpubsub import FastPubSub, Message, Publisher, PubSubBroker

examples/basic_usage/e2_04_message_formats.py

@@ -1,3 +1,27 @@
+"""Title: Message Chaining Between Topics
+
+Demonstrates how a subscriber can publish messages to another topic.
+
+This example shows:
+- Chaining message processing between topics
+- A subscriber that receives a message and publishes to a different topic
+- Creating pipelines where one message triggers subsequent messages
+
+The flow:
+1. Initial message is published to 'first-topic'
+2. First subscriber processes it and publishes to 'second-topic'
+3. Second subscriber receives the chained message
+
+This pattern is useful for event-driven architectures and workflow processing.
+
+Run with:
+    fastpubsub run examples.basic_usage.e3_01_linked_pubsub:app
+
+Requirements:
+    - Set PUBSUB_EMULATOR_HOST for local testing, or
+    - Set GOOGLE_APPLICATION_CREDENTIALS for GCP
+"""
+
 from fastpubsub import FastPubSub, Message, PubSubBroker
 from fastpubsub.logger import logger