/usr/share/doc/python-pygresql/_sources/contents/pg/notification.txt is in python-pygresql-doc 1:5.0.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | The Notification Handler
========================
.. py:currentmodule:: pg
PyGreSQL comes with a client-side asynchronous notification handler that
was based on the ``pgnotify`` module written by Ng Pheng Siong.
.. versionadded:: 4.1.1
Instantiating the notification handler
--------------------------------------
.. class:: NotificationHandler(db, event, callback, [arg_dict], [timeout], [stop_event])
Create an instance of the notification handler
:param int db: the database connection
:type db: :class:`Connection`
:param str event: the name of an event to listen for
:param callback: a callback function
:param dict arg_dict: an optional dictionary for passing arguments
:param timeout: the time-out when waiting for notifications
:type timeout: int, float or None
:param str stop_event: an optional different name to be used as stop event
You can also create an instance of the NotificationHandler using the
:class:`DB.connection_handler` method. In this case you don't need to
pass a database connection because the :class:`DB` connection itself
will be used as the datebase connection for the notification handler.
You must always pass the name of an *event* (notification channel) to listen
for and a *callback* function.
You can also specify a dictionary *arg_dict* that will be passed as the
single argument to the callback function, and a *timeout* value in seconds
(a floating point number denotes fractions of seconds). If it is absent
or *None*, the callers will never time out. If the time-out is reached,
the callback function will be called with a single argument that is *None*.
If you set the *timeout* to ``0``, the handler will poll notifications
synchronously and return.
You can specify the name of the event that will be used to signal the handler
to stop listening as *stop_event*. By default, it will be the event name
prefixed with ``'stop_'``.
All of the parameters will be also available as attributes of the
created notification handler object.
Invoking the notification handler
---------------------------------
To invoke the notification handler, just call the instance without passing
any parameters.
The handler is a loop that listens for notifications on the event and stop
event channels. When either of these notifications are received, its
associated *pid*, *event* and *extra* (the payload passed with the
notification) are inserted into its *arg_dict* dictionary and the callback
is invoked with this dictionary as a single argument. When the handler
receives a stop event, it stops listening to both events and return.
In the special case that the timeout of the handler has been set to ``0``,
the handler will poll all events synchronously and return. If will keep
listening until it receives a stop event.
.. warning::
If you run this loop in another thread, don't use the same database
connection for database operations in the main thread.
Sending notifications
---------------------
You can send notifications by either running ``NOTIFY`` commands on the
database directly, or using the following method:
.. method:: NotificationHandler.notify([db], [stop], [payload])
Generate a notification
:param int db: the database connection for sending the notification
:type db: :class:`Connection`
:param bool stop: whether to produce a normal event or a stop event
:param str payload: an optional payload to be sent with the notification
This method sends a notification event together with an optional *payload*.
If you set the *stop* flag, a stop notification will be sent instead of
a normal notification. This will cause the handler to stop listening.
.. warning::
If the notification handler is running in another thread, you must pass
a different database connection since PyGreSQL database connections are
not thread-safe.
Auxiliary methods
-----------------
.. method:: NotificationHandler.listen()
Start listening for the event and the stop event
This method is called implicitly when the handler is invoked.
.. method:: NotificationHandler.unlisten()
Stop listening for the event and the stop event
This method is called implicitly when the handler receives a stop event
or when it is closed or deleted.
.. method:: NotificationHandler.close()
Stop listening and close the database connection
You can call this method instead of :meth:`NotificationHandler.unlisten`
if you want to close not only the handler, but also the database connection
it was created with.
|