mirror of
https://github.com/psycopg/psycopg2.git
synced 2025-02-25 21:20:32 +03:00
Added documentation for the Notify object.
This commit is contained in:
parent
4ec298e112
commit
1a0fca09d9
|
@ -208,14 +208,19 @@ read:
|
|||
Asynchronous notifications
|
||||
--------------------------
|
||||
|
||||
.. versionchanged:: 2.2.3
|
||||
Added `~psycopg2.extensions.Notify` object allowing to retrieve
|
||||
the notification payload if connected to a PostgreSQL 9.0 server.
|
||||
|
||||
Psycopg allows asynchronous interaction with other database sessions using the
|
||||
facilities offered by PostgreSQL commands |LISTEN|_ and |NOTIFY|_. Please
|
||||
refer to the PostgreSQL documentation for examples of how to use this form of
|
||||
refer to the PostgreSQL documentation for examples about how to use this form of
|
||||
communication.
|
||||
|
||||
Notifications received are made available in the `connection.notifies`
|
||||
list. Notifications can be sent from Python code simply using a :sql:`NOTIFY`
|
||||
command in an `~cursor.execute()` call.
|
||||
Notifications are instances of the `~psycopg2.extensions.Notify` object made
|
||||
available upon reception in the `connection.notifies` list. Notifications can
|
||||
be sent from Python code simply using a :sql:`NOTIFY` command in an
|
||||
`~cursor.execute()` call.
|
||||
|
||||
Because of the way sessions interact with notifications (see |NOTIFY|_
|
||||
documentation), you should keep the connection in :ref:`autocommit
|
||||
|
@ -248,7 +253,8 @@ something to read::
|
|||
curs = conn.cursor()
|
||||
curs.execute("LISTEN test;")
|
||||
|
||||
print "Waiting for 'NOTIFY test'"
|
||||
# Payload only available since PostgreSQL 9.0
|
||||
print "Waiting for 'NOTIFY test', 'hello'"
|
||||
while 1:
|
||||
if select.select([conn],[],[],5) == ([],[],[]):
|
||||
print "Timeout"
|
||||
|
@ -263,7 +269,7 @@ Running the script and executing the command :sql:`NOTIFY test` in a separate
|
|||
Waiting for 'NOTIFY test'
|
||||
Timeout
|
||||
Timeout
|
||||
Got NOTIFY: (6535, 'test')
|
||||
Got NOTIFY: Notify(6535, 'test', 'hello')
|
||||
Timeout
|
||||
...
|
||||
|
||||
|
|
|
@ -203,15 +203,17 @@ The ``connection`` class
|
|||
|
||||
.. attribute:: notifies
|
||||
|
||||
List containing asynchronous notifications received by the session.
|
||||
|
||||
Received notifications have the form of a 2 items tuple
|
||||
:samp:`({pid},{name})`, where :samp:`{pid}` is the PID of the backend
|
||||
that sent the notification and :samp:`{name}` is the signal name
|
||||
specified in the :sql:`NOTIFY` command.
|
||||
List of `~psycopg2.extensions.Notify` objects containing asynchronous
|
||||
notifications received by the session.
|
||||
|
||||
For other details see :ref:`async-notify`.
|
||||
|
||||
.. versionchanged:: 2.2.3
|
||||
Notifications are instances of the `!Notify` object. Previously the
|
||||
list was composed by 2 items tuples :samp:`({pid},{channel})` and
|
||||
the payload was not accessible. To keep backward compatibility,
|
||||
`!Notify` objects can still be accessed as 2 items tuples.
|
||||
|
||||
.. index::
|
||||
pair: Backend; PID
|
||||
|
||||
|
|
|
@ -106,6 +106,12 @@ functionalities defined by the |DBAPI|_.
|
|||
Close the object and remove it from the database.
|
||||
|
||||
|
||||
.. autoclass:: Notify(pid, channel, payload=None)
|
||||
:members: pid, channel, payload
|
||||
|
||||
.. versionadded:: 2.2.3
|
||||
|
||||
|
||||
.. autofunction:: set_wait_callback(f)
|
||||
|
||||
.. versionadded:: 2.2.0
|
||||
|
|
|
@ -33,10 +33,32 @@
|
|||
#include "psycopg/psycopg.h"
|
||||
#include "psycopg/notify.h"
|
||||
|
||||
static const char notify_doc[] =
|
||||
"A notification received from the backend.\n\n"
|
||||
"`!Notify` instances are made available upon reception on the\n"
|
||||
"`~connection.notifies` member of the listening connection. The object\n"
|
||||
"can be also accessed as a 2 items tuple returning the members\n"
|
||||
":samp:`({pid},{channel})` for backward compatibility.\n\n"
|
||||
"See :ref:`async-notify` for details.";
|
||||
|
||||
static const char pid_doc[] =
|
||||
"The ID of the backend process that sent the notification.\n\n"
|
||||
"Note: if the sending session was handled by Psycopg, you can use\n"
|
||||
"`~connection.get_backend_pid()` to know its PID.";
|
||||
|
||||
static const char channel_doc[] =
|
||||
"The name of the channel to which the notification was sent.";
|
||||
|
||||
static const char payload_doc[] =
|
||||
"The payload message of the notification.\n\n"
|
||||
"Attaching a payload to a notification is only available since\n"
|
||||
"PostgreSQL 9.0: for notifications received from previous versions\n"
|
||||
"of the server this member is always the empty string.";
|
||||
|
||||
static PyMemberDef notify_members[] = {
|
||||
{ "pid", T_OBJECT, offsetof(NotifyObject, pid), RO },
|
||||
{ "channel", T_OBJECT, offsetof(NotifyObject, channel), RO },
|
||||
{ "payload", T_OBJECT, offsetof(NotifyObject, payload), RO },
|
||||
{ "pid", T_OBJECT, offsetof(NotifyObject, pid), RO, (char *)pid_doc },
|
||||
{ "channel", T_OBJECT, offsetof(NotifyObject, channel), RO, (char *)channel_doc },
|
||||
{ "payload", T_OBJECT, offsetof(NotifyObject, payload), RO, (char *)payload_doc },
|
||||
{ NULL }
|
||||
};
|
||||
|
||||
|
@ -172,9 +194,6 @@ static PySequenceMethods notify_sequence = {
|
|||
};
|
||||
|
||||
|
||||
static const char notify_doc[] =
|
||||
"A notification received from the backend.";
|
||||
|
||||
PyTypeObject NotifyType = {
|
||||
PyObject_HEAD_INIT(NULL)
|
||||
0,
|
||||
|
|
Loading…
Reference in New Issue
Block a user