LISTEN/NOTIFY funcionality

Signed-off-by: chandr-andr (Kiselev Aleksandr) <chandr@chandr.net>

Author: chandr-andr

python/psqlpy/_internal/__init__.pyi

@@ -1828,7 +1828,7 @@ class Listener:
         self: Self,
         channel: str,
         callback: Callable[
-            [str, str, int, Connection],
+            [Connection, str, str, int],
             Awaitable[None],
         ],
     ) -> None:
@@ -1837,12 +1837,14 @@ class Listener:
         Callback must be async function and have signature like this:
         ```python
         async def callback(
-            channel: str,
-            payload: str,
-            process_id: str,
             connection: Connection,
+            payload: str,
+            channel: str,
+            process_id: int,
         ) -> None: ...
         ```
+
+        Callback parameters are passed as args.
         """
 
     async def clear_channel_callbacks(self, channel: str) -> None:
@@ -1852,12 +1854,14 @@ class Listener:
         - `channel`: name of the channel.
         """
 
+    async def clear_all_channels(self) -> None:
+        """Clear all channels callbacks."""
+
     def listen(self: Self) -> None:
         """Start listening.
 
         Start actual listening.
         In the background it creates task in Rust event loop.
-        You must save returned Future to the array.
         """
 
     def abort_listen(self: Self) -> None:

python/psqlpy/_internal/exceptions.pyi

@@ -79,3 +79,15 @@ class PyToRustValueMappingError(RustPSQLDriverPyBaseError):
     You can get this exception when executing queries with parameters.
     So, if there are no parameters for the query, don't handle this error.
     """
+
+class BaseListenerError(RustPSQLDriverPyBaseError):
+    """Base error for all Listener errors."""
+
+class ListenerStartError(BaseListenerError):
+    """Error if listener start failed."""
+
+class ListenerClosedError(BaseListenerError):
+    """Error if listener manipulated but it's closed."""
+
+class ListenerCallbackError(BaseListenerError):
+    """Error if callback passed to listener isn't a coroutine."""

python/psqlpy/exceptions.py

@@ -2,6 +2,7 @@
     BaseConnectionError,
     BaseConnectionPoolError,
     BaseCursorError,
+    BaseListenerError,
     BaseTransactionError,
     ConnectionClosedError,
     ConnectionExecuteError,
@@ -12,6 +13,9 @@
     CursorCloseError,
     CursorFetchError,
     CursorStartError,
+    ListenerCallbackError,
+    ListenerClosedError,
+    ListenerStartError,
     MacAddrConversionError,
     PyToRustValueMappingError,
     RustPSQLDriverPyBaseError,
@@ -29,6 +33,7 @@
     "BaseConnectionError",
     "BaseConnectionPoolError",
     "BaseCursorError",
+    "BaseListenerError",
     "BaseTransactionError",
     "ConnectionClosedError",
     "ConnectionExecuteError",
@@ -39,6 +44,9 @@
     "CursorClosedError",
     "CursorFetchError",
     "CursorStartError",
+    "ListenerCallbackError",
+    "ListenerClosedError",
+    "ListenerStartError",
     "MacAddrConversionError",
     "PyToRustValueMappingError",
     "RustPSQLDriverPyBaseError",

python/tests/conftest.py

@@ -68,6 +68,11 @@ def table_name() -> str:
     return random_string()
 
 
+@pytest.fixture
+def listener_table_name() -> str:
+    return random_string()
+
+
 @pytest.fixture
 def number_database_records() -> int:
     return random.randint(10, 35)
@@ -137,6 +142,23 @@ async def create_default_data_for_tests(
     )
 
 
+@pytest.fixture
+async def create_table_for_listener_tests(
+    psql_pool: ConnectionPool,
+    listener_table_name: str,
+) -> AsyncGenerator[None, None]:
+    await psql_pool.execute(
+        f"CREATE TABLE {listener_table_name}"
+        f"(id SERIAL, payload VARCHAR(255),"
+        f"channel VARCHAR(255), process_id INT)",
+    )
+
+    yield
+    await psql_pool.execute(
+        f"DROP TABLE {listener_table_name}",
+    )
+
+
 @pytest.fixture
 async def test_cursor(
     psql_pool: ConnectionPool,