From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 12 Nov 2020 01:02:15 +0000 (+0000)
Subject: More Connection documentation.
X-Git-Tag: 3.0.dev0~378
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2e51ef7621402345a7adf3152f1935bd075ccf95;p=thirdparty%2Fpsycopg.git

More Connection documentation.
---

diff --git a/docs/connection.rst b/docs/connection.rst
index 16067494f..5ccb9f7a0 100644
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -69,7 +69,7 @@ Take a look to :ref:`transactions` for the details.
 
         TODO
 
-    .. rubric:: Methods you will need if you do something cool
+    .. rubric:: Methods you can use to do something cool
 
     .. automethod:: notifies
 
@@ -82,6 +82,12 @@ Take a look to :ref:`transactions` for the details.
 
     See :ref:`async-notify` for details.
 
+    .. automethod:: cancel
+    .. automethod:: add_notice_handler
+    .. automethod:: remove_notice_handler
+
+    TODO: document `Diagnostic`
+
 
 .. autoclass:: AsyncConnection
 
@@ -103,3 +109,4 @@ Take a look to :ref:`transactions` for the details.
 
 
 .. autoclass:: Notify
+    :members: channel, payload, pid
diff --git a/psycopg3/psycopg3/connection.py b/psycopg3/psycopg3/connection.py
index 9ef0c9935..dd1b04f45 100644
--- a/psycopg3/psycopg3/connection.py
+++ b/psycopg3/psycopg3/connection.py
@@ -46,8 +46,13 @@ class Notify(NamedTuple):
     """An asynchronous notification received from the database."""
 
     channel: str
+    """The name of the channel on which the notification was received."""
+
     payload: str
+    """The message attached to the notification."""
+
     pid: int
+    """The PID of the backend process which sent the notification."""
 
 
 NoticeHandler = Callable[[e.Diagnostic], None]
@@ -138,13 +143,20 @@ class BaseConnection:
         raise NotImplementedError
 
     def cancel(self) -> None:
+        """Cancel the current operation on the connection."""
         c = self.pgconn.get_cancel()
         c.cancel()
 
     def add_notice_handler(self, callback: NoticeHandler) -> None:
+        """
+        Register a callable to be invoked when a notice message is received.
+        """
         self._notice_handlers.append(callback)
 
     def remove_notice_handler(self, callback: NoticeHandler) -> None:
+        """
+        Unregister a notice message callable previously registered.
+        """
         self._notice_handlers.remove(callback)
 
     @staticmethod