From 212093df0e064499ce220de452bb35f74f43ccb4 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Tue, 28 Oct 2025 02:00:06 +0000 Subject: [PATCH] docs(pool): add API documentation for conninfo/kwargs as callable --- docs/api/pool.rst | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/api/pool.rst b/docs/api/pool.rst index 68cd3858b..f06fa12e2 100644 --- a/docs/api/pool.rst +++ b/docs/api/pool.rst @@ -48,9 +48,10 @@ The `!ConnectionPool` class arguments have meaningful defaults and can probably be tweaked later, if required. - :param conninfo: The connection string. See - `~psycopg.Connection.connect()` for details. - :type conninfo: `!str` + :param conninfo: The connection string. See `~psycopg.Connection.connect()` + for details. If it is a callable it will be called at + every connection attempt. + :type conninfo: `!str` or `!Callable[[], str]` :param connection_class: The class of the connections to serve. It should be a `!Connection` subclass. @@ -58,9 +59,9 @@ The `!ConnectionPool` class :param kwargs: Extra arguments to pass to `!connect()`. Note that this is *one dict argument* of the pool constructor, which is - expanded as `connect()` keyword parameters. - - :type kwargs: `!dict` + expanded as `connect()` keyword parameters. If it is a + callable it will be called at every connection attempt. + :type kwargs: `!dict[str, Any]` or `!Callable[[], dict[str, Any]]` :param min_size: The minimum number of connection the pool will hold. The pool will actively try to create new connections if some @@ -181,6 +182,9 @@ The `!ConnectionPool` class .. versionchanged:: 3.3 added `!close_returns` parameter to the constructor. + .. versionchanged:: 3.3 + `conninfo` and `kwargs` can be callable. + .. warning:: At the moment, the default value for the `!open` parameter is `!True`; @@ -284,10 +288,18 @@ Only the functions and parameters with different signature from .. autoclass:: AsyncConnectionPool + :param conninfo: The connection string. It can be an async function too. + :type conninfo: `!str` or `!Callable[[], str]` or `async Callable[[], str]` + :param connection_class: The class of the connections to serve. It should be an `!AsyncConnection` subclass. :type connection_class: `!type`, default: `~psycopg.AsyncConnection` + :param kwargs: Extra arguments to pass to `!connect()`. It can be an async + function too. + :type kwargs: `!dict[str, Any]` or `!Callable[[], dict[str, Any]]` + or `async !Callable[[], dict[str, Any]]` + :param check: A callback to check that a connection is working correctly when obtained by the pool. :type check: `async Callable[[Connection], None]` @@ -313,6 +325,9 @@ Only the functions and parameters with different signature from .. versionchanged:: 3.3 added `!close_returns` parameter to the constructor. + .. versionchanged:: 3.3 + `conninfo` and `kwargs` can be callable (sync or async). + .. warning:: Opening an async pool in the constructor (using `!open=True` on init) -- 2.47.3