postgresql-notification-listener 1.0.0__tar.gz

postgresql_notification_listener-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Falcony.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

postgresql_notification_listener-1.0.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.1
+Name: postgresql-notification-listener
+Version: 1.0.0
+Summary: Execute functions on PostgreSQL notifications
+Home-page: https://github.com/tvuotila/postgresql-notification-listener
+License: MIT
+Author: Tero Vuotila
+Author-email: tero.vuotila@falcony.io
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: psycopg
+Project-URL: Repository, https://github.com/tvuotila/postgresql-notification-listener
+Description-Content-Type: text/markdown
+
+# PostgreSQL Notification Listener
+
+This project is a Python library that listens to notifications from a PostgreSQL database.
+It provides a simple way to execute functions when specific events happen in the database.
+
+## How it works
+
+The listener connects to the PostgreSQL database and sets up a notification channel. You can then attach callbacks to this channel, which will be executed whenever a notification is received.
+
+## Installation
+
+To install the library, run:
+pip install postgresql-notification-listener
+
+### Usage
+
+To use this library, follow these steps:
+
+* Import the library in your Python script: `from postgresql_notification_listener import NotificationListener`
+* Create instance of the listener `listener = NotificationListener("host=your_host port=your_port dbname=your_database user=your_username password=your_password")`
+* Define a callback function that will be executed when a notification is received.
+* Use the `subscribe_to_channel` method to attach your callback function to the notification channel: `listener.subscribe_to_channel("channel_to_listen", callback_function)`
+* Start listening for notifications by calling the `start` method: `listener.start()`
+* You can trigger a notification from PostgreSQL by `NOTIFY channel_to_listen` statement.
+* The `start` method will call all attached callbacks once when called. If you don't want this behaviour, pass the `initial_run=False` argument to the start method: `listener.start(initial_run=False)`
+* You can get the notification that caused the callback from the `last_notification` attribute on the listener instance `listener.last_notification`
+
+
+### API
+* **NotificationListener**: The main class of this library. It is responsible for setting up a notification channel and managing callbacks.
+	+ **subscribe_to_channel** : Attaches a callback function to a specific channel.  The `subscribe_to_channel` method takes two required parameters: the name of the channel to listen to and the callback function to execute when a notification is received.
+	+ **start** : Starts listening for notifications. If you don't want all attached callbacks to be called once when called, pass `initial_run=False` as an argument.
+	+ **last_notification**: Returns the latest notification that caused a callback.
+
+

postgresql_notification_listener-1.0.0/README.md

@@ -0,0 +1,34 @@
+# PostgreSQL Notification Listener
+
+This project is a Python library that listens to notifications from a PostgreSQL database.
+It provides a simple way to execute functions when specific events happen in the database.
+
+## How it works
+
+The listener connects to the PostgreSQL database and sets up a notification channel. You can then attach callbacks to this channel, which will be executed whenever a notification is received.
+
+## Installation
+
+To install the library, run:
+pip install postgresql-notification-listener
+
+### Usage
+
+To use this library, follow these steps:
+
+* Import the library in your Python script: `from postgresql_notification_listener import NotificationListener`
+* Create instance of the listener `listener = NotificationListener("host=your_host port=your_port dbname=your_database user=your_username password=your_password")`
+* Define a callback function that will be executed when a notification is received.
+* Use the `subscribe_to_channel` method to attach your callback function to the notification channel: `listener.subscribe_to_channel("channel_to_listen", callback_function)`
+* Start listening for notifications by calling the `start` method: `listener.start()`
+* You can trigger a notification from PostgreSQL by `NOTIFY channel_to_listen` statement.
+* The `start` method will call all attached callbacks once when called. If you don't want this behaviour, pass the `initial_run=False` argument to the start method: `listener.start(initial_run=False)`
+* You can get the notification that caused the callback from the `last_notification` attribute on the listener instance `listener.last_notification`
+
+
+### API
+* **NotificationListener**: The main class of this library. It is responsible for setting up a notification channel and managing callbacks.
+	+ **subscribe_to_channel** : Attaches a callback function to a specific channel.  The `subscribe_to_channel` method takes two required parameters: the name of the channel to listen to and the callback function to execute when a notification is received.
+	+ **start** : Starts listening for notifications. If you don't want all attached callbacks to be called once when called, pass `initial_run=False` as an argument.
+	+ **last_notification**: Returns the latest notification that caused a callback.
+

postgresql_notification_listener-1.0.0/postgresql_notification_listener/__init__.py

@@ -0,0 +1,3 @@
+from .listener import NotificationListener
+
+__all__ = ("NotificationListener",)

postgresql_notification_listener-1.0.0/postgresql_notification_listener/listener.py

@@ -0,0 +1,130 @@
+from types import TracebackType
+from typing import NoReturn, Self
+
+import psycopg
+from psycopg import sql, Notify
+
+from .types import Callback
+
+
+class NotificationListener:
+    """
+    NotificationListener listens to notifications from a PostgreSQL database.
+
+    Callbacks can be attached to the listener to be called when notification is received.
+    """
+
+    def __init__(self, database_url: str) -> None:
+        # Stores latest Notify object in case callbacks need it
+        self.last_notification: Notify | None = None
+        self.connection = psycopg.connect(database_url, autocommit=True)
+        self.callbacks: dict[str, set[Callback]] = {}
+
+    ## Context manager methods ##
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self.connection.close()
+
+    ## Subscription methods ##
+
+    def _get_or_create_listening_channel(self, channel: str) -> set[Callback]:
+        if channel not in self.callbacks:
+            self.callbacks[channel] = set()
+            self.connection.execute(
+                sql.SQL("LISTEN {}").format(sql.Identifier(channel))
+            )
+        return self.callbacks[channel]
+
+    def subscribe_to_channel(
+        self,
+        channel: str,
+        callback: Callback,
+    ) -> None:
+        """
+        Subscribes to a channel and associates a callback function with it.
+        If callback is already associated with the channel, old association will be overwritten.
+
+        Args:
+            channel (str): The name of the channel to subscribe to.
+            callback (Callable): The callback function to be executed when a notification is received.
+        """
+        self._get_or_create_listening_channel(channel).add(callback)
+
+    ## Unsubscription methods ##
+
+    def unsubscribe_from_channel(self, channel: str, callback: Callback) -> None:
+        """
+        Unsubscribe the specified callback function from a channel.
+
+        Args:
+            channel (str): The channel to unsubscribe from.
+            callback (Callable): The callback function to remove.
+
+        Raises: KeyError if channel or callback is not subscribed
+        """
+        self.callbacks[channel].remove(callback)
+        if not self.callbacks[channel]:
+            self.unsubscribe_channel(channel)
+
+    def unsubscribe_channel(self, channel: str) -> None:
+        """
+        Unsubscribe all callback functions from a channel.
+
+        Args:
+            channel (str): The channel to unsubscribe from.
+
+        Raises: KeyError if channel is not subscribed
+        """
+        del self.callbacks[channel]
+        self.connection.execute(sql.SQL("UNLISTEN {}").format(sql.Identifier(channel)))
+
+    def unsubscribe_all(self) -> None:
+        """
+        Unsubscribe all callback functions from all channels.
+        """
+        for channel in list(self.callbacks):
+            self.unsubscribe_channel(channel)
+
+    ## Listening methods ##
+
+    def start(self, initial_run: bool = True) -> NoReturn:  # type: ignore[misc]  # We never return
+        """
+        Starts the notification listener and executes the callbacks for each received notification.
+        Duplicate notifications for a channel are ignored.
+        This function will never return.
+
+        Args:
+            initial_run (bool): Execute all callbacks before listening starts.
+            This makes sure that no notifications are left unporcessed
+            while the notification listened was not running.
+            (default: True)
+        """
+        if initial_run:
+            self.execute_all_callbacks()
+        self._notification_generator = self.connection.notifies()
+        for notification in self._notification_generator:
+            self.last_notification = notification
+            self.execute_callbacks(notification.channel)
+
+    ## Execution methods ##
+    def execute_all_callbacks(self) -> None:
+        for channel in self.callbacks:
+            self.execute_callbacks(channel)
+
+    def execute_callbacks(self, channel: str) -> None:
+        if channel not in self.callbacks:
+            return
+        # Use a copy to allow callbacks to be removed during iteration
+        for callback in self.callbacks[channel].copy():
+            callback()

postgresql_notification_listener-1.0.0/postgresql_notification_listener/types.py

@@ -0,0 +1,4 @@
+from typing import Any, Callable
+
+
+Callback = Callable[[], Any]

postgresql_notification_listener-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[tool.poetry]
+name = "postgresql-notification-listener"
+version = "1.0.0"
+description = "Execute functions on PostgreSQL notifications"
+authors = ["Tero Vuotila <tero.vuotila@falcony.io>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/tvuotila/postgresql-notification-listener"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+psycopg = "*"
+
+
+[tool.poetry.group.dev.dependencies]
+mypy = "*"
+ruff = "*"
+black = "*"
+pytest = "*"
+pytest-timeout = "*"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.mypy]
+exclude = ["dist"]
+warn_unused_ignores = true
+show_error_codes = true
+strict = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+check_untyped_defs = true
+disallow_untyped_defs = false
+disallow_untyped_calls = false