docs: document PGconn.encrypt_password()

Including an example of usage.

diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index 3c135171f693c748619dbc82976536356d7b2f24..d70071e05ca9b7e81eb1e4ad49a226132d8627a0 100644 (file)
--- a/docs/api/pq.rst
+++ b/docs/api/pq.rst
@@ -91,6 +91,14 @@ Objects wrapping libpq structures and functions
     .. autoattribute:: needs_password
     .. autoattribute:: used_password
 
+    .. automethod:: encrypt_password
+
+       .. code:: python
+
+           >>> enc = conn.info.encoding
+           >>> encrypted = conn.pgconn.encrypt_password(password.encode(enc), rolename.encode(enc))
+           b'SCRAM-SHA-256$4096:...
+
 
 .. autoclass:: PGresult()
 

diff --git a/psycopg/psycopg/pq/pq_ctypes.py b/psycopg/psycopg/pq/pq_ctypes.py
index a2c86dc40710ab9a987b9d4bffbcb62c8f25cac9..f61ba3f736420434a7c757c01ff019b380fd2fbd 100644 (file)
--- a/psycopg/psycopg/pq/pq_ctypes.py
+++ b/psycopg/psycopg/pq/pq_ctypes.py
@@ -612,6 +612,11 @@ class PGconn:
     def encrypt_password(
         self, passwd: bytes, user: bytes, algorithm: Optional[bytes] = None
     ) -> bytes:
+        """
+        Return the encrypted form of a PostgreSQL password.
+
+        See :pq:`PQencryptPasswordConn` for details.
+        """
         out = impl.PQencryptPasswordConn(self._pgconn_ptr, passwd, user, algorithm)
         if not out:
             raise e.OperationalError(