Added documentation for the Notify object.

doc/src/advanced.rst

@@ -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
     ...
 

doc/src/connection.rst

@@ -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
 

doc/src/extensions.rst

@@ -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

psycopg/notify_type.c

@@ -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,