From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sun, 13 Mar 2022 00:10:46 +0000 (+0000)
Subject: docs: add docs for `Error.pgconn` and `Error.pgresult`
X-Git-Tag: 3.1~168^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7d235eb4702896c8ef3d9b0b9ae2b8e66da230d5;p=thirdparty%2Fpsycopg.git

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

diff --git a/docs/api/errors.rst b/docs/api/errors.rst
index 6d5ed6519..6d810d39a 100644
--- 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 6a7ac3b28..4351e3d2a 100644
--- 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 e77fa8c39..9ac5ae413 100644
--- 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