34 |
35 | # Upgrade Guide
36 |
37 | Welcome to the Upgrade Guide for Pyventus `v0.7`! In this section, you will learn how to properly upgrade your application from Pyventus `v0.6` to `v0.7`, as well as address any potential issues related to breaking changes, ensuring a smooth transition to the latest version.
38 |
39 | ## Upgrading to the Latest Version
40 |
41 | Pyventus is published as a Python package and can be easily upgraded with `pip`. To get started, open up a terminal and upgrade Pyventus with the following command:
42 |
43 |
73 |
--------------------------------------------------------------------------------
/tests/pyventus/core/processing/fastapi/test_fastapi_processing_service.py:
--------------------------------------------------------------------------------
1 | from typing import Any
2 |
3 | import pytest
4 | from fastapi import BackgroundTasks, Depends, FastAPI
5 | from fastapi.testclient import TestClient
6 | from pyventus import PyventusException
7 | from pyventus.core.processing.fastapi import FastAPIProcessingService
8 | from starlette.status import HTTP_200_OK
9 | from typing_extensions import override
10 |
11 | from .....fixtures import CallableMock
12 | from ..processing_service_test import ProcessingServiceTest
13 |
14 |
15 | class TestFastAPIProcessingService(ProcessingServiceTest):
16 | # =================================
17 | # Test Cases for creation
18 | # =================================
19 |
20 | def test_creation_with_valid_input(self) -> None:
21 | # Arrange/Act
22 | processing_service = FastAPIProcessingService(background_tasks=BackgroundTasks())
23 |
24 | # Assert
25 | assert processing_service is not None
26 | assert isinstance(processing_service, FastAPIProcessingService)
27 |
28 | # =================================
29 |
30 | def test_creation_with_fastapi_depends(self) -> None:
31 | # Arrange
32 | client = TestClient(FastAPI())
33 |
34 | # Act/Assert
35 | @client.app.get("/") # type: ignore[attr-defined, misc]
36 | def api(
37 | processing_service: FastAPIProcessingService = Depends(FastAPIProcessingService), # noqa: B008
38 | ) -> None:
39 | assert processing_service is not None
40 | assert isinstance(processing_service, FastAPIProcessingService)
41 |
42 | res = client.get("/")
43 | assert res.status_code == HTTP_200_OK
44 |
45 | # =================================
46 |
47 | @pytest.mark.parametrize(
48 | ["background_tasks", "exception"],
49 | [
50 | (None, PyventusException),
51 | (True, PyventusException),
52 | (object(), PyventusException),
53 | (BackgroundTasks, PyventusException),
54 | ],
55 | )
56 | def test_creation_with_invalid_input(self, background_tasks: Any, exception: type[Exception]) -> None:
57 | # Arrange/Act/Assert
58 | with pytest.raises(exception):
59 | FastAPIProcessingService(background_tasks=background_tasks)
60 |
61 | # =================================
62 | # Test Cases for submission
63 | # =================================
64 |
65 | @override
66 | def handle_submission_in_sync_context(
67 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
68 | ) -> None:
69 | # Arrange
70 | client = TestClient(FastAPI())
71 |
72 | @client.app.get("/") # type: ignore[attr-defined, misc]
73 | def api(background_tasks: BackgroundTasks) -> None:
74 | processing_service = FastAPIProcessingService(background_tasks=background_tasks)
75 | processing_service.submit(callback, *args, **kwargs)
76 |
77 | # Act
78 | res = client.get("/")
79 |
80 | # Assert
81 | assert res.status_code == HTTP_200_OK
82 |
83 | # =================================
84 |
85 | @override
86 | async def handle_submission_in_async_context(
87 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
88 | ) -> None:
89 | # Arrange
90 | client = TestClient(FastAPI())
91 |
92 | @client.app.get("/") # type: ignore[attr-defined, misc]
93 | async def api(background_tasks: BackgroundTasks) -> None:
94 | processing_service = FastAPIProcessingService(background_tasks=background_tasks)
95 | processing_service.submit(callback, *args, **kwargs)
96 |
97 | # Act
98 | res = client.get("/")
99 |
100 | # Assert
101 | assert res.status_code == HTTP_200_OK
102 |
--------------------------------------------------------------------------------
/tests/pyventus/core/subscriptions/test_subscription.py:
--------------------------------------------------------------------------------
1 | from pickle import dumps, loads
2 | from typing import Any
3 |
4 | import pytest
5 | from pyventus import PyventusException
6 | from pyventus.core.subscriptions.subscription import Subscription
7 |
8 | from ....fixtures import CallableMock
9 | from ....utils import get_private_attr
10 |
11 |
12 | class TestSubscription:
13 | # =================================
14 | # Test Cases for creation
15 | # =================================
16 |
17 | def test_creation_with_valid_input(self) -> None:
18 | # Arrange/Act
19 | subscription = Subscription(teardown_callback=lambda s: True)
20 |
21 | # Assert
22 | assert subscription is not None
23 | assert isinstance(subscription, Subscription)
24 | assert subscription.timestamp is get_private_attr(subscription, "__timestamp")
25 |
26 | # =================================
27 |
28 | @pytest.mark.parametrize(
29 | ["teardown_callback", "exception"],
30 | [
31 | (None, PyventusException),
32 | (True, PyventusException),
33 | (object, PyventusException),
34 | (object(), PyventusException),
35 | ],
36 | )
37 | def test_creation_with_invalid_input(self, teardown_callback: Any, exception: type[Exception]) -> None:
38 | # Arrange/Act/Assert
39 | with pytest.raises(exception):
40 | Subscription(teardown_callback=teardown_callback)
41 |
42 | # =================================
43 | # Test Cases for unsubscribe
44 | # =================================
45 |
46 | def test_unsubscribe_execution(self) -> None:
47 | # Arrange
48 | teardown_callback = CallableMock.Sync(return_value=True)
49 | subscription = Subscription(teardown_callback=teardown_callback)
50 |
51 | # Act
52 | subscription.unsubscribe()
53 |
54 | # Assert
55 | assert teardown_callback.call_count == 1
56 | assert teardown_callback.last_args == (subscription,)
57 |
58 | # =================================
59 |
60 | def test_unsubscribe_with_exceptions(self) -> None:
61 | # Arrange
62 | teardown_callback = CallableMock.Sync(return_value=False, raise_exception=ValueError())
63 | subscription = Subscription(teardown_callback=teardown_callback)
64 |
65 | # Act
66 | with pytest.raises(ValueError):
67 | subscription.unsubscribe()
68 |
69 | # Assert
70 | assert teardown_callback.call_count == 1
71 | assert teardown_callback.last_args == (subscription,)
72 |
73 | # =================================
74 |
75 | @pytest.mark.parametrize(
76 | ["expected"],
77 | [(True,), (False,)],
78 | )
79 | def test_unsubscribe_return_value(self, expected: bool) -> None:
80 | # Arrange
81 | teardown_callback = CallableMock.Sync(return_value=expected)
82 | subscription = Subscription(teardown_callback=teardown_callback)
83 |
84 | # Act
85 | return_value = subscription.unsubscribe()
86 |
87 | # Assert
88 | assert teardown_callback.call_count == 1
89 | assert teardown_callback.last_args == (subscription,)
90 | assert return_value is expected
91 |
92 | # =================================
93 | # Test Cases for Serialization/Deserialization
94 | # =================================
95 |
96 | def test_pickle_serialization_and_deserialization(self) -> None:
97 | # Arrange
98 | teardown_callback = CallableMock.Sync(return_value=False)
99 | subscription = Subscription(teardown_callback=teardown_callback)
100 |
101 | # Act
102 | data = dumps(subscription)
103 | restored = loads(data)
104 |
105 | # Assert
106 | for attr in Subscription.__slots__:
107 | attr_name: str = f"_{type(restored).__name__}{attr}" if attr.startswith("__") else attr
108 | assert hasattr(restored, attr_name)
109 |
--------------------------------------------------------------------------------
/src/pyventus/core/subscriptions/subscription.py:
--------------------------------------------------------------------------------
1 | from collections.abc import Callable
2 | from datetime import datetime
3 | from typing import Any
4 |
5 | from typing_extensions import Self, override
6 |
7 | from ..utils import attributes_repr, get_callable_name, validate_callable
8 | from .unsubscribable import Unsubscribable
9 |
10 |
11 | class Subscription(Unsubscribable):
12 | """
13 | A base class that represents a subscription to a source.
14 |
15 | **Notes:**
16 |
17 | - This class encapsulates the subscription lifecycle and provides a
18 | mechanism for releasing or cleaning up any associated resources.
19 | """
20 |
21 | # Attributes for the Subscription
22 | __slots__ = ("__timestamp", "__teardown_callback")
23 |
24 | def __init__(self, teardown_callback: Callable[[Self], bool]) -> None:
25 | """
26 | Initialize an instance of `Subscription`.
27 |
28 | :param teardown_callback: A callback function invoked during the
29 | unsubscription process to perform cleanup or teardown operations
30 | associated with the subscription. It should return `True` if the
31 | cleanup was successful, or `False` if the teardown has already been
32 | executed and the subscription is no longer active.
33 | """
34 | # Validate the teardown callback
35 | validate_callable(teardown_callback)
36 |
37 | # Initialize attributes
38 | self.__timestamp: datetime = datetime.now()
39 | self.__teardown_callback: Callable[[Self], bool] = teardown_callback
40 |
41 | def __repr__(self) -> str:
42 | """
43 | Retrieve a string representation of the instance.
44 |
45 | :return: A string representation of the instance.
46 | """
47 | return attributes_repr(
48 | timestamp=self.__timestamp.strftime("%Y-%m-%d %I:%M:%S %p"),
49 | teardown_callback=get_callable_name(self.__teardown_callback),
50 | )
51 |
52 | @property
53 | def timestamp(self) -> datetime:
54 | """
55 | Retrieve the timestamp when the subscription was created.
56 |
57 | :return: The timestamp when the subscription was created.
58 | """
59 | return self.__timestamp
60 |
61 | @override
62 | def unsubscribe(self: Self) -> bool:
63 | return self.__teardown_callback(self)
64 |
65 | def __getstate__(self) -> dict[str, Any]:
66 | """
67 | Prepare the object state for serialization.
68 |
69 | This method is called when the object is pickled. It returns a dictionary
70 | containing the attributes that should be serialized. Only the attributes
71 | that are necessary for reconstructing the object in another process or
72 | context are included to improve efficiency and avoid issues with
73 | contextually irrelevant attributes.
74 |
75 | :return: A dictionary containing the serialized state of the object.
76 | """
77 | # Include only the attributes that are necessary for serialization
78 | # Attributes like __teardown_callback are not included as they are
79 | # context-specific and do not make sense in another scope/process.
80 | return {"__timestamp": self.__timestamp}
81 |
82 | def __setstate__(self, state: dict[str, Any]) -> None:
83 | """
84 | Restore the object from the serialized state.
85 |
86 | This method is called when the object is unpickled. It takes a dictionary
87 | containing the serialized state and restores the object's attributes.
88 | Additionally, it sets default values for attributes that were not serialized,
89 | ensuring the object remains in a valid state after deserialization.
90 |
91 | :param state: A dictionary containing the serialized state of the object.
92 | :return: None
93 | """
94 | # Restore the attributes from the serialized state
95 | self.__timestamp = state["__timestamp"]
96 |
97 | # Set default values for attributes that were not serialized
98 | self.__teardown_callback = lambda sub: False
99 |
--------------------------------------------------------------------------------
/docs/learn/events/emitters/asyncio.md:
--------------------------------------------------------------------------------
1 | # AsyncIO Event Emitter
2 |
3 |
44 | ```console
45 | pip install -U pyventus
46 | ```
47 |
48 |
49 | ## Reviewing Key Breaking Changes
50 |
51 | Please review the following breaking changes and apply the necessary actions to effectively update your application. You can mark each item as complete to track your progress.
52 |
53 | - [ ] All previous event-driven features must now be imported from the new inner package `pyventus.events` instead of directly from `pyventus` or its submodules.
54 | - [ ] The inheritance structure of the `EventEmitter` has been replaced with composition using the `ProcessingService`. Custom event emitters must now be implemented through the `ProcessingService` interface and composed with the `EventEmitter` class.
55 | - [ ] The `EventLinker` has experienced some method renames and return type modifications to align with the new redesigned codebase:
56 | - [ ] `remove_event_handler()` → `remove_subscriber()`.
57 | - [ ] `get_event_handlers()` → `get_subscribers()`: Now returns a `set` instead of a `list`.
58 | - [ ] `get_events_by_event_handler()` → `get_events_from_subscribers()`: Now returns a `set` instead of a `list` and supports retrieving events for multiple subscribers.
59 | - [ ] `get_event_handlers_by_events()` → `get_subscribers_from_events()`: Now returns a `set` instead of a `list` and includes a new flag `pop_onetime_subscribers`.
60 | - [ ] `unsubscribe()` → `remove()`: Now removes one event from a subscriber at a time.
61 | - [ ] Parameters named `event_handler` have been renamed to `subscriber` in all methods.
62 | - [ ] `get_events()`: Now returns a `set` instead of a `list` with non-duplicates.
63 | - [ ] The `RQEventEmitter` has been renamed to `RedisEventEmitter`.
64 | - [ ] The `CeleryEventEmitter.Queue` has been removed, and the `CeleryEventEmitter` now requires a `Celery` instance. Security aspects have been delegated to the `Celery` app.
65 | - [ ] Dependency injection for the `FastAPIEventEmitter` through FastAPI's `Depends()` function has been simplified; use `Depends(FastAPIEventEmitter())` for all scenarios.
66 | - [ ] The `ExecutorEventEmitter` can no longer be used as a context manager; for this purpose, use the new `ExecutorEventEmitterCtx`.
67 |
68 | ## Questions and Issues
69 |
70 | If you have any questions or run into issues during the upgrade process, please feel free to open a new issue or start a discussion. Before doing so, it is recommended to check for existing inquiries to avoid duplicates.
71 |
72 | 4 | In Pyventus, you can easily integrate Event Emitters with the AsyncIO framework through the AsyncIO Processing Service. Simply create an instance of the AsyncIO Processing Service and pass it as the event processor when setting up the Event Emitter, or you can use the factory method called AsyncIO Event Emitter to handle the setup in a single step. 5 |
6 | 7 | === ":material-console: Manual Configuration" 8 | 9 | ```Python linenums="1" hl_lines="1 2 4" 10 | from pyventus.events import EventEmitter 11 | from pyventus.core.processing.asyncio import AsyncIOProcessingService 12 | 13 | event_emitter = EventEmitter(event_processor=AsyncIOProcessingService()) 14 | event_emitter.emit("MyEvent") 15 | ``` 16 | 17 | === ":material-factory: Factory Method" 18 | 19 | ```Python linenums="1" hl_lines="1 4" 20 | from pyventus.events import AsyncIOEventEmitter, EventEmitter 21 | 22 | 23 | event_emitter: EventEmitter = AsyncIOEventEmitter() 24 | event_emitter.emit("MyEvent") 25 | ``` 26 | 27 |28 | By utilizing the AsyncIO Processing Service, the execution of each event emission will be handled by the AsyncIO event loop. 29 |
30 | 31 | ## AsyncIO Behavior 32 | 33 |34 | It is important to note that the AsyncIO Processing Service handles the execution of each event emission differently depending on whether an AsyncIO loop is already running (async context) or not (sync context). If there isn’t an active loop, it uses the `asyncio.run()` method to execute the event emission, creating a new loop, waiting for the event emission to finish, and finally closing it. If a loop is already running, the service simply schedules the event emission as a background task using the `asyncio.create_task()`. 35 |
36 | 37 | !!! tip "Event Emission is Silently Discarded" 38 | 39 |40 | When working with async contexts, it is important to properly handle the underlying AsyncIO loop, as the AsyncIO Processing Service simply schedules tasks to it. If the AsyncIO loop closes before all submitted callbacks are complete, they will be discarded. 41 |
42 | 43 | ## Practical Example 44 | 45 | === "`Sync` contexts" 46 | 47 | ```Python linenums="1" hl_lines="3 12 18 19" 48 | import asyncio 49 | 50 | from pyventus.core.processing.asyncio import AsyncIOProcessingService 51 | from pyventus.events import EventEmitter, EventLinker 52 | 53 | 54 | async def handle_event_with_delay(): 55 | await asyncio.sleep(1.5) 56 | print("Done!") 57 | 58 | 59 | def main(): 60 | print("Starting...") 61 | 62 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 63 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 64 | 65 | event_processor = AsyncIOProcessingService() 66 | event_emitter = EventEmitter(event_processor=event_processor) 67 | 68 | event_emitter.emit("MyEvent") 69 | event_emitter.emit("MyEvent") 70 | 71 | print("Closing...") 72 | 73 | 74 | 75 | main() 76 | ``` 77 | 78 | === "`Async` contexts" 79 | 80 | ```Python linenums="1" hl_lines="3 12 18 19 25" 81 | import asyncio 82 | 83 | from pyventus.core.processing.asyncio import AsyncIOProcessingService 84 | from pyventus.events import EventEmitter, EventLinker 85 | 86 | 87 | async def handle_event_with_delay(): 88 | await asyncio.sleep(1.5) 89 | print("Done!") 90 | 91 | 92 | async def main(): 93 | print("Starting...") 94 | 95 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 96 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 97 | 98 | event_processor = AsyncIOProcessingService() 99 | event_emitter = EventEmitter(event_processor=event_processor) 100 | 101 | event_emitter.emit("MyEvent") 102 | event_emitter.emit("MyEvent") 103 | 104 | print("Closing...") 105 | await event_processor.wait_for_tasks() 106 | 107 | 108 | asyncio.run(main()) 109 | ``` 110 | -------------------------------------------------------------------------------- /src/pyventus/core/loggers/logger.py: -------------------------------------------------------------------------------- 1 | from ..utils import attributes_repr, formatted_repr, summarized_repr 2 | from .stdout_logger import ExcInfoType, StdOutLogger 3 | 4 | 5 | class Logger: 6 | """A custom logger class that wraps the `StdOutLogger` and provides additional functionality.""" 7 | 8 | # Attributes for the Logger 9 | __slots__ = ("__source", "__debug") 10 | 11 | def __init__(self, source: str | type | object | None = None, debug: bool = False): 12 | """ 13 | Initialize an instance of `Logger`. 14 | 15 | :param source: The source of the log message, which can be a string, type, or object. Defaults to None. 16 | :param debug: A flag indicating whether debug mode is enabled. 17 | """ 18 | # Variable to hold the name of the source. 19 | source_name: str 20 | 21 | # Determine the name of the source based on its type. 22 | if source is None: 23 | source_name = summarized_repr(self) 24 | elif isinstance(source, str): 25 | source_name = source 26 | elif isinstance(source, type): 27 | source_name = f"{source.__name__}(ClassReference)" 28 | else: 29 | source_name = summarized_repr(source) 30 | 31 | # Store the determined source name and debug flag. 32 | self.__source: str = source_name 33 | self.__debug = debug 34 | 35 | def __repr__(self) -> str: 36 | """ 37 | Retrieve a string representation of the instance. 38 | 39 | :return: A string representation of the instance. 40 | """ 41 | return formatted_repr( 42 | instance=self, 43 | info=attributes_repr( 44 | source=self.__source, 45 | debug=self.__debug, 46 | ), 47 | ) 48 | 49 | @property 50 | def debug_enabled(self) -> bool: 51 | """ 52 | Return a boolean value indicating whether debug mode is enabled. 53 | 54 | :return: `True` if debug mode is enabled, `False` otherwise. 55 | """ 56 | return self.__debug 57 | 58 | def critical(self, msg: str, action: str | None = None, exc_info: ExcInfoType = None) -> None: 59 | """ 60 | Log a CRITICAL level message. 61 | 62 | :param msg: The message to be logged. 63 | :param action: The action or method associated with the log. Defaults to None. 64 | :param exc_info: Exception information to be logged. Defaults to None. 65 | :return: None. 66 | """ 67 | StdOutLogger.critical(msg=msg, source=self.__source, action=action, exc_info=exc_info) 68 | 69 | def error(self, msg: str, action: str | None = None, exc_info: ExcInfoType = None) -> None: 70 | """ 71 | Log an ERROR level message. 72 | 73 | :param msg: The message to be logged. 74 | :param action: The action or method associated with the log. Defaults to None. 75 | :param exc_info: Exception information to be logged. Defaults to None. 76 | :return: None. 77 | """ 78 | StdOutLogger.error(msg=msg, source=self.__source, action=action, exc_info=exc_info) 79 | 80 | def warning(self, msg: str, action: str | None = None) -> None: 81 | """ 82 | Log a WARNING level message. 83 | 84 | :param msg: The message to be logged. 85 | :param action: The action or method associated with the log. Defaults to None. 86 | :return: None. 87 | """ 88 | StdOutLogger.warning(msg=msg, source=self.__source, action=action) 89 | 90 | def info(self, msg: str, action: str | None = None) -> None: 91 | """ 92 | Log an INFO level message. 93 | 94 | :param msg: The message to be logged. 95 | :param action: The action or method associated with the log. Defaults to None. 96 | :return: None. 97 | """ 98 | StdOutLogger.info(msg=msg, source=self.__source, action=action) 99 | 100 | def debug(self, msg: str, action: str | None = None) -> None: 101 | """ 102 | Log a DEBUG level message. 103 | 104 | :param msg: The message to be logged. 105 | :param action: The action or method associated with the log. Defaults to None. 106 | :return: None. 107 | """ 108 | StdOutLogger.debug(msg=msg, source=self.__source, action=action) 109 | -------------------------------------------------------------------------------- /docs/learn/events/emitters/fastapi.md: -------------------------------------------------------------------------------- 1 | 9 | 10 | # FastAPI Event Emitter 11 | 12 |13 | In Pyventus, you can easily integrate Event Emitters with the FastAPI framework through the FastAPI Processing Service. Simply create an instance of the FastAPI Processing Service and pass it as the event processor when setting up the Event Emitter, or you can use the factory method called FastAPI Event Emitter to handle the setup in a single step. 14 |
15 | 16 | === ":material-console: Manual Configuration" 17 | 18 | ```Python linenums="1" hl_lines="1-3 5 9 10" 19 | from fastapi import BackgroundTasks, FastAPI 20 | from pyventus.core.processing.fastapi import FastAPIProcessingService 21 | from pyventus.events import EventEmitter 22 | 23 | app = FastAPI() 24 | 25 | 26 | @app.get("/") 27 | def read_root(background_tasks: BackgroundTasks): 28 | event_emitter = EventEmitter(event_processor=FastAPIProcessingService(background_tasks)) 29 | event_emitter.emit("MyEvent") 30 | return {"Event": "Emitted"} 31 | ``` 32 | 33 | === ":material-factory: Factory Method" 34 | 35 | ```Python linenums="1" hl_lines="1-2 4 8" 36 | from fastapi import Depends, FastAPI 37 | from pyventus.events import EventEmitter, FastAPIEventEmitter 38 | 39 | app = FastAPI() 40 | 41 | 42 | @app.get("/") 43 | def read_root(event_emitter: EventEmitter = Depends(FastAPIEventEmitter())): 44 | event_emitter.emit("MyEvent") 45 | return {"Event": "Emitted"} 46 | ``` 47 | 48 |49 | By utilizing the FastAPI Processing Service, the execution of each event emission will be handled by the FastAPI's Background Tasks system. 50 |
51 | 52 | ## Practical Example 53 | 54 |55 | To start using the Event Emitter with FastAPI, follow these steps: 56 |
57 | 58 | 1.Install Dependencies: 59 | Before proceeding, ensure that you have installed the optional [FastAPI dependency](../../../getting-started.md/#optional-dependencies). 60 |
61 | 62 | 2.Subscribe and Emit: 63 | Once you have everything installed and configured, using Pyventus with FastAPI is straightforward. Simply define your subscribers and events, instantiate an Event Emitter configured for FastAPI, and emit your events. 64 |
65 | 66 | ```Python title="main.py" linenums="1" hl_lines="3-4 7-8 14 20 22" 67 | import time 68 | 69 | from fastapi import Depends, FastAPI 70 | from pyventus.events import EventEmitter, EventLinker, FastAPIEventEmitter 71 | 72 | 73 | @EventLinker.on("SendEmail") 74 | def handle_email_notification(email: str) -> None: 75 | print(f"Sending email to: {email}") 76 | time.sleep(2.5) # Simulate sending delay. 77 | print("Email sent successfully!") 78 | 79 | 80 | app = FastAPI() 81 | 82 | 83 | @app.get("/email") 84 | def send_email( 85 | email_to: str, 86 | event_emitter: EventEmitter = Depends(FastAPIEventEmitter()), 87 | ) -> None: 88 | event_emitter.emit("SendEmail", email_to) 89 | return {"message": "Email sent!"} 90 | ``` 91 | 92 | To start the FastAPI server, run the following command: 93 | 94 |
95 | ```console
96 | fastapi dev main.py
97 | ```
98 |
99 |
100 | Open your browser and navigate to http://127.0.0.1:8000/email?email_to=email@email.com. You should see the following JSON response:
101 |
102 | ```JSON
103 | { "message": "Email sent!" }
104 | ```
105 |
106 | Additionally, you will be able to view the output of the functions in the console logs.
107 |
108 | ```console
109 | INFO Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
110 | INFO Started reloader process [12604] using WatchFiles
111 | INFO Started server process [7008]
112 | INFO Waiting for application startup.
113 | INFO Application startup complete.
114 | INFO 127.0.0.1:49763 - "GET /email?email_to=email@email.com HTTP/1.1" 200
115 | Sending email to: email@email.com
116 | Email sent successfully!
117 | ```
118 |
--------------------------------------------------------------------------------
/src/pyventus/core/processing/asyncio/asyncio_processing_service.py:
--------------------------------------------------------------------------------
1 | from asyncio import Task, create_task, gather, get_running_loop, run
2 | from typing import Any
3 |
4 | from typing_extensions import override
5 |
6 | from ...utils import attributes_repr, formatted_repr, is_callable_async
7 | from ..processing_service import ProcessingService, ProcessingServiceCallbackType
8 |
9 |
10 | class AsyncIOProcessingService(ProcessingService):
11 | """
12 | A processing service that utilizes the `AsyncIO` framework to handle the execution of calls.
13 |
14 | **Notes:**
15 |
16 | - When the provided callback is a synchronous call, it will be executed in a blocking manner, regardless
17 | of whether an event loop is active. However, if the synchronous callback involves I/O or non-CPU-bound
18 | operations, it can be offloaded to a thread pool using `asyncio.to_thread()` from the `AsyncIO` framework.
19 |
20 | - When the provided callback is an asynchronous call and is submitted in a context where an event loop is
21 | already running, the callback is scheduled and processed on that existing loop. If the event loop exits
22 | before all calls are completed, any remaining scheduled calls will be canceled.
23 |
24 | - When the provided callback is an asynchronous call and is submitted in a context where no event loop is
25 | active, a new event loop is started and subsequently closed by the `asyncio.run()` method. Within this
26 | loop, the callback is executed, and the loop waits for all scheduled tasks to finish before closing.
27 | """
28 |
29 | @staticmethod
30 | def is_loop_running() -> bool:
31 | """
32 | Determine whether there is currently an active `AsyncIO` event loop.
33 |
34 | :return: `True` if an event loop is running; `False` otherwise.
35 | """
36 | try:
37 | get_running_loop()
38 | return True
39 | except RuntimeError:
40 | return False
41 |
42 | # Attributes for the AsyncIOProcessingService
43 | __slots__ = ("__background_tasks",)
44 |
45 | def __init__(self) -> None:
46 | """
47 | Initialize an instance of `AsyncIOProcessingService`.
48 |
49 | :return: None.
50 | """
51 | # Initialize the set of background tasks
52 | self.__background_tasks: set[Task[Any]] = set()
53 |
54 | def __repr__(self) -> str:
55 | """
56 | Retrieve a string representation of the instance.
57 |
58 | :return: A string representation of the instance.
59 | """
60 | return formatted_repr(
61 | instance=self,
62 | info=attributes_repr(
63 | background_tasks=self.__background_tasks,
64 | ),
65 | )
66 |
67 | @override
68 | def submit(self, callback: ProcessingServiceCallbackType, *args: Any, **kwargs: Any) -> None:
69 | # Check if the callback is asynchronous and execute accordingly.
70 | if is_callable_async(callback):
71 | # Check if there is an active event loop.
72 | loop_running: bool = AsyncIOProcessingService.is_loop_running()
73 |
74 | if loop_running:
75 | # Schedule the callback in the running loop as a background task.
76 | task: Task[Any] = create_task(callback(*args, **kwargs))
77 |
78 | # Add a callback to remove the Task from the set of background tasks upon completion.
79 | task.add_done_callback(self.__background_tasks.discard)
80 |
81 | # Add the Task to the set of background tasks.
82 | self.__background_tasks.add(task)
83 | else:
84 | # Execute the callback in a blocking manner if no event loop is active.
85 | run(callback(*args, **kwargs))
86 | else:
87 | # Execute the callback directly if it is not an asynchronous call.
88 | callback(*args, **kwargs)
89 |
90 | async def wait_for_tasks(self) -> None:
91 | """
92 | Wait for all background tasks associated with the current service to complete.
93 |
94 | This method ensures that any ongoing tasks are finished before proceeding.
95 |
96 | :return: None.
97 | """
98 | # Retrieve the current set of background tasks and clear the registry.
99 | tasks: set[Task[Any]] = self.__background_tasks.copy()
100 | self.__background_tasks.clear()
101 |
102 | # Await the completion of all background tasks.
103 | await gather(*tasks)
104 |
--------------------------------------------------------------------------------
/docs/learn/events/emitters/executor.md:
--------------------------------------------------------------------------------
1 | # Executor Event Emitter
2 |
3 | 4 | In Pyventus, you can easily integrate Event Emitters with threads or processes through the Executor Processing Service. Simply create an instance of the Executor Processing Service and pass it as the event processor when setting up the Event Emitter, or you can use the factory method called Executor Event Emitter to handle the setup in a single step. 5 |
6 | 7 | === ":material-console: Manual Configuration" 8 | 9 | ```Python linenums="1" hl_lines="1 3 8 10" 10 | from concurrent.futures import ThreadPoolExecutor 11 | 12 | from pyventus.core.processing.executor import ExecutorProcessingService 13 | from pyventus.events import EventEmitter 14 | 15 | 16 | if __name__ == "__main__": 17 | executor = ThreadPoolExecutor() 18 | 19 | event_emitter = EventEmitter(event_processor=ExecutorProcessingService(executor)) 20 | event_emitter.emit("MyEvent") 21 | 22 | executor.shutdown() 23 | ``` 24 | 25 | === ":material-factory: Factory Method" 26 | 27 | ```Python linenums="1" hl_lines="1 3 8 10" 28 | from concurrent.futures import ThreadPoolExecutor 29 | 30 | from pyventus.events import ExecutorEventEmitter 31 | 32 | 33 | 34 | if __name__ == "__main__": 35 | executor = ThreadPoolExecutor() 36 | 37 | event_emitter = ExecutorEventEmitter(executor) 38 | event_emitter.emit("MyEvent") 39 | 40 | executor.shutdown() 41 | ``` 42 | 43 | === ":material-code-block-tags: Context Manager" 44 | 45 | ```Python linenums="1" hl_lines="1 3 7" 46 | from concurrent.futures import ThreadPoolExecutor 47 | 48 | from pyventus.events import ExecutorEventEmitterCtx 49 | 50 | 51 | if __name__ == "__main__": 52 | with ExecutorEventEmitterCtx(executor=ThreadPoolExecutor()) as event_emitter: 53 | event_emitter.emit("MyEvent") 54 | ``` 55 | 56 |57 | By utilizing the Executor Processing Service, the execution of each event emission will be handled by the given Thread/Process executor. 58 |
59 | 60 | ## Executor Management 61 | 62 |63 | It is important to properly manage the underlying Executor when using the Executor Processing Service. Once you've finished emitting events, call the `shutdown()` method to signal the executor to free any resources associated with pending futures, or use the `with` statement, which will automatically shut down the Executor. 64 |
65 | 66 | ## Practical Example 67 | 68 | === "Using `ThreadPoolExecutor`" 69 | 70 | ```Python linenums="1" hl_lines="2 4 18-21" 71 | import time 72 | from concurrent.futures import ThreadPoolExecutor 73 | 74 | from pyventus.events import EventLinker, ExecutorEventEmitter 75 | 76 | 77 | def handle_event_with_delay(): 78 | time.sleep(1.5) 79 | print("Done!") 80 | 81 | 82 | if __name__ == "__main__": 83 | print("Starting...") 84 | 85 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 86 | EventLinker.subscribe("MyEvent", event_callback=handle_event_with_delay) 87 | 88 | with ThreadPoolExecutor() as executor: 89 | event_emitter = ExecutorEventEmitter(executor) 90 | event_emitter.emit("MyEvent") 91 | event_emitter.emit("MyEvent") 92 | 93 | print("Closing...") 94 | ``` 95 | 96 | === "Using `ProcessPoolExecutor`" 97 | 98 | ```Python linenums="1" hl_lines="1 3 19-22" 99 | from concurrent.futures import ProcessPoolExecutor 100 | 101 | from pyventus.events import EventLinker, ExecutorEventEmitter 102 | 103 | def fibonacci(n): 104 | if n <= 1: 105 | return n 106 | return fibonacci(n - 1) + fibonacci(n - 2) 107 | 108 | if __name__ == "__main__": 109 | print("Starting...") 110 | 111 | EventLinker.subscribe( 112 | "Fibonacci", 113 | event_callback=fibonacci, 114 | success_callback=print, 115 | ) 116 | 117 | with ProcessPoolExecutor() as executor: 118 | event_emitter = ExecutorEventEmitter(executor) 119 | event_emitter.emit("Fibonacci", 35) 120 | event_emitter.emit("Fibonacci", 35) 121 | 122 | print("Closing...") 123 | ``` 124 | 125 | !!! warning "Picklable Objects Required for `ProcessPoolExecutor`" 126 | 127 |128 | When working with the `ProcessPoolExecutor`, it is essential to ensure that all objects involved in the event emission are picklable. 129 |
130 | -------------------------------------------------------------------------------- /docs/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | hide: 3 | - navigation 4 | --- 5 | 6 | 14 | 15 |16 | Welcome to the Getting Started section! In this guide, you will learn how to install Pyventus, as well as enable any of its optional dependencies. For more detailed information on how to use this library, you can refer to the [API](api/index.md) and [Learn](learn/index.md) sections. 17 |
18 | 19 | ## Installation 20 | 21 |
22 | Pyventus is published as a Python package and can be installed using pip, ideally in a virtual environment for proper dependency isolation. To get started, open up a terminal and install Pyventus with the following command:
23 |
26 | ```console
27 | pip install pyventus
28 | ```
29 |
30 |
31 |
32 | By default, Pyventus relies on the Python standard library and requires Python 3.10 or higher with no additional dependencies aside from typing-extensions, which is primarily used to support advanced typing features in older versions of Python.
33 |
38 | While Pyventus primarily relies on the Python standard library, it also supports optional dependencies to access additional features, such as different processing services[^1]. Below is a list of supported integrations: 39 |
40 | 41 | ### Supported Library Integrations 42 | 43 | -Celery ─ 44 | Pyventus integrates with Celery through the `CeleryProcessingService`, which is a concrete implementation of the `ProcessingService` interface that leverages the Celery framework to handle the execution of calls. To install Pyventus with Celery support, use the following command: 45 |
46 | 47 |
48 | ```console
49 | pip install pyventus[celery] (1)
50 | ```
51 |
52 |
53 | 1. Optional Package Dependencies
54 |55 | This package also includes optional dependencies. For more information, please visit the Celery documentation. 56 |
57 | 58 | *** 59 | 60 | -Redis Queue (RQ) ─ 61 | Pyventus integrates with Redis Queue through the `RedisProcessingService`, which is a concrete implementation of the `ProcessingService` interface that leverages the Redis Queue framework to handle the execution of calls. To install Pyventus with Redis Queue support, use the following command: 62 |
63 | 64 |
65 | ```console
66 | pip install pyventus[rq]
67 | ```
68 |
69 |
70 | ### Supported Framework Integrations
71 |
72 | - FastAPI ─ 73 | Pyventus integrates with FastAPI through the `FastAPIProcessingService`, which is a concrete implementation of the `ProcessingService` interface that utilizes the FastAPI's `BackgroundTasks` to handle the execution of calls. To install Pyventus with FastAPI integration, use the following command: 74 |
75 | 76 |
77 | ```console
78 | pip install pyventus[fastapi] (1)
79 | ```
80 |
81 |
82 | 1. Optional Package Dependencies
83 |84 | This package also includes optional dependencies. For more information, please visit the FastAPI documentation. 85 |
86 | 87 | --- 88 | 89 | You can install all of these integrations simultaneously using: 90 | 91 |
92 | ```console
93 | pip install pyventus[all]
94 | ```
95 |
96 |
97 | [^1]: These processing services expand the capabilities of Pyventus by providing different strategies for processing calls. For instance, the `EventEmitter` class leverages these services to decouple the processing of each event emission from the underlying implementation, resulting in a more flexible and efficient execution mechanism that enhances the responsiveness and scalability of event handling.
98 |
--------------------------------------------------------------------------------
/src/pyventus/core/processing/executor/executor_processing_service.py:
--------------------------------------------------------------------------------
1 | from asyncio import run
2 | from concurrent.futures import Executor
3 | from types import TracebackType
4 | from typing import Any
5 |
6 | from typing_extensions import Self, override
7 |
8 | from ...exceptions import PyventusException
9 | from ...utils import attributes_repr, formatted_repr, is_callable_async
10 | from ..processing_service import ProcessingService, ProcessingServiceCallbackType
11 |
12 |
13 | class ExecutorProcessingService(ProcessingService):
14 | """
15 | A processing service that utilizes the `concurrent.futures.Executor` to handle the execution of calls.
16 |
17 | **Notes:**
18 |
19 | - This service uses the `concurrent.futures.Executor` for processing the callbacks' execution. It
20 | can work with either a `ThreadPoolExecutor` for thread-based execution or a `ProcessPoolExecutor`
21 | for process-based execution.
22 |
23 | - Synchronous callbacks are executed in a blocking manner inside the executor, while asynchronous
24 | callbacks are processed within a new asyncio event loop using the `asyncio.run()` function.
25 |
26 | - When using this service, it is important to properly manage the underlying `Executor`. Once
27 | there are no more calls to be processed through the given executor, it's important to invoke
28 | the `shutdown()` method to signal the executor to free any resources for pending futures. You
29 | can avoid the need to call this method explicitly by using the `with` statement, which
30 | automatically shuts down the `Executor`.
31 | """
32 |
33 | @staticmethod
34 | def _execute(callback: ProcessingServiceCallbackType, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
35 | """
36 | Execute the provided callback with the given arguments.
37 |
38 | This method is intended to be used within the executor to execute the callback.
39 |
40 | :param callback: The callback to be executed.
41 | :param args: Positional arguments to be passed to the callback.
42 | :param kwargs: Keyword arguments to be passed to the callback.
43 | :return: None.
44 | """
45 | # Check if the callback is asynchronous and execute accordingly.
46 | if is_callable_async(callback):
47 | # Run the async callback in a new asyncio event loop.
48 | run(callback(*args, **kwargs))
49 | else:
50 | # Run the sync callback directly with the provided arguments.
51 | callback(*args, **kwargs)
52 |
53 | # Attributes for the ExecutorProcessingService.
54 | __slots__ = ("__executor",)
55 |
56 | def __init__(self, executor: Executor) -> None:
57 | """
58 | Initialize an instance of `ExecutorProcessingService`.
59 |
60 | :param executor: The executor object used to handle the callbacks' execution.
61 | :return: None.
62 | :raises PyventusException: If the executor is not provided or is not an instance of `Executor`.
63 | """
64 | # Validate the executor instance.
65 | if executor is None or not isinstance(executor, Executor):
66 | raise PyventusException("The 'executor' argument must be an instance of Executor.")
67 |
68 | # Store the executor instance.
69 | self.__executor: Executor = executor
70 |
71 | def __repr__(self) -> str:
72 | """
73 | Retrieve a string representation of the instance.
74 |
75 | :return: A string representation of the instance.
76 | """
77 | return formatted_repr(
78 | instance=self,
79 | info=attributes_repr(
80 | executor=self.__executor,
81 | ),
82 | )
83 |
84 | @override
85 | def submit(self, callback: ProcessingServiceCallbackType, *args: Any, **kwargs: Any) -> None:
86 | # Submit the callback to the executor along with its arguments.
87 | self.__executor.submit(self.__class__._execute, callback, args, kwargs)
88 |
89 | def shutdown(self, wait: bool = True, cancel_futures: bool = False) -> None:
90 | """
91 | Shut down the executor and release any resources it is using.
92 |
93 | :param wait: A boolean indicating whether to wait for the currently pending futures
94 | to complete before shutting down.
95 | :param cancel_futures: A boolean indicating whether to cancel any pending futures.
96 | :return: None.
97 | """
98 | self.__executor.shutdown(wait=wait, cancel_futures=cancel_futures)
99 |
100 | def __enter__(self) -> Self:
101 | """
102 | Return the current instance of `ExecutorProcessingService` for context management.
103 |
104 | :return: The current instance of `ExecutorProcessingService`.
105 | """
106 | return self
107 |
108 | def __exit__(
109 | self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
110 | ) -> None:
111 | """
112 | Clean up the executor resources when exiting the context.
113 |
114 | :param exc_type: The exception type, if any.
115 | :param exc_val: The exception value, if any.
116 | :param exc_tb: The traceback information, if any.
117 | :return: None.
118 | """
119 | self.shutdown(wait=True, cancel_futures=False)
120 |
--------------------------------------------------------------------------------
/tests/pyventus/core/processing/celery/test_celery_processing_service.py:
--------------------------------------------------------------------------------
1 | from concurrent.futures import ThreadPoolExecutor
2 | from typing import Any
3 | from unittest.mock import patch
4 |
5 | import pytest
6 | from celery import Celery
7 | from pyventus import PyventusException
8 | from typing_extensions import override
9 |
10 | from .....fixtures import CallableMock
11 | from ..processing_service_test import ProcessingServiceTest
12 |
13 |
14 | class CeleryMock(Celery): # type: ignore[misc]
15 | """
16 | A mock implementation of the Celery class for testing purposes.
17 |
18 | This class simulates the behavior of a Celery worker, allowing for the
19 | testing of task submissions without requiring a real Celery backend. It
20 | provides a way to invoke tasks by name with the given arguments.
21 | """
22 |
23 | def send_task(self, *args: Any, **kwargs: Any) -> None:
24 | """Simulate sending a task to the Celery worker."""
25 |
26 | # Use a new thread to separate the execution of the task from the current test thread.
27 | with ThreadPoolExecutor() as executor:
28 | fut = executor.submit(self.tasks[kwargs["name"]], *kwargs["args"])
29 |
30 | # Retrieve the results and raise
31 | # any exceptions that occurred.
32 | fut.result()
33 |
34 |
35 | class TestCeleryProcessingService(ProcessingServiceTest):
36 | # =================================
37 | # Test Cases for creation
38 | # =================================
39 |
40 | @pytest.mark.parametrize(
41 | ["celery", "queue"],
42 | [
43 | (CeleryMock(), None),
44 | (CeleryMock(), "Queue"),
45 | ],
46 | )
47 | def test_creation_with_valid_input(self, celery: Celery, queue: str) -> None:
48 | from pyventus.core.processing.celery import CeleryProcessingService
49 |
50 | # Arrange/Act
51 | processing_service = CeleryProcessingService(celery=celery, queue=queue)
52 |
53 | # Assert
54 | assert processing_service is not None
55 | assert isinstance(processing_service, CeleryProcessingService)
56 |
57 | # =================================
58 |
59 | @pytest.mark.parametrize(
60 | ["celery", "queue", "exception"],
61 | [
62 | (None, None, PyventusException),
63 | (True, None, PyventusException),
64 | (object(), None, PyventusException),
65 | (CeleryMock, None, PyventusException),
66 | (CeleryMock(), "", PyventusException),
67 | ],
68 | )
69 | def test_creation_with_invalid_input(self, celery: Any, queue: str | None, exception: type[Exception]) -> None:
70 | from pyventus.core.processing.celery import CeleryProcessingService
71 |
72 | # Arrange/Act/Assert
73 | with pytest.raises(exception):
74 | CeleryProcessingService(celery=celery, queue=queue)
75 |
76 | # =================================
77 | # Test Cases for task registration
78 | # =================================
79 |
80 | def test_task_registration(self) -> None:
81 | from pyventus.core.processing.celery import CeleryProcessingService
82 |
83 | # Arrange/Act
84 | CeleryProcessingService.register()
85 |
86 | # Assert
87 | assert CeleryProcessingService.CELERY_TASK_NAME in CeleryMock().tasks
88 |
89 | # =================================
90 | # Test Cases for submission
91 | # =================================
92 |
93 | @override
94 | def handle_submission_in_sync_context(
95 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
96 | ) -> None:
97 | # Use patching to override the behavior of pickle.dumps and pickle.loads.
98 | # This ensures that objects are not serialized or deserialized during testing,
99 | # allowing access to callback metrics for assertions such as call count and others.
100 | with (
101 | patch("pickle.dumps", new=lambda obj: obj),
102 | patch("pickle.loads", new=lambda obj: obj),
103 | ):
104 | from pyventus.core.processing.celery import CeleryProcessingService
105 |
106 | # Arrange: Register the service task and create a new Celery processing service.
107 | CeleryProcessingService.register()
108 | processing_service = CeleryProcessingService(celery=CeleryMock())
109 |
110 | # Act: Submit the callback to the processing service with the provided arguments.
111 | processing_service.submit(callback, *args, **kwargs)
112 |
113 | # =================================
114 |
115 | @override
116 | async def handle_submission_in_async_context(
117 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
118 | ) -> None:
119 | # Use patching to override the behavior of pickle.dumps and pickle.loads.
120 | # This ensures that objects are not serialized or deserialized during testing,
121 | # allowing access to callback metrics for assertions such as call count and others.
122 | with (
123 | patch("pickle.dumps", new=lambda obj: obj),
124 | patch("pickle.loads", new=lambda obj: obj),
125 | ):
126 | from pyventus.core.processing.celery import CeleryProcessingService
127 |
128 | # Arrange: Register the service task and create a new Celery processing service.
129 | CeleryProcessingService.register()
130 | processing_service = CeleryProcessingService(celery=CeleryMock())
131 |
132 | # Submit the callback to the processing service with the provided arguments.
133 | processing_service.submit(callback, *args, **kwargs)
134 |
--------------------------------------------------------------------------------
/.github/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | We as members, contributors, and leaders pledge to make participation in our
6 | community a harassment-free experience for everyone, regardless of age, body
7 | size, visible or invisible disability, ethnicity, sex characteristics, gender
8 | identity and expression, level of experience, education, socio-economic status,
9 | nationality, personal appearance, race, caste, color, religion, or sexual
10 | identity and orientation.
11 |
12 | We pledge to act and interact in ways that contribute to an open, welcoming,
13 | diverse, inclusive, and healthy community.
14 |
15 | ## Our Standards
16 |
17 | Examples of behavior that contributes to a positive environment for our
18 | community include:
19 |
20 | * Demonstrating empathy and kindness toward other people
21 | * Being respectful of differing opinions, viewpoints, and experiences
22 | * Giving and gracefully accepting constructive feedback
23 | * Accepting responsibility and apologizing to those affected by our mistakes,
24 | and learning from the experience
25 | * Focusing on what is best not just for us as individuals, but for the overall
26 | community
27 |
28 | Examples of unacceptable behavior include:
29 |
30 | * The use of sexualized language or imagery, and sexual attention or advances of
31 | any kind
32 | * Trolling, insulting or derogatory comments, and personal or political attacks
33 | * Public or private harassment
34 | * Publishing others' private information, such as a physical or email address,
35 | without their explicit permission
36 | * Other conduct which could reasonably be considered inappropriate in a
37 | professional setting
38 |
39 | ## Enforcement Responsibilities
40 |
41 | Community leaders are responsible for clarifying and enforcing our standards of
42 | acceptable behavior and will take appropriate and fair corrective action in
43 | response to any behavior that they deem inappropriate, threatening, offensive,
44 | or harmful.
45 |
46 | Community leaders have the right and responsibility to remove, edit, or reject
47 | comments, commits, code, wiki edits, issues, and other contributions that are
48 | not aligned to this Code of Conduct, and will communicate reasons for moderation
49 | decisions when appropriate.
50 |
51 | ## Scope
52 |
53 | This Code of Conduct applies within all community spaces, and also applies when
54 | an individual is officially representing the community in public spaces.
55 | Examples of representing our community include using an official email address,
56 | posting via an official social media account, or acting as an appointed
57 | representative at an online or offline event.
58 |
59 | ## Enforcement
60 |
61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
62 | reported to the community leaders responsible for enforcement at
63 | dapensoft@gmail.com.
64 | All complaints will be reviewed and investigated promptly and fairly.
65 |
66 | All community leaders are obligated to respect the privacy and security of the
67 | reporter of any incident.
68 |
69 | ## Enforcement Guidelines
70 |
71 | Community leaders will follow these Community Impact Guidelines in determining
72 | the consequences for any action they deem in violation of this Code of Conduct:
73 |
74 | ### 1. Correction
75 |
76 | **Community Impact**: Use of inappropriate language or other behavior deemed
77 | unprofessional or unwelcome in the community.
78 |
79 | **Consequence**: A private, written warning from community leaders, providing
80 | clarity around the nature of the violation and an explanation of why the
81 | behavior was inappropriate. A public apology may be requested.
82 |
83 | ### 2. Warning
84 |
85 | **Community Impact**: A violation through a single incident or series of
86 | actions.
87 |
88 | **Consequence**: A warning with consequences for continued behavior. No
89 | interaction with the people involved, including unsolicited interaction with
90 | those enforcing the Code of Conduct, for a specified period of time. This
91 | includes avoiding interactions in community spaces as well as external channels
92 | like social media. Violating these terms may lead to a temporary or permanent
93 | ban.
94 |
95 | ### 3. Temporary Ban
96 |
97 | **Community Impact**: A serious violation of community standards, including
98 | sustained inappropriate behavior.
99 |
100 | **Consequence**: A temporary ban from any sort of interaction or public
101 | communication with the community for a specified period of time. No public or
102 | private interaction with the people involved, including unsolicited interaction
103 | with those enforcing the Code of Conduct, is allowed during this period.
104 | Violating these terms may lead to a permanent ban.
105 |
106 | ### 4. Permanent Ban
107 |
108 | **Community Impact**: Demonstrating a pattern of violation of community
109 | standards, including sustained inappropriate behavior, harassment of an
110 | individual, or aggression toward or disparagement of classes of individuals.
111 |
112 | **Consequence**: A permanent ban from any sort of public interaction within the
113 | community.
114 |
115 | ## Attribution
116 |
117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118 | version 2.1, available at
119 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120 |
121 | Community Impact Guidelines were inspired by
122 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123 |
124 | For answers to common questions about this code of conduct, see the FAQ at
125 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126 | [https://www.contributor-covenant.org/translations][translations].
127 |
128 | [homepage]: https://www.contributor-covenant.org
129 |
130 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
131 |
132 | [Mozilla CoC]: https://github.com/mozilla/diversity
133 |
134 | [FAQ]: https://www.contributor-covenant.org/faq
135 |
136 | [translations]: https://www.contributor-covenant.org/translations
137 |
--------------------------------------------------------------------------------
/tests/pyventus/core/processing/processing_service_test.py:
--------------------------------------------------------------------------------
1 | from abc import ABC, abstractmethod
2 | from typing import Any
3 |
4 | import pytest
5 |
6 | from ....fixtures import CallableMock
7 |
8 |
9 | class ProcessingServiceTest(ABC):
10 | """Abstract base class for testing processing services."""
11 |
12 | @abstractmethod
13 | def handle_submission_in_sync_context(
14 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
15 | ) -> None:
16 | """
17 | Abstract method to process a callback submission in a synchronous context.
18 |
19 | This method should be implemented by subclasses to instantiate the processing
20 | service, submit the provided callback with the specified arguments, and ensure
21 | that the callback execution is complete before returning.
22 |
23 | :param callback: The callback to be submitted for execution.
24 | :param args: Positional arguments to be passed to the callback.
25 | :param kwargs: Keyword arguments to be passed to the callback.
26 | :return: None.
27 | """
28 | pass
29 |
30 | @abstractmethod
31 | async def handle_submission_in_async_context(
32 | self, callback: CallableMock.Base, args: tuple[Any, ...], kwargs: dict[str, Any]
33 | ) -> None:
34 | """
35 | Abstract method to process a callback submission in an asynchronous context.
36 |
37 | This method should be implemented by subclasses to instantiate the processing
38 | service, submit the provided callback with the specified arguments, and ensure
39 | that the callback execution is complete before returning.
40 |
41 | :param callback: The callback to be submitted for execution.
42 | :param args: Positional arguments to be passed to the callback.
43 | :param kwargs: Keyword arguments to be passed to the callback.
44 | :return: None.
45 | """
46 | pass
47 |
48 | @pytest.mark.parametrize(
49 | ["callback_type", "args", "kwargs"],
50 | [
51 | (CallableMock.Sync, (), {}),
52 | (CallableMock.Sync, ("str", 0), {}),
53 | (CallableMock.Sync, (), {"str": ...}),
54 | (CallableMock.Sync, ("str", 0), {"str": ...}),
55 | (CallableMock.Async, (), {}),
56 | (CallableMock.Async, ("str", 0), {}),
57 | (CallableMock.Async, (), {"str": ...}),
58 | (CallableMock.Async, ("str", 0), {"str": ...}),
59 | ],
60 | )
61 | def test_submission_in_sync_context(
62 | self, callback_type: type[CallableMock.Base], args: tuple[Any, ...], kwargs: dict[str, Any]
63 | ) -> None:
64 | """
65 | Test the submission of a callback in a synchronous context.
66 |
67 | This test verifies that the provided callback is submitted correctly to the
68 | processing service and that it is executed with the expected arguments.
69 | It checks that the callback is called exactly once and that the arguments
70 | passed to the callback match the expected values.
71 |
72 | :param callback_type: The callback type to be instantiated and submitted for execution.
73 | :param args: Positional arguments to be passed to the callback.
74 | :param kwargs: Keyword arguments to be passed to the callback.
75 | :return: None.
76 | """
77 | # Arrange/Act: Instantiate the callback and submit it with the provided arguments in a sync context.
78 | callback: CallableMock.Base = callback_type()
79 | self.handle_submission_in_sync_context(callback=callback, args=args, kwargs=kwargs)
80 |
81 | # Assert: Verify that the callback was called exactly once with the specified arguments.
82 | assert callback.call_count == 1, f"Callback was not called exactly once ({callback.call_count} == 1)."
83 | assert callback.last_args == args, f"Expected args {args}, but got {callback.last_args}."
84 | assert callback.last_kwargs == kwargs, f"Expected kwargs {kwargs}, but got {callback.last_kwargs}."
85 |
86 | @pytest.mark.parametrize(
87 | ["callback_type", "args", "kwargs"],
88 | [
89 | (CallableMock.Sync, (), {}),
90 | (CallableMock.Sync, ("str", 0), {}),
91 | (CallableMock.Sync, (), {"str": ...}),
92 | (CallableMock.Sync, ("str", 0), {"str": ...}),
93 | (CallableMock.Async, (), {}),
94 | (CallableMock.Async, ("str", 0), {}),
95 | (CallableMock.Async, (), {"str": ...}),
96 | (CallableMock.Async, ("str", 0), {"str": ...}),
97 | ],
98 | )
99 | async def test_submission_in_async_context(
100 | self, callback_type: type[CallableMock.Base], args: tuple[Any, ...], kwargs: dict[str, Any]
101 | ) -> None:
102 | """
103 | Test the submission of a callback in an asynchronous context.
104 |
105 | This test verifies that the provided callback is submitted correctly to the
106 | processing service and that it is executed with the expected arguments when
107 | called from an asynchronous context. It checks that the callback is called
108 | exactly once and that the arguments passed to the callback match the
109 | expected values.
110 |
111 | :param callback_type: The callback type to be instantiated and submitted for execution.
112 | :param args: Positional arguments to be passed to the callback.
113 | :param kwargs: Keyword arguments to be passed to the callback.
114 | :return: None.
115 | """
116 | # Arrange/Act: Instantiate the callback and submit it with the provided arguments in an async context.
117 | callback: CallableMock.Base = callback_type()
118 | await self.handle_submission_in_async_context(callback=callback, args=args, kwargs=kwargs)
119 |
120 | # Assert: Verify that the callback was called exactly once with the specified arguments.
121 | assert callback.call_count == 1, f"Callback was not called exactly once ({callback.call_count} == 1)."
122 | assert callback.last_args == args, f"Expected args {args}, but got {callback.last_args}."
123 | assert callback.last_kwargs == kwargs, f"Expected kwargs {kwargs}, but got {callback.last_kwargs}."
124 |
--------------------------------------------------------------------------------
/src/pyventus/core/processing/celery/celery_processing_service.py:
--------------------------------------------------------------------------------
1 | from asyncio import run
2 | from dataclasses import dataclass
3 | from pickle import dumps, loads
4 | from typing import Any, Final, cast
5 |
6 | from typing_extensions import override
7 |
8 | from ...exceptions import PyventusException, PyventusImportException
9 | from ...loggers import StdOutLogger
10 | from ...utils import attributes_repr, formatted_repr, is_callable_async, summarized_repr
11 | from ..processing_service import ProcessingService, ProcessingServiceCallbackType
12 |
13 | try: # pragma: no cover
14 | from celery import Celery, shared_task
15 | except ImportError: # pragma: no cover
16 | raise PyventusImportException(import_name="celery", is_optional=True, is_dependency=True) from None
17 |
18 |
19 | class CeleryProcessingService(ProcessingService):
20 | """
21 | A processing service that utilizes the `Celery` framework to handle the execution of calls.
22 |
23 | **Notes:**
24 |
25 | - This service leverages the `Celery` framework to enqueue the provided callbacks into a distributed
26 | task system, which is monitored by multiple workers. Once enqueued, these callbacks are eligible
27 | for retrieval and processing by available workers, enabling a scalable and distributed approach
28 | to handling calls asynchronously.
29 |
30 | - Synchronous callbacks are executed in a blocking manner inside the worker, while asynchronous
31 | callbacks are processed within a new asyncio event loop using the `asyncio.run()` function.
32 | """
33 |
34 | CELERY_TASK_NAME: Final[str] = "pyventus_task"
35 | """The name of the task in Celery."""
36 |
37 | @dataclass(slots=True, frozen=True)
38 | class CeleryPayload:
39 | """A data class representing the payload of the `CeleryProcessingService`."""
40 |
41 | callback: ProcessingServiceCallbackType
42 | args: tuple[Any, ...]
43 | kwargs: dict[str, Any]
44 |
45 | @classmethod
46 | def register(cls) -> None:
47 | """
48 | Register the service's task globally in `Celery`.
49 |
50 | **Notes:**
51 |
52 | - This method should be invoked in the `Celery` worker script to ensure that the task is
53 | accessible to both the client and the worker. If this method is not called, a `KeyError`
54 | will be raised when attempting to submit a new callback.
55 |
56 | - This method uses the `shared_task` functionality from the `Celery` framework to register
57 | the service's task, making it available independently of the `Celery` instance used.
58 |
59 | - The registered task is a `Celery` task that will be used to process the execution
60 | of callbacks.
61 |
62 | :return: None.
63 | """
64 |
65 | def task(serialized_payload: bytes) -> None:
66 | """
67 | Celery task that processes the callbacks' execution with the given arguments.
68 |
69 | :param serialized_payload: The serialized data representing the callback and its arguments.
70 | :return: None.
71 | :raises PyventusException: If the serialized payload is invalid or cannot be deserialized.
72 | """
73 | # Validate that the serialized payload is provided.
74 | if not serialized_payload: # pragma: no cover
75 | raise PyventusException("The 'serialized_payload' argument is required but was not received.")
76 |
77 | # Deserialize the payload to retrieve the original callback and its arguments.
78 | payload = cast(CeleryProcessingService.CeleryPayload, loads(serialized_payload))
79 |
80 | # Validate the deserialized payload to ensure it is of the expected type.
81 | if payload is None or not isinstance(payload, CeleryProcessingService.CeleryPayload): # pragma: no cover
82 | raise PyventusException("Failed to deserialize the given payload.")
83 |
84 | # Check if the callback is asynchronous and execute accordingly.
85 | if is_callable_async(payload.callback):
86 | # Run the async callback in a new asyncio event loop.
87 | run(payload.callback(*payload.args, **payload.kwargs))
88 | else:
89 | # Run the sync callback directly with the provided arguments.
90 | payload.callback(*payload.args, **payload.kwargs)
91 |
92 | # Register the service's task as a shared task in Celery.
93 | shared_task(name=cls.CELERY_TASK_NAME)(task)
94 |
95 | # Attributes for the CeleryProcessingService
96 | __slots__ = ("__celery", "__queue")
97 |
98 | def __init__(self, celery: Celery, queue: str | None = None) -> None:
99 | """
100 | Initialize an instance of `CeleryProcessingService`.
101 |
102 | :param celery: The Celery object used to enqueue and process callbacks.
103 | :param queue: The name of the queue where callbacks will be enqueued. Defaults to
104 | None, which uses the `task_default_queue` from the Celery configuration.
105 | :raises PyventusException: If the Celery instance is invalid or if the
106 | queue name is set but empty.
107 | """
108 | # Validate the Celery instance.
109 | if celery is None or not isinstance(celery, Celery):
110 | raise PyventusException("The 'celery' argument must be an instance of the Celery class.")
111 |
112 | # Check if the Celery app configuration uses the 'auth' serializer.
113 | if celery.conf.task_serializer != "auth":
114 | StdOutLogger.warning(
115 | source=summarized_repr(self),
116 | action="Security Message:",
117 | msg=(
118 | "To enhance security in message communication, it is recommended to employ the Celery 'auth' "
119 | "serializer. While this service is serializer-agnostic, it relies on the pickling process to "
120 | "convert callbacks and their arguments into transmittable data, making security a critical "
121 | "consideration. Please refer to: https://docs.celeryq.dev/en/stable/userguide/security.html"
122 | ),
123 | )
124 |
125 | # Validate the queue name, if provided.
126 | if queue is not None and len(queue) == 0:
127 | raise PyventusException("The 'queue' argument cannot be empty.")
128 |
129 | # Assign the Celery instance and queue name.
130 | self.__celery: Celery = celery
131 | self.__queue: str = queue if queue else self.__celery.conf.task_default_queue
132 |
133 | def __repr__(self) -> str:
134 | """
135 | Retrieve a string representation of the instance.
136 |
137 | :return: A string representation of the instance.
138 | """
139 | return formatted_repr(
140 | instance=self,
141 | info=attributes_repr(
142 | celery=self.__celery,
143 | queue=self.__queue,
144 | ),
145 | )
146 |
147 | @override
148 | def submit(self, callback: ProcessingServiceCallbackType, *args: Any, **kwargs: Any) -> None:
149 | # Create the Celery payload to encapsulate the callback and its arguments.
150 | payload = CeleryProcessingService.CeleryPayload(callback=callback, args=args, kwargs=kwargs)
151 |
152 | # Serialize the payload object.
153 | serialized_payload: bytes = dumps(payload)
154 |
155 | # Send the serialized payload to Celery for asynchronous execution.
156 | self.__celery.send_task(
157 | name=self.__class__.CELERY_TASK_NAME,
158 | args=(serialized_payload,),
159 | queue=self.__queue,
160 | )
161 |
--------------------------------------------------------------------------------
/docs/learn/events/emitters/redis.md:
--------------------------------------------------------------------------------
1 |
9 |
10 | # Redis Event Emitter
11 |
12 | 13 | In Pyventus, you can easily integrate Event Emitters with the Redis Queue framework through the Redis Processing Service. Simply create an instance of the Redis Processing Service and pass it as the event processor when setting up the Event Emitter, or you can use the factory method called Redis Event Emitter to handle the setup in a single step. 14 |
15 | 16 | === ":material-console: Manual Configuration" 17 | 18 | ```Python linenums="1" hl_lines="1-4 6-7 10" 19 | from pyventus.core.processing.redis import RedisProcessingService 20 | from pyventus.events import EventEmitter 21 | from redis import Redis 22 | from rq import Queue 23 | 24 | redis_conn = Redis.from_url("redis://default:redispw@localhost:6379") 25 | default_queue: Queue = Queue(name="default", connection=redis_conn) 26 | 27 | if __name__ == "__main__": 28 | event_emitter: EventEmitter = EventEmitter(event_processor=RedisProcessingService(queue=default_queue)) 29 | event_emitter.emit("MyEvent") 30 | ``` 31 | 32 | === ":material-factory: Factory Method" 33 | 34 | ```Python linenums="1" hl_lines="1-3 5-6 9" 35 | from pyventus.events import EventEmitter, RedisEventEmitter 36 | from redis import Redis 37 | from rq import Queue 38 | 39 | redis_conn = Redis.from_url("redis://default:redispw@localhost:6379") 40 | default_queue: Queue = Queue(name="default", connection=redis_conn) 41 | 42 | if __name__ == "__main__": 43 | event_emitter: EventEmitter = RedisEventEmitter(queue=default_queue) 44 | event_emitter.emit("MyEvent") 45 | ``` 46 | 47 |48 | By utilizing the Redis Processing Service, the execution of each event emission will be handled by a Redis Queue worker. 49 |
50 | 51 | ## Practical Example 52 | 53 |54 | To start using the Event Emitter with Redis Queue, follow these steps: 55 |
56 | 57 | 1.Install Dependencies: 58 | Before proceeding, ensure that you have installed the optional [Redis Queue dependency](../../../getting-started.md/#optional-dependencies). 59 |
60 | 61 | 2.Define Subscribers: 62 | If you're using Python's built-in functions, you can skip this step. If you're working with your own functions, you'll need to let Redis Queue know where they are defined. However, to avoid circular dependencies between modules, it's important to place these functions in a separate module from both your worker module and the event emitter. 63 |
64 | 65 | ```Python title="subscribers.py" linenums="1" 66 | from pyventus.events import EventLinker 67 | 68 | 69 | @EventLinker.on("MyEvent") 70 | def handle_my_event() -> None: 71 | print("Handling 'MyEvent'!") 72 | ``` 73 | 74 | 3.Create a Worker: 75 | Now that you’ve defined your subscribers, the next step is to create the script for the Redis Queue worker. This worker will listen to the Redis Queue pub/sub channel and process each event emission. For more information about Redis Queue workers, you can refer to the official documentation: [RQ Workers](https://python-rq.org/docs/workers/). 76 |
77 | 78 | === ":material-apple: macOS / :material-linux: Linux" 79 | 80 | ```Python title="worker.py" linenums="1" hl_lines="1 3-4 6 8-9 12 21-24 26-27" 81 | from multiprocessing import Process 82 | 83 | from redis import Redis 84 | from rq import Queue, SimpleWorker 85 | 86 | from .subscribers import handle_my_event # (1)! 87 | 88 | redis_conn = Redis.from_url("redis://default:redispw@localhost:6379") 89 | default_queue: Queue = Queue(name="default", connection=redis_conn) 90 | 91 | 92 | def worker_process() -> None: # (2)! 93 | worker = SimpleWorker(connection=redis_conn, queues=[default_queue]) 94 | worker.work() 95 | 96 | 97 | if __name__ == "__main__": 98 | num_workers = 1 # (3)! 99 | worker_processes: list[Process] = [] 100 | 101 | for _ in range(num_workers): # (4)! 102 | p = Process(target=worker_process) 103 | worker_processes.append(p) 104 | p.start() 105 | 106 | for process in worker_processes: 107 | process.join() # (5)! 108 | ``` 109 | 110 | 1. Import the `subscribers.py` module to let Redis Queue know about the available functions. 111 | 2. Creates a new Worker instance and starts the work loop. 112 | 3. Set the number of workers. For auto-assignment use: `multiprocessing.cpu_count()`. 113 | 4. Creates and starts new Processes for each worker. 114 | 5. Join every worker process. 115 | 116 | === ":fontawesome-brands-windows: Windows" 117 | 118 | ```Python title="worker.py" linenums="1" hl_lines="1 3-5 7 9-10 13-15 25-28 30-31" 119 | from multiprocessing import Process 120 | 121 | from redis import Redis 122 | from rq import Queue, SimpleWorker 123 | from rq.timeouts import TimerDeathPenalty 124 | 125 | from .subscribers import handle_my_event # (1)! 126 | 127 | redis_conn = Redis.from_url("redis://default:redispw@localhost:6379") 128 | default_queue: Queue = Queue(name="default", connection=redis_conn) 129 | 130 | 131 | def worker_process() -> None: # (2)! 132 | class WindowsSimpleWorker(SimpleWorker): # (3)! 133 | death_penalty_class = TimerDeathPenalty 134 | 135 | worker = WindowsSimpleWorker(connection=redis_conn, queues=[default_queue]) 136 | worker.work() 137 | 138 | 139 | if __name__ == "__main__": 140 | num_workers = 1 # (4)! 141 | worker_processes: list[Process] = [] 142 | 143 | for _ in range(num_workers): # (5)! 144 | p = Process(target=worker_process) 145 | worker_processes.append(p) 146 | p.start() 147 | 148 | for process in worker_processes: 149 | process.join() # (6)! 150 | ``` 151 | 152 | 1. Import the `subscribers.py` module to let Redis Queue know about the available functions. 153 | 2. Creates a new Worker instance and starts the work loop. 154 | 3. A class that inherits from `SimpleWorker` and is used to create a new worker instance in a Windows based system. 155 | 4. Set the number of workers. For auto-assignment use: `multiprocessing.cpu_count()`. 156 | 5. Creates and starts new Processes for each worker. 157 | 6. Join every worker process. 158 | 159 |160 | With the previous configuration in place, you can now launch the Redis Queue worker. 161 |
162 | 163 |
164 | ```console
165 | py -m worker
166 | ```
167 |
168 |
169 | 4. Emitting events: 170 | Now that your workers are up and running, it’s time to start emitting events! Just create an Event Emitter configured with the Redis Processing Service, and you’re all set to emit an event. 171 |
172 | 173 | ```Python title="main.py" linenums="1" hl_lines="1 3 6" 174 | from pyventus.events import EventEmitter, RedisEventEmitter 175 | 176 | from .worker import default_queue 177 | 178 | if __name__ == "__main__": 179 | event_emitter: EventEmitter = RedisEventEmitter(queue=default_queue) 180 | event_emitter.emit("MyEvent") 181 | ``` 182 | -------------------------------------------------------------------------------- /tests/pyventus/reactive/subscribers/test_subscriber.py: -------------------------------------------------------------------------------- 1 | from pickle import dumps, loads 2 | from typing import Any 3 | 4 | import pytest 5 | from pyventus import PyventusException 6 | from pyventus.reactive import Subscriber 7 | 8 | from ....fixtures import CallableMock, DummyCallable 9 | from ....utils import has_private_attr 10 | 11 | 12 | class TestSubscriber: 13 | # ================================= 14 | # Test Cases for creation 15 | # ================================= 16 | 17 | @pytest.mark.parametrize( 18 | ["next_callback", "error_callback", "complete_callback"], 19 | [ 20 | (CallableMock.Sync(), None, None), 21 | (None, CallableMock.Async(), None), 22 | (None, None, CallableMock.Async()), 23 | (CallableMock.Async(), None, CallableMock.Sync()), 24 | (CallableMock.Async(), CallableMock.Sync(), None), 25 | (None, CallableMock.Sync(), CallableMock.Async()), 26 | ], 27 | ) 28 | def test_creation_with_valid_input( 29 | self, next_callback: CallableMock.Base, error_callback: CallableMock.Base, complete_callback: CallableMock.Base 30 | ) -> None: 31 | # Arrange/Act 32 | subscriber = Subscriber[Any]( 33 | teardown_callback=lambda sub: True, 34 | next_callback=next_callback, 35 | error_callback=error_callback, 36 | complete_callback=complete_callback, 37 | force_async=False, 38 | ) 39 | 40 | # Assert 41 | assert subscriber is not None 42 | assert isinstance(subscriber, Subscriber) 43 | assert subscriber.has_next_callback is bool(next_callback is not None) 44 | assert subscriber.has_error_callback is bool(error_callback is not None) 45 | assert subscriber.has_complete_callback is bool(complete_callback is not None) 46 | 47 | # ================================= 48 | 49 | @pytest.mark.parametrize( 50 | ["next_callback", "error_callback", "complete_callback", "exception"], 51 | [ 52 | (None, None, None, PyventusException), 53 | (DummyCallable.Sync.Generator.func, None, None, PyventusException), 54 | (None, DummyCallable.Async.Generator.func, None, PyventusException), 55 | (None, None, DummyCallable.Async.Generator.func, PyventusException), 56 | ], 57 | ) 58 | def test_creation_with_invalid_input( 59 | self, next_callback: Any, error_callback: Any, complete_callback: Any, exception: type[Exception] 60 | ) -> None: 61 | # Arrange/Act/Assert 62 | with pytest.raises(exception): 63 | Subscriber[Any]( 64 | teardown_callback=lambda sub: True, 65 | next_callback=next_callback, 66 | error_callback=error_callback, 67 | complete_callback=complete_callback, 68 | force_async=False, 69 | ) 70 | 71 | # ================================= 72 | # Test Cases for the Next method execution. 73 | # ================================= 74 | 75 | @pytest.mark.parametrize( 76 | ["next_callback"], 77 | [ 78 | (None,), 79 | (CallableMock.Sync(),), 80 | (CallableMock.Async(),), 81 | ], 82 | ) 83 | async def test_next_method_execution(self, next_callback: CallableMock.Base | None) -> None: 84 | # Arrange 85 | value: Any = object() 86 | error_callback: CallableMock.Base = CallableMock.Sync() 87 | complete_callback: CallableMock.Base = CallableMock.Async() 88 | subscriber = Subscriber[Any]( 89 | teardown_callback=lambda sub: True, 90 | next_callback=next_callback, 91 | error_callback=error_callback, 92 | complete_callback=complete_callback, 93 | force_async=False, 94 | ) 95 | 96 | # Act 97 | await subscriber.next(value) 98 | 99 | # Assert 100 | if next_callback: 101 | assert next_callback.call_count == 1 102 | assert next_callback.last_args == (value,) 103 | assert next_callback.last_kwargs == {} 104 | assert error_callback.call_count == 0 105 | assert complete_callback.call_count == 0 106 | 107 | # ================================= 108 | # Test Cases for the Error method execution. 109 | # ================================= 110 | 111 | @pytest.mark.parametrize( 112 | ["error_callback"], 113 | [ 114 | (None,), 115 | (CallableMock.Sync(),), 116 | (CallableMock.Async(),), 117 | ], 118 | ) 119 | async def test_error_method_execution(self, error_callback: CallableMock.Base | None) -> None: 120 | # Arrange 121 | exception: Exception = ValueError() 122 | next_callback: CallableMock.Base = CallableMock.Async() 123 | complete_callback: CallableMock.Base = CallableMock.Sync() 124 | subscriber = Subscriber[Any]( 125 | teardown_callback=lambda sub: True, 126 | next_callback=next_callback, 127 | error_callback=error_callback, 128 | complete_callback=complete_callback, 129 | force_async=False, 130 | ) 131 | 132 | # Act 133 | await subscriber.error(exception) 134 | 135 | # Assert 136 | if error_callback: 137 | assert error_callback.call_count == 1 138 | assert error_callback.last_args == (exception,) 139 | assert error_callback.last_kwargs == {} 140 | assert next_callback.call_count == 0 141 | assert complete_callback.call_count == 0 142 | 143 | # ================================= 144 | # Test Cases for the Complete method execution. 145 | # ================================= 146 | 147 | @pytest.mark.parametrize( 148 | ["complete_callback"], 149 | [ 150 | (None,), 151 | (CallableMock.Sync(),), 152 | (CallableMock.Async(),), 153 | ], 154 | ) 155 | async def test_complete_method_execution(self, complete_callback: CallableMock.Base | None) -> None: 156 | # Arrange 157 | next_callback: CallableMock.Base = CallableMock.Async() 158 | error_callback: CallableMock.Base = CallableMock.Sync() 159 | subscriber = Subscriber[Any]( 160 | teardown_callback=lambda sub: True, 161 | next_callback=next_callback, 162 | error_callback=error_callback, 163 | complete_callback=complete_callback, 164 | force_async=False, 165 | ) 166 | 167 | # Act 168 | await subscriber.complete() 169 | 170 | # Assert 171 | if complete_callback: 172 | assert complete_callback.call_count == 1 173 | assert complete_callback.last_args == () 174 | assert complete_callback.last_kwargs == {} 175 | assert next_callback.call_count == 0 176 | assert error_callback.call_count == 0 177 | 178 | # ================================= 179 | # Test Cases for Serialization/Deserialization 180 | # ================================= 181 | 182 | def test_pickle_serialization_and_deserialization(self) -> None: 183 | # Arrange 184 | subscriber = Subscriber( 185 | teardown_callback=CallableMock.Sync(return_value=False), 186 | next_callback=CallableMock.Sync(), 187 | error_callback=None, 188 | complete_callback=None, 189 | force_async=True, 190 | ) 191 | 192 | # Act 193 | data = dumps(subscriber) 194 | restored = loads(data) 195 | 196 | # Assert 197 | for attr in Subscriber.__slots__: 198 | assert ( 199 | hasattr(restored, attr) 200 | if not attr.startswith("__") or attr.endswith("__") 201 | else has_private_attr(restored, attr) 202 | ) 203 | -------------------------------------------------------------------------------- /docs/learn/events/emitters/index.md: -------------------------------------------------------------------------------- 1 | # Event Emitters 2 | 3 |4 | Now that your events and responses are all linked up, you may need a way to dispatch these events throughout your application and trigger their corresponding responses. For this purpose, Pyventus provides you with what is known as an Event Emitter. 5 |
6 | 7 |8 | The Event Emitter in Pyventus is essentially a base class that allows you to orchestrate the emission of events within your application in a modular and decoupled manner. 9 |
10 | 11 | ## Getting Started 12 | 13 |14 | In order to start working with the Event Emitter, the first thing you will need to do is to create a new instance of it. To do so, you will need what is known as an event processor, which is an instance of the Processing Service interface. This processor is crucial for the Event Emitter, as it is responsible for processing the emission of events. 15 |
16 | 17 | === ":material-console: Manual Creation" 18 | 19 | ```Python linenums="1" hl_lines="1 2 4" 20 | from pyventus.events import EventEmitter 21 | from pyventus.core.processing.asyncio import AsyncIOProcessingService # (1)! 22 | 23 | event_emitter = EventEmitter(event_processor=AsyncIOProcessingService()) 24 | event_emitter.emit("MyEvent") 25 | ``` 26 | 27 | 1. You can import and use any of the supported processing services, or even create your own custom ones. 28 | 29 | === ":material-factory: Factory Method" 30 | 31 | ```Python linenums="1" hl_lines="1 4" 32 | from pyventus.events import AsyncIOEventEmitter, EventEmitter 33 | 34 | 35 | event_emitter: EventEmitter = AsyncIOEventEmitter() # (1)! 36 | event_emitter.emit("MyEvent") 37 | ``` 38 | 39 | 1. There is a factory method for each of the supported processing services. For reference, you can check the [Event Emitter utilities](../../../api/events/emitters/event_emitter_utils.md). 40 | 41 | ### Using Custom Event Linkers 42 | 43 |44 | By default, the Event Emitter comes with the base Event Linker class configured as the primary access point for events and their responses. However, you have the flexibility to specify the Event Linker class that the Event Emitter will use. 45 |
46 | 47 | === ":material-console: Manual Creation" 48 | 49 | ```Python linenums="1" hl_lines="5 7 11" 50 | from pyventus.events import EventEmitter, EventLinker 51 | from pyventus.core.processing.asyncio import AsyncIOProcessingService 52 | 53 | 54 | class CustomEventLinker(EventLinker): ... 55 | 56 | CustomEventLinker.subscribe("MyEvent", event_callback=print) 57 | EventLinker.subscribe("MyEvent", event_callback=print) # (1)! 58 | 59 | event_emitter = EventEmitter( 60 | event_linker=CustomEventLinker, 61 | event_processor=AsyncIOProcessingService(), 62 | ) 63 | event_emitter.emit("MyEvent", "Hello, World!") 64 | ``` 65 | 66 | 1. This event subscriber will not be triggered, as it is subscribed to the Event Linker base class rather than the custom one that was created. 67 | 68 | === ":material-factory: Factory Method" 69 | 70 | ```Python linenums="1" hl_lines="4 7 12" 71 | from pyventus.events import AsyncIOEventEmitter, EventEmitter, EventLinker 72 | 73 | 74 | class CustomEventLinker(EventLinker): ... 75 | 76 | 77 | CustomEventLinker.subscribe("MyEvent", event_callback=print) 78 | EventLinker.subscribe("MyEvent", event_callback=print) # (1)! 79 | 80 | 81 | event_emitter: EventEmitter = AsyncIOEventEmitter( 82 | event_linker=CustomEventLinker, 83 | ) 84 | event_emitter.emit("MyEvent", "Hello, World!") 85 | ``` 86 | 87 | 1. This event subscriber will not be triggered, as it is subscribed to the Event Linker base class rather than the custom one that was created. 88 | 89 | ### Using Custom Event Processors 90 | 91 |92 | If you need a different strategy for processing event emissions, you can easily do so by providing an instance of a subclass of the Processing Service interface to the Event Emitter. 93 |
94 | 95 | ```Python linenums="1" hl_lines="3 7 8 14" 96 | import asyncio 97 | 98 | from pyventus.core.processing import ProcessingService 99 | from pyventus.events import EventEmitter, EventLinker 100 | 101 | 102 | class CustomProcessingService(ProcessingService): 103 | def submit(self, callback, *args, **kwargs): # (1)! 104 | coro = callback(*args, **kwargs) # (2)! 105 | if asyncio.iscoroutine(coro): 106 | asyncio.run(coro) 107 | 108 | 109 | event_emitter = EventEmitter(event_processor=CustomProcessingService()) 110 | 111 | EventLinker.subscribe("MyEvent", event_callback=print) 112 | event_emitter.emit("MyEvent", "Hello, World!") 113 | ``` 114 | 115 | 1. Implement this method to define the processing strategy. See the example below. 116 | 2. The given `callback` can be either a synchronous or an asynchronous Python function. For typing, you can refer to the base [submit()](../../../api/core/processing/#pyventus.core.processing.ProcessingService.submit) method. 117 | 118 | ## Runtime Flexibility 119 | 120 |121 | Thanks to the separation of concerns between the Event Linker and the Event Emitter, you can easily change the Event Emitter at runtime without needing to reconfigure all connections or implement complex logic. 122 |
123 | 124 | ```Python linenums="1" hl_lines="6 14 15" 125 | from concurrent.futures import ThreadPoolExecutor 126 | 127 | from pyventus.events import AsyncIOEventEmitter, EventEmitter, EventLinker, ExecutorEventEmitter 128 | 129 | 130 | def main(event_emitter: EventEmitter) -> None: 131 | event_emitter.emit("MyEvent", f"Using: {event_emitter}!") 132 | 133 | 134 | if __name__ == "__main__": 135 | executor = ThreadPoolExecutor() 136 | EventLinker.subscribe("MyEvent", event_callback=print) 137 | 138 | main(event_emitter=AsyncIOEventEmitter()) 139 | main(event_emitter=ExecutorEventEmitter(executor)) 140 | 141 | executor.shutdown() 142 | ``` 143 | 144 | ## Debug Mode 145 | 146 |147 | Pyventus' Event Emitter offers a useful debug mode feature to help you understand the flow of events and troubleshoot your event-driven application. You can enable debug mode in the Event Emitter using the following options: 148 |
149 | 150 | ### Global Debug Mode 151 | 152 |153 | By default, Pyventus leverages Python's global debug tracing feature to determine whether the code is running in debug mode or not. When this mode is enabled, all local debug flags are set to `True` unless they are already configured. To activate global debug mode, simply run your code in a debugger like [pdb](https://docs.python.org/3/library/pdb.html). 154 |
155 | 156 |
157 | 
158 |
163 | Alternatively, if you want to enable or disable debug mode for a specific Event Emitter instance, you can use the `debug` flag. Setting the `debug` flag to `True` enables debug mode for that instance, while setting it to `False` disables debug mode. 164 |
165 | 166 | === "Debug Mode `On`" 167 | 168 | ```Python linenums="1" hl_lines="3" 169 | from pyventus.events import AsyncIOEventEmitter, EventEmitter 170 | 171 | event_emitter: EventEmitter = AsyncIOEventEmitter(debug=True) 172 | event_emitter.emit("MyEvent", "Hello, World!") 173 | ``` 174 | 175 | === "Debug Mode `Off`" 176 | 177 | ```Python linenums="1" hl_lines="3" 178 | from pyventus.events import AsyncIOEventEmitter, EventEmitter 179 | 180 | event_emitter: EventEmitter = AsyncIOEventEmitter(debug=False) 181 | event_emitter.emit("MyEvent", "Hello, World!") 182 | ``` 183 | -------------------------------------------------------------------------------- /src/pyventus/events/subscribers/event_subscriber.py: -------------------------------------------------------------------------------- 1 | from collections.abc import Awaitable, Callable 2 | from typing import Any, TypeAlias, final 3 | 4 | from typing_extensions import Self, override 5 | 6 | from ...core.exceptions import PyventusException 7 | from ...core.subscriptions import Subscription 8 | from ...core.utils import CallableWrapper, attributes_repr, formatted_repr 9 | from ...events.handlers import EventHandler 10 | 11 | EventCallbackType: TypeAlias = Callable[..., Any] 12 | """Type alias for the event callback invoked when the event occurs.""" 13 | 14 | SuccessCallbackType: TypeAlias = Callable[..., Awaitable[None] | None] 15 | """Type alias for the callback invoked when the event response completes successfully.""" 16 | 17 | FailureCallbackType: TypeAlias = Callable[[Exception], Awaitable[None] | None] 18 | """Type alias for the callback invoked when the event response fails.""" 19 | 20 | 21 | @final 22 | class EventSubscriber(EventHandler, Subscription): 23 | """ 24 | A class that represents an `EventHandler` subscribed to an `EventLinker`. 25 | 26 | **Notes:** 27 | 28 | - This class combines the `EventHandler` interface with the `Subscription` 29 | base class, providing a convenient way to handle events and manage the 30 | subscription lifecycle. 31 | 32 | - This class is not intended to be subclassed or instantiated directly. 33 | """ 34 | 35 | # Attributes for the EventSubscriber 36 | __slots__ = ("__event_callback", "__success_callback", "__failure_callback", "__once") 37 | 38 | def __init__( 39 | self, 40 | teardown_callback: Callable[[Self], bool], 41 | event_callback: EventCallbackType, 42 | success_callback: SuccessCallbackType | None, 43 | failure_callback: FailureCallbackType | None, 44 | force_async: bool, 45 | once: bool, 46 | ) -> None: 47 | """ 48 | Initialize an instance of `EventSubscriber`. 49 | 50 | :param teardown_callback: A callback function invoked during the unsubscription process to perform 51 | cleanup or teardown operations associated with the subscription. It should return `True` if the 52 | cleanup was successful, or `False` if the teardown has already been executed and the subscription 53 | is no longer active. 54 | :param event_callback: The callback to be executed when the event occurs. 55 | :param success_callback: The callback to be executed when the event response completes successfully. 56 | :param failure_callback: The callback to be executed when the event response fails. 57 | :param force_async: Determines whether to force all callbacks to run asynchronously. 58 | If `True`, synchronous callbacks will be converted to run asynchronously in a 59 | thread pool, using the `asyncio.to_thread` function. If `False`, callbacks 60 | will run synchronously or asynchronously as defined. 61 | :param once: Specifies if the event subscriber is a one-time subscription. 62 | """ 63 | # Initialize the base Subscription class with the teardown callback 64 | super().__init__(teardown_callback=teardown_callback) 65 | 66 | # Ensure the 'once' parameter is a boolean 67 | if not isinstance(once, bool): 68 | raise PyventusException("The 'once' argument must be a boolean value.") 69 | 70 | # Wrap and set the event callback 71 | self.__event_callback = CallableWrapper[..., Any](event_callback, force_async=force_async) 72 | 73 | # Ensure that the event callback is not a generator. 74 | if self.__event_callback.is_generator: 75 | raise PyventusException("The 'event_callback' cannot be a generator.") 76 | 77 | # Wrap and set the success callback, if provided. 78 | self.__success_callback = ( 79 | CallableWrapper[..., None]( 80 | success_callback, 81 | force_async=force_async, 82 | ) 83 | if success_callback 84 | else None 85 | ) 86 | 87 | # Ensure that the success callback is not a generator. 88 | if self.__success_callback and self.__success_callback.is_generator: 89 | raise PyventusException("The 'success_callback' cannot be a generator.") 90 | 91 | # Wrap and set the failure callback, if provided. 92 | self.__failure_callback = ( 93 | CallableWrapper[[Exception], None]( 94 | failure_callback, 95 | force_async=force_async, 96 | ) 97 | if failure_callback 98 | else None 99 | ) 100 | 101 | # Ensure that the failure callback is not a generator. 102 | if self.__failure_callback and self.__failure_callback.is_generator: 103 | raise PyventusException("The 'failure_callback' cannot be a generator.") 104 | 105 | # Store the one-time subscription flag. 106 | self.__once: bool = once 107 | 108 | @override 109 | def __repr__(self) -> str: 110 | return formatted_repr( 111 | instance=self, 112 | info=( 113 | attributes_repr( 114 | event_callback=self.__event_callback, 115 | success_callback=self.__success_callback, 116 | failure_callback=self.__failure_callback, 117 | once=self.__once, 118 | ) 119 | + f", {super().__repr__()}" 120 | ), 121 | ) 122 | 123 | @property 124 | def once(self) -> bool: 125 | """ 126 | Determine if the event subscriber is a one-time subscription. 127 | 128 | :return: A boolean value indicating if the event subscriber 129 | is a one-time subscription. 130 | """ 131 | return self.__once 132 | 133 | @override 134 | async def _handle_event(self, *args: Any, **kwargs: Any) -> Any: 135 | # Execute the event callback with the provided arguments and return the result 136 | return await self.__event_callback.execute(*args, **kwargs) 137 | 138 | @override 139 | async def _handle_success(self, results: Any) -> None: 140 | if self.__success_callback is None: 141 | # If no success callback is set, exit early 142 | return 143 | elif results is None: 144 | # If results are None, invoke the success callback without parameters 145 | await self.__success_callback.execute() 146 | else: 147 | # Invoke the success callback with the given results 148 | await self.__success_callback.execute(results) 149 | 150 | @override 151 | async def _handle_failure(self, exception: Exception) -> None: 152 | if self.__failure_callback is None: 153 | # If no failure callback is set, exit early 154 | return 155 | else: 156 | # Invoke the failure callback with the provided exception 157 | await self.__failure_callback.execute(exception) 158 | 159 | @override 160 | def __getstate__(self) -> dict[str, Any]: 161 | # Retrieve the state of the base Subscription class 162 | state: dict[str, Any] = super().__getstate__() 163 | 164 | # Add the state of the EventSubscriber attributes 165 | state["__event_callback"] = self.__event_callback 166 | state["__success_callback"] = self.__success_callback 167 | state["__failure_callback"] = self.__failure_callback 168 | state["__once"] = self.__once 169 | 170 | # Return the complete state for serialization 171 | return state 172 | 173 | @override 174 | def __setstate__(self, state: dict[str, Any]) -> None: 175 | # Restore the state of the base Subscription class 176 | super().__setstate__(state) 177 | 178 | # Restore the state of the EventSubscriber attributes 179 | self.__event_callback = state["__event_callback"] 180 | self.__success_callback = state["__success_callback"] 181 | self.__failure_callback = state["__failure_callback"] 182 | self.__once = state["__once"] 183 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Project information 2 | site_name: Pyventus 3 | site_url: https://mdapena.github.io/pyventus/ 4 | site_author: Manuel Da Pena 5 | site_description: >- 6 | A powerful Python library for event-driven and reactive programming. 7 | 8 | # Repository 9 | repo_name: mdapena/pyventus 10 | repo_url: https://github.com/mdapena/pyventus 11 | 12 | # Copyright 13 | copyright: | 14 | Copyright © 2023-2025 Manuel Da Pena 15 | 16 | # Configuration 17 | theme: 18 | name: material 19 | language: en 20 | custom_dir: docs/.overrides 21 | logo: images/logo/pyventus-logo-white.png 22 | favicon: images/favicon/pyventus-logo.ico 23 | palette: 24 | # Palette toggle for automatic mode 25 | - media: "(prefers-color-scheme)" 26 | toggle: 27 | icon: material/weather-sunny 28 | name: Switch to light mode 29 | # Palette toggle for light mode 30 | - media: '(prefers-color-scheme: light)' 31 | scheme: default 32 | primary: cyan 33 | accent: amber 34 | toggle: 35 | icon: material/weather-night 36 | name: Switch to dark mode 37 | # Palette toggle for dark mode 38 | - media: '(prefers-color-scheme: dark)' 39 | scheme: slate 40 | primary: cyan 41 | accent: amber 42 | toggle: 43 | icon: material/brightness-auto 44 | name: Switch to system preference 45 | features: 46 | - navigation.instant 47 | - navigation.instant.progress 48 | - navigation.tracking 49 | - navigation.tabs 50 | - navigation.indexes 51 | - navigation.top 52 | - navigation.sections 53 | - navigation.footer 54 | - toc.follow 55 | - search.suggest 56 | - search.highlight 57 | - content.tabs.link 58 | - content.code.annotation 59 | - content.code.copy 60 | - content.tooltips 61 | - content.code.annotate 62 | - announce.dismiss 63 | 64 | # Customization 65 | extra: 66 | version: 67 | provider: mike 68 | default: 69 | - latest 70 | - dev 71 | social: 72 | - icon: fontawesome/brands/linkedin 73 | link: https://linkedin.com/in/manuel-da-pena 74 | - icon: fontawesome/brands/github 75 | link: https://github.com/mdapena 76 | analytics: 77 | provider: google 78 | property: !ENV GOOGLE_ANALYTICS_KEY 79 | feedback: 80 | title: Was this page helpful? 81 | ratings: 82 | - icon: material/thumb-up-outline 83 | name: This page was helpful 84 | data: 1 85 | note: >- 86 | Thanks for your feedback! 87 | - icon: material/thumb-down-outline 88 | name: This page could be improved 89 | data: 0 90 | note: >- 91 | Thanks for your feedback! 92 | 93 | # Plugins 94 | plugins: 95 | - search 96 | - git-committers: 97 | enabled: !ENV [ CI, false ] 98 | repository: mdapena/pyventus 99 | branch: master 100 | exclude: 101 | - api/* 102 | - learn/index.md 103 | - index.md 104 | - git-revision-date-localized: 105 | type: timeago 106 | enable_creation_date: true 107 | exclude: 108 | - api/* 109 | - learn/index.md 110 | - index.md 111 | - mkdocstrings: 112 | handlers: 113 | python: 114 | options: 115 | docstring_style: sphinx 116 | show_if_no_docstring: true 117 | inherited_members: true 118 | members_order: source 119 | separate_signature: true 120 | unwrap_annotated: true 121 | filters: ["!^(_.*$)", "^(__init__|__init_subclass__|__call__|__enter__|__exit__)$"] 122 | docstring_section_style: spacy 123 | signature_crossrefs: true 124 | show_symbol_type_heading: true 125 | show_symbol_type_toc: true 126 | show_signature_annotations: true 127 | show_category_heading: true 128 | - mike: 129 | alias_type: symlink 130 | canonical_version: latest 131 | - social: 132 | enabled: !ENV [ CI, false ] 133 | 134 | # Extensions 135 | markdown_extensions: 136 | - attr_list 137 | - md_in_html 138 | - pymdownx.arithmatex: 139 | generic: true 140 | - pymdownx.highlight: 141 | anchor_linenums: true 142 | - pymdownx.tasklist: 143 | custom_checkbox: true 144 | clickable_checkbox: true 145 | - pymdownx.inlinehilite 146 | - pymdownx.snippets: 147 | base_path: 148 | - !relative $docs_dir 149 | - admonition 150 | - footnotes 151 | - pymdownx.details 152 | - pymdownx.superfences 153 | - pymdownx.mark 154 | - abbr 155 | - pymdownx.emoji: 156 | emoji_index: !!python/name:material.extensions.emoji.twemoji 157 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 158 | - pymdownx.tabbed: 159 | alternate_style: true 160 | - toc: 161 | permalink: true 162 | 163 | # Extra Stylesheets 164 | extra_css: 165 | - stylesheets/announcement.css 166 | - stylesheets/search-bar.css 167 | 168 | # Extra JavaScript for MathJax 169 | extra_javascript: 170 | - javascripts/mathjax.js 171 | - javascripts/announcement.js 172 | - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js 173 | 174 | # Page tree 175 | nav: 176 | - Pyventus: index.md 177 | - Getting Started: getting-started.md 178 | - Learn: 179 | - learn/index.md 180 | - Upgrade Guide: learn/upgrade_guide.md 181 | - Events: 182 | - learn/events/index.md 183 | - Event Types: learn/events/types.md 184 | - Event Linkers: learn/events/linkers.md 185 | - Event Emitters: 186 | - learn/events/emitters/index.md 187 | - AsyncIO Event Emitter: learn/events/emitters/asyncio.md 188 | - Celery Event Emitter: learn/events/emitters/celery.md 189 | - Executor Event Emitter: learn/events/emitters/executor.md 190 | - FastAPI Event Emitter: learn/events/emitters/fastapi.md 191 | - Redis Event Emitter: learn/events/emitters/redis.md 192 | - Reactive: 193 | - learn/reactive/index.md 194 | - API Reference: 195 | - api/index.md 196 | - Core: 197 | - api/core/index.md 198 | - Collections: 199 | - MultiBidict: api/core/collections/multi_bidict.md 200 | - Exceptions: 201 | - PyventusException: api/core/exceptions/pyventus_exception.md 202 | - PyventusImportException: api/core/exceptions/pyventus_import_exception.md 203 | - Processing: 204 | - api/core/processing/index.md 205 | - AsyncIOProcessingService: api/core/processing/asyncio_processing_service.md 206 | - CeleryProcessingService: api/core/processing/celery_processing_service.md 207 | - ExecutorProcessingService: api/core/processing/executor_processing_service.md 208 | - FastAPIProcessingService: api/core/processing/fastapi_processing_service.md 209 | - RedisProcessingService: api/core/processing/redis_processing_service.md 210 | - Subscriptions: 211 | - SubscriptionContext: api/core/subscriptions/subscription_context.md 212 | - Subscription: api/core/subscriptions/subscription.md 213 | - Unsubscribable: api/core/subscriptions/unsubscribable.md 214 | - Events: 215 | - api/events/index.md 216 | - EventEmitter: 217 | - api/events/emitters/index.md 218 | - EventEmitter Utils: api/events/emitters/event_emitter_utils.md 219 | - EventHandler: api/events/handlers/event_handler.md 220 | - EventLinker: api/events/linkers/event_linker.md 221 | - EventSubscriber: api/events/subscribers/event_subscriber.md 222 | - Reactive: 223 | - api/reactive/index.md 224 | - Observable: 225 | - api/reactive/observables/index.md 226 | - ObservableTask: api/reactive/observables/observable_task.md 227 | - Observable Utils: api/reactive/observables/observable_utils.md 228 | - Observer: api/reactive/observers/observer.md 229 | - Subscriber: api/reactive/subscribers/subscriber.md 230 | - Contributing: contributing.md 231 | - Release Notes: release-notes.md 232 | -------------------------------------------------------------------------------- /src/pyventus/events/emitters/event_emitter_utils.py: -------------------------------------------------------------------------------- 1 | from collections.abc import Callable, Generator 2 | from concurrent.futures import Executor, ThreadPoolExecutor 3 | from contextlib import contextmanager 4 | from typing import Any 5 | 6 | from ..linkers import EventLinker 7 | from .event_emitter import EventEmitter 8 | 9 | 10 | def AsyncIOEventEmitter( # noqa: N802 11 | event_linker: type[EventLinker] = EventLinker, 12 | debug: bool | None = None, 13 | ) -> EventEmitter: 14 | """ 15 | Create an `EventEmitter` instance configured with the `AsyncIOProcessingService`. 16 | 17 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 18 | corresponding subscribers. Defaults to `EventLinker`. 19 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 20 | execution environment. 21 | :return: An instance of `EventEmitter` configured with the `AsyncIOProcessingService`. 22 | """ 23 | from ...core.processing.asyncio import AsyncIOProcessingService 24 | 25 | processing_service = AsyncIOProcessingService() 26 | 27 | return EventEmitter( 28 | event_processor=processing_service, 29 | event_linker=event_linker, 30 | debug=debug, 31 | ) 32 | 33 | 34 | def CeleryEventEmitter( # noqa: N802 35 | celery: Any, 36 | queue: str | None = None, 37 | event_linker: type[EventLinker] = EventLinker, 38 | debug: bool | None = None, 39 | ) -> EventEmitter: 40 | """ 41 | Create an `EventEmitter` instance configured with the `CeleryProcessingService`. 42 | 43 | :param celery: The Celery object used to enqueue and process event emissions. 44 | :param queue: The name of the queue where the event emission will be enqueued. 45 | Defaults to None, which uses the task_default_queue from the Celery configuration. 46 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 47 | corresponding subscribers. Defaults to `EventLinker`. 48 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 49 | execution environment. 50 | :return: An instance of `EventEmitter` configured with the `CeleryProcessingService`. 51 | """ 52 | from ...core.processing.celery import CeleryProcessingService 53 | 54 | processing_service = CeleryProcessingService(celery=celery, queue=queue) 55 | 56 | return EventEmitter( 57 | event_processor=processing_service, 58 | event_linker=event_linker, 59 | debug=debug, 60 | ) 61 | 62 | 63 | def ExecutorEventEmitter( # noqa: N802 64 | executor: Executor, 65 | event_linker: type[EventLinker] = EventLinker, 66 | debug: bool | None = None, 67 | ) -> EventEmitter: 68 | """ 69 | Create an `EventEmitter` instance configured with the `ExecutorProcessingService`. 70 | 71 | :param executor: The executor object used to handle the execution of event emissions. 72 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 73 | corresponding subscribers. Defaults to `EventLinker`. 74 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 75 | execution environment. 76 | :return: An instance of `EventEmitter` configured with the `ExecutorProcessingService`. 77 | """ 78 | from ...core.processing.executor import ExecutorProcessingService 79 | 80 | processing_service = ExecutorProcessingService(executor=executor) 81 | 82 | return EventEmitter( 83 | event_processor=processing_service, 84 | event_linker=event_linker, 85 | debug=debug, 86 | ) 87 | 88 | 89 | @contextmanager 90 | def ExecutorEventEmitterCtx( # noqa: N802 91 | executor: Executor | None = None, 92 | event_linker: type[EventLinker] = EventLinker, 93 | debug: bool | None = None, 94 | ) -> Generator[EventEmitter, None, None]: 95 | """ 96 | Context manager that creates an `EventEmitter` instance configured with the `ExecutorProcessingService`. 97 | 98 | This context manager yields an `EventEmitter` instance, which can be used within a `with` statement. 99 | Upon exiting the context, the processing service is properly shut down. 100 | 101 | :param executor: The executor object used to handle the execution of event emissions. If `None`, 102 | a `ThreadPoolExecutor` with default settings will be created. 103 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 104 | corresponding subscribers. Defaults to `EventLinker`. 105 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 106 | execution environment. 107 | :return: An instance of `EventEmitter` configured with the `ExecutorProcessingService`. 108 | """ 109 | from ...core.processing.executor import ExecutorProcessingService 110 | 111 | processing_service = ExecutorProcessingService(executor=(executor if executor else ThreadPoolExecutor())) 112 | 113 | yield EventEmitter( 114 | event_processor=processing_service, 115 | event_linker=event_linker, 116 | debug=debug, 117 | ) 118 | 119 | processing_service.shutdown() 120 | 121 | 122 | def FastAPIEventEmitter( # noqa: N802 123 | event_linker: type[EventLinker] = EventLinker, 124 | debug: bool | None = None, 125 | ) -> Callable[[Any], EventEmitter]: 126 | """ 127 | Create an `EventEmitter` instance configured with the `FastAPIProcessingService`. 128 | 129 | This function is compatible with FastAPI's dependency injection system and should be 130 | used with the `Depends` method to automatically provide the `BackgroundTasks` instance. 131 | 132 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 133 | corresponding subscribers. Defaults to `EventLinker`. 134 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 135 | execution environment. 136 | :return: An instance of `EventEmitter` configured with the `FastAPIProcessingService`. 137 | """ 138 | from fastapi import BackgroundTasks 139 | 140 | from ...core.processing.fastapi import FastAPIProcessingService 141 | 142 | def create_event_emitter(background_tasks: BackgroundTasks) -> EventEmitter: 143 | """ 144 | Create and return an `EventEmitter` instance using the provided `BackgroundTasks`. 145 | 146 | :param background_tasks: The FastAPI `BackgroundTasks` object used to handle the execution of event emissions. 147 | :return: An instance of `EventEmitter` configured with the `FastAPIProcessingService`. 148 | """ 149 | processing_service = FastAPIProcessingService(background_tasks=background_tasks) 150 | 151 | return EventEmitter( 152 | event_processor=processing_service, 153 | event_linker=event_linker, 154 | debug=debug, 155 | ) 156 | 157 | return create_event_emitter 158 | 159 | 160 | def RedisEventEmitter( # noqa: N802 161 | queue: Any, 162 | options: dict[str, Any] | None = None, 163 | event_linker: type[EventLinker] = EventLinker, 164 | debug: bool | None = None, 165 | ) -> EventEmitter: 166 | """ 167 | Create an `EventEmitter` instance configured with the `RedisProcessingService`. 168 | 169 | :param queue: The Redis queue object used to enqueue and process event emissions. 170 | :param options: Additional options for the RQ package enqueueing method. Defaults to None (an empty dictionary). 171 | :param event_linker: Specifies the type of event linker used to manage and access events along with their 172 | corresponding subscribers. Defaults to `EventLinker`. 173 | :param debug: Specifies the debug mode for the logger. If `None`, it is determined based on the 174 | execution environment. 175 | :return: An instance of `EventEmitter` configured with the `RedisProcessingService`. 176 | """ 177 | from ...core.processing.redis import RedisProcessingService 178 | 179 | processing_service = RedisProcessingService(queue=queue, options=options) 180 | 181 | return EventEmitter( 182 | event_processor=processing_service, 183 | event_linker=event_linker, 184 | debug=debug, 185 | ) 186 | -------------------------------------------------------------------------------- /tests/pyventus/events/emitters/test_event_emitter_utils.py: -------------------------------------------------------------------------------- 1 | from pyventus.events import ( 2 | AsyncIOEventEmitter, 3 | CeleryEventEmitter, 4 | EventEmitter, 5 | EventLinker, 6 | ExecutorEventEmitter, 7 | ExecutorEventEmitterCtx, 8 | FastAPIEventEmitter, 9 | ) 10 | 11 | from ....utils import get_private_attr 12 | 13 | 14 | class TestEventEmitterUtils: 15 | # ================================= 16 | # Test Cases for AsyncIOEventEmitter 17 | # ================================= 18 | 19 | def test_AsyncIOEventEmitter(self) -> None: # noqa: N802 20 | from pyventus.core.processing.asyncio import AsyncIOProcessingService 21 | 22 | # Arrange 23 | class IsolatedEventLinker(EventLinker): ... 24 | 25 | # Act 26 | event_emitter = AsyncIOEventEmitter(event_linker=IsolatedEventLinker, debug=True) 27 | event_processor = get_private_attr(event_emitter, "__event_processor") 28 | event_linker = get_private_attr(event_emitter, "__event_linker") 29 | logger = get_private_attr(event_emitter, "__logger") 30 | 31 | # Assert creation and properties 32 | assert event_emitter is not None 33 | assert isinstance(event_emitter, EventEmitter) 34 | assert isinstance(event_processor, AsyncIOProcessingService) 35 | assert event_linker is IsolatedEventLinker 36 | assert logger.debug_enabled is True 37 | 38 | # ================================= 39 | # Test Cases for CeleryEventEmitter 40 | # ================================= 41 | 42 | def test_CeleryEventEmitter(self) -> None: # noqa: N802 43 | from celery import Celery 44 | from pyventus.core.processing.celery import CeleryProcessingService 45 | 46 | # Arrange 47 | class IsolatedEventLinker(EventLinker): ... 48 | 49 | celery = Celery() 50 | queue = "Queue" 51 | 52 | # Act 53 | event_emitter = CeleryEventEmitter(celery=celery, queue=queue, event_linker=IsolatedEventLinker, debug=True) 54 | event_processor = get_private_attr(event_emitter, "__event_processor") 55 | event_linker = get_private_attr(event_emitter, "__event_linker") 56 | logger = get_private_attr(event_emitter, "__logger") 57 | 58 | # Assert creation and properties 59 | assert event_emitter is not None 60 | assert isinstance(event_emitter, EventEmitter) 61 | assert isinstance(event_processor, CeleryProcessingService) 62 | assert get_private_attr(event_processor, "__celery") is celery 63 | assert get_private_attr(event_processor, "__queue") is queue 64 | assert event_linker is IsolatedEventLinker 65 | assert logger.debug_enabled is True 66 | 67 | # ================================= 68 | # Test Cases for ExecutorEventEmitter 69 | # ================================= 70 | 71 | def test_ExecutorEventEmitter(self) -> None: # noqa: N802 72 | from concurrent.futures import ThreadPoolExecutor 73 | 74 | from pyventus.core.processing.executor import ExecutorProcessingService 75 | 76 | # Arrange 77 | class IsolatedEventLinker(EventLinker): ... 78 | 79 | executor = ThreadPoolExecutor() 80 | 81 | # Act 82 | event_emitter = ExecutorEventEmitter(executor=executor, event_linker=IsolatedEventLinker, debug=True) 83 | event_processor = get_private_attr(event_emitter, "__event_processor") 84 | event_linker = get_private_attr(event_emitter, "__event_linker") 85 | logger = get_private_attr(event_emitter, "__logger") 86 | 87 | # Assert creation and properties 88 | assert event_emitter is not None 89 | assert isinstance(event_emitter, EventEmitter) 90 | assert isinstance(event_processor, ExecutorProcessingService) 91 | assert get_private_attr(event_processor, "__executor") is executor 92 | assert event_linker is IsolatedEventLinker 93 | assert logger.debug_enabled is True 94 | assert executor._shutdown is False 95 | 96 | # ================================= 97 | # Test Cases for ExecutorEventEmitterCtx 98 | # ================================= 99 | 100 | def test_ExecutorEventEmitterCtx(self) -> None: # noqa: N802 101 | from concurrent.futures import ThreadPoolExecutor 102 | 103 | from pyventus.core.processing.executor import ExecutorProcessingService 104 | 105 | # Arrange 106 | class IsolatedEventLinker(EventLinker): ... 107 | 108 | executor = ThreadPoolExecutor() 109 | 110 | # Act 111 | with ExecutorEventEmitterCtx(executor=executor, event_linker=IsolatedEventLinker, debug=True) as event_emitter: 112 | event_processor = get_private_attr(event_emitter, "__event_processor") 113 | event_linker = get_private_attr(event_emitter, "__event_linker") 114 | logger = get_private_attr(event_emitter, "__logger") 115 | 116 | # Assert creation and properties 117 | assert event_emitter is not None 118 | assert isinstance(event_emitter, EventEmitter) 119 | assert isinstance(event_processor, ExecutorProcessingService) 120 | assert get_private_attr(event_processor, "__executor") is executor 121 | assert event_linker is IsolatedEventLinker 122 | assert logger.debug_enabled is True 123 | assert executor._shutdown is True 124 | 125 | # ================================= 126 | # Test Cases for FastAPIEventEmitter 127 | # ================================= 128 | 129 | def test_FastAPIEventEmitter(self) -> None: # noqa: N802 130 | from fastapi import BackgroundTasks, Depends, FastAPI 131 | from fastapi.testclient import TestClient 132 | from pyventus.core.processing.fastapi import FastAPIProcessingService 133 | from starlette.status import HTTP_200_OK 134 | 135 | # Arrange 136 | class IsolatedEventLinker(EventLinker): ... 137 | 138 | client = TestClient(FastAPI()) 139 | 140 | # Act 141 | @client.app.get("/") # type: ignore[attr-defined, misc] 142 | def api( 143 | background_tasks: BackgroundTasks, 144 | event_emitter: EventEmitter = Depends(FastAPIEventEmitter(IsolatedEventLinker, True)), # noqa: B008 145 | ) -> None: 146 | event_processor = get_private_attr(event_emitter, "__event_processor") 147 | event_linker = get_private_attr(event_emitter, "__event_linker") 148 | logger = get_private_attr(event_emitter, "__logger") 149 | 150 | # Assert creation and properties 151 | assert event_emitter is not None 152 | assert isinstance(event_emitter, EventEmitter) 153 | assert isinstance(event_processor, FastAPIProcessingService) 154 | assert get_private_attr(event_processor, "__background_tasks") is background_tasks 155 | assert event_linker is IsolatedEventLinker 156 | assert logger.debug_enabled is True 157 | 158 | assert client.get("/").status_code == HTTP_200_OK 159 | 160 | # ================================= 161 | # Test Cases for RedisEventEmitter 162 | # ================================= 163 | 164 | def test_RedisEventEmitter(self) -> None: # noqa: N802 165 | from fakeredis import FakeStrictRedis 166 | from pyventus.core.processing.redis import RedisProcessingService 167 | from pyventus.events import RedisEventEmitter 168 | from rq import Queue 169 | 170 | # Arrange 171 | class IsolatedEventLinker(EventLinker): ... 172 | 173 | queue = Queue(connection=FakeStrictRedis(), is_async=False) 174 | options = {"ttl": 1} 175 | 176 | # Act 177 | event_emitter = RedisEventEmitter(queue=queue, options=options, event_linker=IsolatedEventLinker, debug=True) 178 | event_processor = get_private_attr(event_emitter, "__event_processor") 179 | event_linker = get_private_attr(event_emitter, "__event_linker") 180 | logger = get_private_attr(event_emitter, "__logger") 181 | 182 | # Assert creation and properties 183 | assert event_emitter is not None 184 | assert isinstance(event_emitter, EventEmitter) 185 | assert isinstance(event_processor, RedisProcessingService) 186 | assert get_private_attr(event_processor, "__queue") is queue 187 | assert get_private_attr(event_processor, "__options") is options 188 | assert event_linker is IsolatedEventLinker 189 | assert logger.debug_enabled is True 190 | --------------------------------------------------------------------------------