docs: add docs for `Error.pgconn` and `Error.pgresult`

diff --git a/docs/api/errors.rst b/docs/api/errors.rst
index 6d5ed6519ba2c3aa0a5d6b7d6d6448a8a463ab72..6d810d39aabe569759ac92fa68943d417df360ac 100644 (file)
--- a/docs/api/errors.rst
+++ b/docs/api/errors.rst
@@ -48,6 +48,20 @@ These classes are exposed both by this module and the root `psycopg` module.
         This attribute is also available as class attribute on the
         :ref:`sqlstate-exceptions` classes.
 
+    .. autoattribute:: pgconn
+
+        Most likely it will be in `~psycopg.pq.ConnStatus.BAD` state;
+        however it might be useful to verify precisely what went wrong, for
+        instance checking the `~psycopg.pq.PGconn.needs_password` and
+        `~psycopg.pq.PGconn.used_password`.
+
+        .. versionadded:: 3.1
+
+    .. autoattribute:: pgresult
+
+        .. versionadded:: 3.1
+
+
 .. autoexception:: Warning()
 .. autoexception:: InterfaceError()
 .. autoexception:: DatabaseError()

diff --git a/docs/news.rst b/docs/news.rst
index 6a7ac3b28bea9af22b7c7d88ee6b3541f4708328..4351e3d2aabb61ecf6af4e03dbf526c92c284e92 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -18,6 +18,7 @@ Psycopg 3.1 (unreleased)
   result set can be accessed by calling `~Cursor.nextset()` (:ticket:`#164`).
 - Add `pq.PGconn.trace()` and related trace functions (:ticket:`#167`).
 - Add *prepare_threshold* parameter to `Connection` init (:ticket:`#200`).
+- Add `Error.pgconn` and `Error.pgresult` attributes (:ticket:`#242`).
 - Drop support for Python 3.6.
 
 

diff --git a/psycopg/psycopg/errors.py b/psycopg/psycopg/errors.py
index e77fa8c39341a3025952a1cfe82d421be7707688..9ac5ae4137d07de98aef491b00c71b64a88bf004 100644 (file)
--- a/psycopg/psycopg/errors.py
+++ b/psycopg/psycopg/errors.py
@@ -71,10 +71,18 @@ class Error(Exception):
 
     @property
     def pgconn(self) -> Optional[PGconn]:
+        """The connection object, if the error was raised from a connection attempt.
+
+        :rtype: Optional[psycopg.pq.PGconn]
+        """
         return self._pgconn if self._pgconn else None
 
     @property
     def pgresult(self) -> Optional[PGresult]:
+        """The result object, if the exception was raised after a failed query.
+
+        :rtype: Optional[psycopg.pq.PGresult]
+        """
         return self._info if _is_pgresult(self._info) else None
 
     @property