From 9e4f89a2a1e154d05f48b996a20fef1bdbbe9d51 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sun, 20 May 2018 20:13:04 +0100 Subject: [PATCH] encrypt_password docs moved to extension module and updated --- doc/src/connection.rst | 27 --------------------------- doc/src/extensions.rst | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/doc/src/connection.rst b/doc/src/connection.rst index d656fa1b..2910f301 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -676,33 +676,6 @@ The ``connection`` class .. __: http://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS - .. method:: encrypt_password(password, user, [algorithm]) - - Returns the encrypted form of a PostgreSQL password based on the - current password encryption algorithm. - - Raises `~psycopg2.NotSupportedError` if the ``psycopg2`` module was - compiled with a ``libpq`` version lesser than 10 (which can be detected - by the `~psycopg2.__libpq_version__` constant), when encryption - algorithm other than 'md5' is specified for the server version greater - than, or equal to 10. - - Ignores the encrytion algorithm for servers version less than 10, and - always uses 'md5' as encryption algorithm. - - .. seealso:: libpq docs for `PQencryptPasswordConn()`__ for details. - - .. __: https://www.postgresql.org/docs/devel/static/libpq-misc.html#libpq-pqencryptpasswordconn - - .. seealso:: libpq docs for `PQencryptPassword()`__ for details. - - .. __: https://www.postgresql.org/docs/devel/static/libpq-misc.html#libpq-pqencryptpassword - - .. seealso:: libpq docs for `password_encryption`__ for details. - - .. __: https://www.postgresql.org/docs/devel/static/runtime-config-connection.html#guc-password-encryption - - .. index:: pair: Protocol; Version diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index 8545fcfa..34d53a7e 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -555,6 +555,38 @@ Other functions .. __: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER +.. method:: encrypt_password(password, user, scope=None, algorithm=None) + + Return the encrypted form of a PostgreSQL password. + + :param password: the cleartext password to encrypt + :param user: the name of the user to use the password for + :param scope: the scope to encrypt the password into; if *algorithm* is + ``md5`` it can be `!None` + :type scope: `connection` or `cursor` + :param algorithm: the password encryption algorithm to use + + The *algorithm* ``md5`` is always supported. Other algorithms are only + supported if the client libpq version is at least 10 and may require a + compatible server version: check the `PostgreSQL encryption + documentation`__ to know the algorithms supported by your server. + + .. __: https://www.postgresql.org/docs/current/static/encryption-options.html + + Using `!None` as *algorithm* will result in querying the server to know the + current server password encryption setting, which is a blocking operation: + query the server separately and specify a value for *algorithm* if you + want to maintain a non-blocking behaviour. + + .. versionadded:: 2.8 + + .. seealso:: PostgreSQL docs for the `password_encryption`__ setting, libpq `PQencryptPasswordConn()`__, `PQencryptPassword()`__ functions. + + .. __: https://www.postgresql.org/docs/current/static/runtime-config-connection.html#GUC-PASSWORD-ENCRYPTION + .. __: https://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORDCONN + .. __: https://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQENCRYPTPASSWORD + + .. index:: pair: Isolation level; Constants