From: Denis Laxalde <denis.laxalde@dalibo.com>
Date: Wed, 14 Sep 2022 12:02:43 +0000 (+0200)
Subject: docs: document PGconn.encrypt_password()
X-Git-Tag: 3.1.2~6^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ece43dce6a533ffa0b0fa0385dfbd566fc5dd368;p=thirdparty%2Fpsycopg.git

docs: document PGconn.encrypt_password()

Including an example of usage.
---

diff --git a/docs/api/pq.rst b/docs/api/pq.rst
index 3c135171f..d70071e05 100644
--- 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 a2c86dc40..f61ba3f73 100644
--- 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(