From: Denis Laxalde <denis@laxalde.org>
Date: Sat, 19 Mar 2022 08:46:58 +0000 (+0100)
Subject: docs: document PGconn needs_password and used_password attributes
X-Git-Tag: 3.1~168^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2209d2a294110dcba19ccaa8ee61539c13874e4e;p=thirdparty%2Fpsycopg.git

docs: document PGconn needs_password and used_password attributes

This improves the documentation of Error class, which refers to those
in the new pgconn attribute documentation.
---

diff --git a/docs/api/errors.rst b/docs/api/errors.rst
index 6d810d39a..3f0a719bb 100644
--- a/docs/api/errors.rst
+++ b/docs/api/errors.rst
@@ -53,7 +53,7 @@ These classes are exposed both by this module and the root `psycopg` module.
         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`.
+        `~psycopg.pq.PGconn.used_password` attributes.
 
         .. versionadded:: 3.1
 
diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index 6cd77cbe6..3d259598a 100644
--- a/docs/api/pq.rst
+++ b/docs/api/pq.rst
@@ -88,6 +88,8 @@ Objects wrapping libpq structures and functions
 
     .. autoattribute:: pgconn_ptr
     .. automethod:: get_cancel
+    .. autoattribute:: needs_password
+    .. autoattribute:: used_password
 
 
 .. autoclass:: PGresult()
diff --git a/psycopg/psycopg/pq/pq_ctypes.py b/psycopg/psycopg/pq/pq_ctypes.py
index f286b7ec8..a8acc3d85 100644
--- a/psycopg/psycopg/pq/pq_ctypes.py
+++ b/psycopg/psycopg/pq/pq_ctypes.py
@@ -240,10 +240,19 @@ class PGconn:
 
     @property
     def needs_password(self) -> bool:
+        """True if the connection authentication method required a password,
+        but none was available.
+
+        See :pq:`PQconnectionNeedsPassword` for details.
+        """
         return bool(impl.PQconnectionNeedsPassword(self._pgconn_ptr))
 
     @property
     def used_password(self) -> bool:
+        """True if the connection authentication method used a password.
+
+        See :pq:`PQconnectionUsedPassword` for details.
+        """
         return bool(impl.PQconnectionUsedPassword(self._pgconn_ptr))
 
     @property