fastpubsub 0.0.1a1__tar.gz

fastpubsub-0.0.1a1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: fastpubsub
+Version: 0.0.1a1
+Summary: A high performance FastAPI-based message consumer framework for PubSub
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Requires-Dist: click>=8.2.1,<9.0.0
+Requires-Dist: fastapi>=0.119.0,<1.0.0
+Requires-Dist: google-api-core>=2.25.1,<3.0.0
+Requires-Dist: google-cloud-pubsub>=2.31.1,<3.0.0
+Requires-Dist: pydantic-settings>=2.10.1,<3.0.0
+Requires-Dist: rich-toolkit>=0.15.0,<1.0.0
+Requires-Dist: typer>=0.16.0,<1.0.0
+Requires-Dist: uvicorn>=0.37.0,<1.0.0
+Requires-Dist: httpx>=0.23.0,<1.0.0
+Requires-Dist: newrelic[infinite-tracing]>=10.15.0,<11.0.0 ; extra == 'newrelic'
+Requires-Python: >=3.13, <3.15
+Provides-Extra: newrelic
+Description-Content-Type: text/markdown
+
+# FastPubSub
+
+*A high performance FastAPI-based message consumer framework for PubSub.*
+
+[//]: # (Aqui devem ir algumas tags)
+
+
+## Features
+
+
+FastPubSub ia modern, high-performance framework for building modern applications that process event messages on Google PubSub. It combines the standard PubSub Python SDK with FastAPI, Pydantic and Uvicorn to provide a easy-to-use development experience.
+
+The key features are:
+
+- **Fast:** FastPubSub is (unironically) fast. It's built on top of [**FastAPI**](https://fastapi.tiangolo.com/), [**uvicorn**](https://uvicorn.dev/) and [**Google PubSub Python SDK**](https://github.com/googleapis/python-pubsub) for maximum performance.
+- **Intuitive**: It is designed to be intuitive and easy to use, even for beginners.
+- **Typed**: Providing a great editor support and less time reading docs.
+- **Robust**: Get production-ready code with sensible default values  avoiding shooting yourself in the foot.
+- **Asynchronous:** It is built on top of anyio, which allows it to run on top of either asyncio or trio.
+- **Batteries Included**: Providing its own CLI and other widely used tools such as [**pydantic**](https://docs.pydantic.dev/) for data validation, observability integrations and log contextualization.
+
+
+
+## Quick Start
+
+### Installation
+
+FastPubSub works on Linux, macOS, Windows and most Unix-style operating systems. You can install it with pip as usual:
+
+```shell
+pip install fastpubsub
+```
+
+### Writing your first application
+
+**FastPubSub** brokers provide convenient function decorators (`@broker.subscriber`) and methods (`broker.publisher`) to allow you to delegate the actual process of:
+
+- Creating Pub/Sub subscriptions to receive and process data from topics.
+- Publishing data to other topics downstream in your message processing pipeline.
+
+These decorators make it easy to specify the processing logic for your consumers and producers, allowing you to focus on the core business logic of your application without worrying about the underlying integration.
+
+Also, **Pydantic**’s [`BaseModel`](https://docs.pydantic.dev/usage/models/) class allows you to define messages using a declarative syntax for sending messages downstream, making it easy to specify the fields and types of your messages.
+
+Here is an example Python app using **FastPubSub** that consumes data from an incoming data stream and outputs two messages to another one:
+
+
+```python
+# basic.py
+
+from pydantic import BaseModel, Field
+from fastpubsub import FastPubSub, PubSubBroker, Message
+from fastpubsub.logger import logger
+
+class Address(BaseModel):
+    street: str = Field(..., examples=["5th Avenue"])
+    number: str = Field(..., examples=["1548"])
+
+
+broker = PubSubBroker(project_id="some-project-id")
+app = FastPubSub(broker)
+
+@broker.subscriber(
+    alias="my_handler",
+    topic_name="in_topic",
+    subscription_name="sub_name",
+)
+async def handle_message(message: Message):
+   logger.info(f"The message {message.id} is processed.")
+   await broker.publish(topic_name="out_topic", data="Hi!")
+
+   address = Address(street="Av. Flores", number="213")
+   await broker.publish(topic_name="out_topic", data=address)
+```
+
+
+
+### Running the application
+
+Before running the command make sure to set one of the variables (mutually exclusive):
+
+1. **Running PubSub on Cloud**: The environment variable  `GOOGLE_APPLICATION_CREDENTIALS` with the path of the service-account on your system.
+2. **Running PubSub Emulator**: The environment variable `PUBSUB_EMULATOR_HOST` with host:port of your local PubSub emulator.
+
+
+---
+
+After that, the application can be started using built-in **FastPubSub** CLI command. It is embedded in the library and its a core part of the system.
+
+To run the service, use the **FastPubSub** embedded CLI. Just execute the command ``run`` and pass the module (in this case, the file where the app implementation is located) and the app symbol to the command.
+
+```bash
+fastpubsub run basic:app
+```
+
+After running the command, you should see the following output:
+
+
+``` shell
+2025-10-13 15:23:59,550 | INFO     | 97527:133552019097408 | runner:run:55 | FastPubSub app starting...
+2025-10-13 15:23:59,696 | INFO     | 97527:133552019097408 | tasks:start:74 | The handle_message handler is waiting for messages.
+```
+
+Also, **FastPubSub** provides you with a great hot reload feature to improve your Development Experience
+
+``` shell
+fastpubsub run basic:app --reload
+```
+
+And multiprocessing horizontal scaling feature as well:
+
+``` shell
+fastpubsub run basic:app --workers 3
+```
+
+You can learn more about **CLI** features [here](docs/learn/tutorial/07.cli.md).
+
+
+## Further Documentation
+
+1. [Features](docs/features/00.index.md)
+2. [Getting Started](docs/getting-started/00.index.md)
+3. [Learn](docs/learn/00.index.md)
+    1. [Introduction to Google PubSub](docs/learn/01.intro-pubsub.md)
+    2. [Introduction to Async/Await](docs/learn/02.intro-async-await.md)
+    3. [Introduction to Virtual Environments](docs/learn/03.intro-venv.md)
+    4. [Tutorial: User Guide](docs/learn/tutorial/00.index.md)
+        1. [Subscription Basics](docs/learn/tutorial/01.subscription.md)
+        2. [Publishing Basics](docs/learn/tutorial/02.publishing.md)
+        3. [Lifespan and Hooks](docs/learn/tutorial/03.lifespan.md)
+        4. [Acknowledgement](docs/learn/tutorial/04.acknowledgement.md)
+        5. [Routers (and Hierarchy)](docs/learn/tutorial/05.routers.md)
+        6. [Middlewares (and Hierarchy)](docs/learn/tutorial/06.middlewares.md)
+        7. [Command line Interface (CLI)](docs/learn/tutorial/07.cli.md)
+        8. [Integrations](docs/learn/tutorial/integrations/00.index.md)
+            1. [FastAPI](docs/learn/tutorial/integrations/01.fastapi.md)
+            2. [Observability](docs/learn/tutorial/integrations/02.observability.md)
+            3. [Logging](docs/learn/tutorial/integrations/03.logger.md)
+            4. [Application Probes](docs/learn/tutorial/integrations/04.probes.md)
+    5. [Deployment Guide](docs/learn/deployment/00.index.md)
+        1. [On Virtual Machines](docs/learn/deployment/01.vm-guide.md)
+        2. [On Kubernetes](docs/learn/deployment/02.k8-guide.md)
+
+
+## Contact
+
+Please stay in touch by:
+
+Sending a email at sandro-matheus@hotmail.com.
+
+Sending a message on my [linkedin](www.linkedin.com/in/matheusvnm).
+
+
+## License
+This project is licensed under the terms of the Apache 2.0 license.

fastpubsub-0.0.1a1/README.md

@@ -0,0 +1,155 @@
+# FastPubSub
+
+*A high performance FastAPI-based message consumer framework for PubSub.*
+
+[//]: # (Aqui devem ir algumas tags)
+
+
+## Features
+
+
+FastPubSub ia modern, high-performance framework for building modern applications that process event messages on Google PubSub. It combines the standard PubSub Python SDK with FastAPI, Pydantic and Uvicorn to provide a easy-to-use development experience.
+
+The key features are:
+
+- **Fast:** FastPubSub is (unironically) fast. It's built on top of [**FastAPI**](https://fastapi.tiangolo.com/), [**uvicorn**](https://uvicorn.dev/) and [**Google PubSub Python SDK**](https://github.com/googleapis/python-pubsub) for maximum performance.
+- **Intuitive**: It is designed to be intuitive and easy to use, even for beginners.
+- **Typed**: Providing a great editor support and less time reading docs.
+- **Robust**: Get production-ready code with sensible default values  avoiding shooting yourself in the foot.
+- **Asynchronous:** It is built on top of anyio, which allows it to run on top of either asyncio or trio.
+- **Batteries Included**: Providing its own CLI and other widely used tools such as [**pydantic**](https://docs.pydantic.dev/) for data validation, observability integrations and log contextualization.
+
+
+
+## Quick Start
+
+### Installation
+
+FastPubSub works on Linux, macOS, Windows and most Unix-style operating systems. You can install it with pip as usual:
+
+```shell
+pip install fastpubsub
+```
+
+### Writing your first application
+
+**FastPubSub** brokers provide convenient function decorators (`@broker.subscriber`) and methods (`broker.publisher`) to allow you to delegate the actual process of:
+
+- Creating Pub/Sub subscriptions to receive and process data from topics.
+- Publishing data to other topics downstream in your message processing pipeline.
+
+These decorators make it easy to specify the processing logic for your consumers and producers, allowing you to focus on the core business logic of your application without worrying about the underlying integration.
+
+Also, **Pydantic**’s [`BaseModel`](https://docs.pydantic.dev/usage/models/) class allows you to define messages using a declarative syntax for sending messages downstream, making it easy to specify the fields and types of your messages.
+
+Here is an example Python app using **FastPubSub** that consumes data from an incoming data stream and outputs two messages to another one:
+
+
+```python
+# basic.py
+
+from pydantic import BaseModel, Field
+from fastpubsub import FastPubSub, PubSubBroker, Message
+from fastpubsub.logger import logger
+
+class Address(BaseModel):
+    street: str = Field(..., examples=["5th Avenue"])
+    number: str = Field(..., examples=["1548"])
+
+
+broker = PubSubBroker(project_id="some-project-id")
+app = FastPubSub(broker)
+
+@broker.subscriber(
+    alias="my_handler",
+    topic_name="in_topic",
+    subscription_name="sub_name",
+)
+async def handle_message(message: Message):
+   logger.info(f"The message {message.id} is processed.")
+   await broker.publish(topic_name="out_topic", data="Hi!")
+
+   address = Address(street="Av. Flores", number="213")
+   await broker.publish(topic_name="out_topic", data=address)
+```
+
+
+
+### Running the application
+
+Before running the command make sure to set one of the variables (mutually exclusive):
+
+1. **Running PubSub on Cloud**: The environment variable  `GOOGLE_APPLICATION_CREDENTIALS` with the path of the service-account on your system.
+2. **Running PubSub Emulator**: The environment variable `PUBSUB_EMULATOR_HOST` with host:port of your local PubSub emulator.
+
+
+---
+
+After that, the application can be started using built-in **FastPubSub** CLI command. It is embedded in the library and its a core part of the system.
+
+To run the service, use the **FastPubSub** embedded CLI. Just execute the command ``run`` and pass the module (in this case, the file where the app implementation is located) and the app symbol to the command.
+
+```bash
+fastpubsub run basic:app
+```
+
+After running the command, you should see the following output:
+
+
+``` shell
+2025-10-13 15:23:59,550 | INFO     | 97527:133552019097408 | runner:run:55 | FastPubSub app starting...
+2025-10-13 15:23:59,696 | INFO     | 97527:133552019097408 | tasks:start:74 | The handle_message handler is waiting for messages.
+```
+
+Also, **FastPubSub** provides you with a great hot reload feature to improve your Development Experience
+
+``` shell
+fastpubsub run basic:app --reload
+```
+
+And multiprocessing horizontal scaling feature as well:
+
+``` shell
+fastpubsub run basic:app --workers 3
+```
+
+You can learn more about **CLI** features [here](docs/learn/tutorial/07.cli.md).
+
+
+## Further Documentation
+
+1. [Features](docs/features/00.index.md)
+2. [Getting Started](docs/getting-started/00.index.md)
+3. [Learn](docs/learn/00.index.md)
+    1. [Introduction to Google PubSub](docs/learn/01.intro-pubsub.md)
+    2. [Introduction to Async/Await](docs/learn/02.intro-async-await.md)
+    3. [Introduction to Virtual Environments](docs/learn/03.intro-venv.md)
+    4. [Tutorial: User Guide](docs/learn/tutorial/00.index.md)
+        1. [Subscription Basics](docs/learn/tutorial/01.subscription.md)
+        2. [Publishing Basics](docs/learn/tutorial/02.publishing.md)
+        3. [Lifespan and Hooks](docs/learn/tutorial/03.lifespan.md)
+        4. [Acknowledgement](docs/learn/tutorial/04.acknowledgement.md)
+        5. [Routers (and Hierarchy)](docs/learn/tutorial/05.routers.md)
+        6. [Middlewares (and Hierarchy)](docs/learn/tutorial/06.middlewares.md)
+        7. [Command line Interface (CLI)](docs/learn/tutorial/07.cli.md)
+        8. [Integrations](docs/learn/tutorial/integrations/00.index.md)
+            1. [FastAPI](docs/learn/tutorial/integrations/01.fastapi.md)
+            2. [Observability](docs/learn/tutorial/integrations/02.observability.md)
+            3. [Logging](docs/learn/tutorial/integrations/03.logger.md)
+            4. [Application Probes](docs/learn/tutorial/integrations/04.probes.md)
+    5. [Deployment Guide](docs/learn/deployment/00.index.md)
+        1. [On Virtual Machines](docs/learn/deployment/01.vm-guide.md)
+        2. [On Kubernetes](docs/learn/deployment/02.k8-guide.md)
+
+
+## Contact
+
+Please stay in touch by:
+
+Sending a email at sandro-matheus@hotmail.com.
+
+Sending a message on my [linkedin](www.linkedin.com/in/matheusvnm).
+
+
+## License
+This project is licensed under the terms of the Apache 2.0 license.

fastpubsub-0.0.1a1/fastpubsub/__about__.py

@@ -0,0 +1,7 @@
+"""Simple and fast framework to create message brokers based microservices."""
+
+from importlib.metadata import version
+
+__version__ = version("fastpubsub")
+
+SERVICE_NAME = f"fastpubsub-{__version__}"

fastpubsub-0.0.1a1/fastpubsub/__init__.py

@@ -0,0 +1,19 @@
+"""A high performance FastAPI-based message consumer framework for Google PubSub."""
+
+from fastpubsub.applications import FastPubSub
+from fastpubsub.broker import PubSubBroker
+from fastpubsub.datastructures import Message
+from fastpubsub.middlewares.base import BaseMiddleware
+from fastpubsub.pubsub.publisher import Publisher
+from fastpubsub.pubsub.subscriber import Subscriber
+from fastpubsub.router import PubSubRouter
+
+__all__ = [
+    "FastPubSub",
+    "PubSubBroker",
+    "PubSubRouter",
+    "Publisher",
+    "Subscriber",
+    "BaseMiddleware",
+    "Message",
+]

fastpubsub-0.0.1a1/fastpubsub/__main__.py

@@ -0,0 +1,6 @@
+"""FastPubSub CLI entrypoint."""
+
+from fastpubsub.cli.main import app
+
+if __name__ == "__main__":
+    app(prog_name="fastpubsub")

fastpubsub-0.0.1a1/fastpubsub/applications.py

@@ -0,0 +1,237 @@
+"""FastPubSub application and lifecycle management."""
+
+from collections.abc import AsyncGenerator, AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from pydantic import ConfigDict, validate_call
+from starlette.applications import Starlette
+from starlette.status import HTTP_200_OK, HTTP_500_INTERNAL_SERVER_ERROR
+
+from fastpubsub.broker import PubSubBroker
+from fastpubsub.concurrency.utils import ensure_async_callable_function
+from fastpubsub.logger import logger
+from fastpubsub.observability import get_apm_provider
+from fastpubsub.types import NoArgAsyncCallable
+
+
+class Application:
+    """Manages the lifecycle of a FastPubSub application."""
+
+    def __init__(
+        self,
+        broker: PubSubBroker,
+        on_startup: Sequence[NoArgAsyncCallable] | None = None,
+        on_shutdown: Sequence[NoArgAsyncCallable] | None = None,
+        after_startup: Sequence[NoArgAsyncCallable] | None = None,
+        after_shutdown: Sequence[NoArgAsyncCallable] | None = None,
+    ):
+        """Initializes the Application.
+
+        Args:
+            broker: The PubSubBroker instance.
+            on_startup: A sequence of callables to run on startup.
+            on_shutdown: A sequence of callables to run on shutdown.
+            after_startup: A sequence of callables to run after startup.
+            after_shutdown: A sequence of callables to run after shutdown.
+        """
+        self.broker = broker
+        self.apm = get_apm_provider()
+
+        self._on_startup: list[NoArgAsyncCallable] = []
+        if on_startup and isinstance(on_startup, Sequence):
+            for func in on_startup:
+                self.on_startup(func)
+
+        self._on_shutdown: list[NoArgAsyncCallable] = []
+        if on_shutdown and isinstance(on_shutdown, Sequence):
+            for func in on_shutdown:
+                self.on_shutdown(func)
+
+        self._after_startup: list[NoArgAsyncCallable] = []
+        if after_startup and isinstance(after_startup, Sequence):
+            for func in after_startup:
+                self.after_startup(func)
+
+        self._after_shutdown: list[NoArgAsyncCallable] = []
+        if after_shutdown and isinstance(after_shutdown, Sequence):
+            for func in after_shutdown:
+                self.after_shutdown(func)
+
+    @validate_call(config=ConfigDict(strict=True))
+    def on_startup(self, func: NoArgAsyncCallable) -> NoArgAsyncCallable:
+        """Decorator to register a function to run on startup.
+
+        Args:
+            func: The function to run on startup.
+
+        Returns:
+            The decorated function.
+        """
+        ensure_async_callable_function(func)
+        self._on_startup.append(func)
+        return func
+
+    @validate_call(config=ConfigDict(strict=True))
+    def on_shutdown(self, func: NoArgAsyncCallable) -> NoArgAsyncCallable:
+        """Decorator to register a function to run on shutdown.
+
+        Args:
+            func: The function to run on shutdown.
+
+        Returns:
+            The decorated function.
+        """
+        ensure_async_callable_function(func)
+        self._on_shutdown.append(func)
+        return func
+
+    @validate_call(config=ConfigDict(strict=True))
+    def after_startup(self, func: NoArgAsyncCallable) -> NoArgAsyncCallable:
+        """Decorator to register a function to run after startup.
+
+        Args:
+            func: The function to run after startup.
+
+        Returns:
+            The decorated function.
+        """
+        ensure_async_callable_function(func)
+        self._after_startup.append(func)
+        return func
+
+    @validate_call(config=ConfigDict(strict=True))
+    def after_shutdown(self, func: NoArgAsyncCallable) -> NoArgAsyncCallable:
+        """Decorator to register a function to run after shutdown.
+
+        Args:
+            func: The function to run after shutdown.
+
+        Returns:
+            The decorated function.
+        """
+        ensure_async_callable_function(func)
+        self._after_shutdown.append(func)
+        return func
+
+    # V1: Create a contextualizer
+    async def _start(self) -> None:
+        self.apm.start()
+        with self.apm.start_trace(name="start"):
+            context = {
+                "span_id": self.apm.get_span_id(),
+                "trace_id": self.apm.get_trace_id(),
+            }
+
+            with logger.contextualize(**context):
+                async with self._start_hooks():
+                    await self.broker.start()
+
+    @asynccontextmanager
+    async def _start_hooks(self) -> AsyncIterator[None]:
+        for func in self._on_startup:
+            await func()
+
+        yield
+
+        for func in self._after_startup:
+            await func()
+
+    async def _shutdown(self) -> None:
+        with self.apm.start_trace(name="shutdown"):
+            context = {
+                "span_id": self.apm.get_span_id(),
+                "trace_id": self.apm.get_trace_id(),
+            }
+            with logger.contextualize(**context):
+                async with self._shutdown_hooks():
+                    await self.broker.shutdown()
+
+        self.apm.shutdown()
+
+    @asynccontextmanager
+    async def _shutdown_hooks(self) -> AsyncIterator[None]:
+        for func in self._on_shutdown:
+            await func()
+
+        yield
+
+        for func in self._after_shutdown:
+            await func()
+
+
+class FastPubSub(FastAPI, Application):
+    """A FastAPI integration application for managing Pub/Sub consumers."""
+
+    def __init__(
+        self,
+        broker: PubSubBroker,
+        *,
+        on_startup: Sequence[NoArgAsyncCallable] | None = None,
+        on_shutdown: Sequence[NoArgAsyncCallable] | None = None,
+        after_startup: Sequence[NoArgAsyncCallable] | None = None,
+        after_shutdown: Sequence[NoArgAsyncCallable] | None = None,
+        liveness_url: str = "/consumers/alive",
+        readiness_url: str = "/consumers/ready",
+        **extras: Any,
+    ):
+        """Initializes the FastPubSub application.
+
+        Args:
+            broker: The PubSubBroker instance.
+            on_startup: A sequence of callables to run on startup.
+            on_shutdown: A sequence of callables to run on shutdown.
+            after_startup: A sequence of callables to run after startup.
+            after_shutdown: A sequence of callables to run after shutdown.
+            liveness_url: A url path for the readiness endpoint.
+            readiness_url: A url path for the readiness endpoint.
+            **extras: Extra arguments to pass to the FastAPI constructor.
+        """
+        self.lifespan_context = extras.pop("lifespan", None)
+        super().__init__(
+            lifespan=self._run,
+            **extras,
+        )
+
+        super(Starlette, self).__init__(
+            broker,
+            on_startup=on_startup,
+            on_shutdown=on_shutdown,
+            after_startup=after_startup,
+            after_shutdown=after_shutdown,
+        )
+
+        self.add_api_route(path=liveness_url, endpoint=self._get_liveness, methods=["GET"])
+        self.add_api_route(path=readiness_url, endpoint=self._get_readiness, methods=["GET"])
+
+    @asynccontextmanager
+    async def _run(self, app: "FastPubSub") -> AsyncGenerator[None]:
+        if not self.lifespan_context:
+            await self._start()
+            yield
+            await self._shutdown()
+        else:
+            async with self.lifespan_context(app):
+                await self._start()
+                yield
+                await self._shutdown()
+
+    async def _get_liveness(self, _: Request) -> JSONResponse:
+        alive = await self.broker.alive()
+
+        status_code = HTTP_200_OK
+        if not alive:
+            status_code = HTTP_500_INTERNAL_SERVER_ERROR
+
+        return JSONResponse(content={"alive": alive}, status_code=status_code)
+
+    async def _get_readiness(self, _: Request) -> JSONResponse:
+        ready = await self.broker.ready()
+
+        status_code = HTTP_200_OK
+        if not ready:
+            status_code = HTTP_500_INTERNAL_SERVER_ERROR
+
+        return JSONResponse(content={"ready": ready}, status_code=status_code)