From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 14 Oct 2023 07:59:57 +0000 (+0200)
Subject: refactor(pool): more logical ordering for kwargs
X-Git-Tag: pool-3.2.0~6
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7b4e7a899926f2012eddca31c0f67d1ba06a0c33;p=thirdparty%2Fpsycopg.git

refactor(pool): more logical ordering for kwargs

- conn construction params (class, kwargs, the class affects the pool
  type annotations so first is better);
- sizing (documented as an important parameter for the pool);
- open?
- callbacks (in the order they are used);
- name;
- other details more unlikely to be touched.

The order is the same in docs and code.
---

diff --git a/docs/api/pool.rst b/docs/api/pool.rst
index 949a5224a..76aed2b7d 100644
--- a/docs/api/pool.rst
+++ b/docs/api/pool.rst
@@ -52,6 +52,16 @@ The `!ConnectionPool` class
                     `~psycopg.Connection.connect()` for details.
    :type conninfo: `!str`
 
+   :param connection_class: The class of the connections to serve. It should
+                            be a `!Connection` subclass.
+   :type connection_class: `!type`, default: `~psycopg.Connection`
+
+   :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`
+
    :param min_size: The minimum number of connection the pool will hold. The
                    pool will actively try to create new connections if some
                    are lost (closed, broken) and will try to never go below
@@ -66,22 +76,19 @@ The `!ConnectionPool` class
                    been unused for more than `!max_idle` seconds.
    :type max_size: `!int`, default: `!None`
 
-   :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`
-
-   :param connection_class: The class of the connections to serve. It should
-                            be a `!Connection` subclass.
-   :type connection_class: `!type`, default: `~psycopg.Connection`
-
    :param open: If `!True`, open the pool, creating the required connections,
                 on init. If `!False`, open the pool when `!open()` is called or
                 when the pool context is entered. See the `open()` method
                 documentation for more details.
    :type open: `!bool`, default: `!True`
 
+   :param configure: A callback to configure a connection after creation.
+                     Useful, for instance, to configure its adapters. If the
+                     connection is used to run internal queries (to inspect the
+                     database) make sure to close an eventual transaction
+                     before leaving the function.
+   :type configure: `Callable[[Connection], None]`
+
    :param check: A callback to check that a connection is working correctly
                  when obtained by the pool. The callback is called at every
                  `getconn()` or `connection()`: the connection is only passed
@@ -91,13 +98,6 @@ The `!ConnectionPool` class
                  want to perform a simple check.
    :type check: `Callable[[Connection], None]`
 
-   :param configure: A callback to configure a connection after creation.
-                     Useful, for instance, to configure its adapters. If the
-                     connection is used to run internal queries (to inspect the
-                     database) make sure to close an eventual transaction
-                     before leaving the function.
-   :type configure: `Callable[[Connection], None]`
-
    :param reset: A callback to reset a function after it has been returned to
                  the pool. The connection is guaranteed to be passed to the
                  `!reset()` function in "idle" state (no transaction). When
diff --git a/psycopg_pool/psycopg_pool/null_pool.py b/psycopg_pool/psycopg_pool/null_pool.py
index 7f67c1cf1..bf062d0fd 100644
--- a/psycopg_pool/psycopg_pool/null_pool.py
+++ b/psycopg_pool/psycopg_pool/null_pool.py
@@ -32,13 +32,13 @@ class NullConnectionPool(_BaseNullConnectionPool, ConnectionPool[CT]):
         self: NullConnectionPool[Connection[TupleRow]],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        check: Optional[ConnectionCB[CT]] = ...,
-        configure: Optional[ConnectionCB[CT]] = ...,
-        reset: Optional[ConnectionCB[CT]] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[ConnectionCB[CT]] = ...,
+        check: Optional[ConnectionCB[CT]] = ...,
+        reset: Optional[ConnectionCB[CT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -55,14 +55,14 @@ class NullConnectionPool(_BaseNullConnectionPool, ConnectionPool[CT]):
         self: NullConnectionPool[CT],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        connection_class: Type[CT],
-        check: Optional[ConnectionCB[CT]] = ...,
-        configure: Optional[ConnectionCB[CT]] = ...,
-        reset: Optional[ConnectionCB[CT]] = ...,
+        connection_class: Type[CT] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[ConnectionCB[CT]] = ...,
+        check: Optional[ConnectionCB[CT]] = ...,
+        reset: Optional[ConnectionCB[CT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -78,14 +78,14 @@ class NullConnectionPool(_BaseNullConnectionPool, ConnectionPool[CT]):
         self,
         conninfo: str = "",
         *,
-        open: bool | None = None,
         connection_class: Type[CT] = cast(Type[CT], Connection),
-        check: Optional[ConnectionCB[CT]] = None,
-        configure: Optional[ConnectionCB[CT]] = None,
-        reset: Optional[ConnectionCB[CT]] = None,
         kwargs: Optional[Dict[str, Any]] = None,
         min_size: int = 0,
         max_size: Optional[int] = None,
+        open: bool | None = None,
+        configure: Optional[ConnectionCB[CT]] = None,
+        check: Optional[ConnectionCB[CT]] = None,
+        reset: Optional[ConnectionCB[CT]] = None,
         name: Optional[str] = None,
         timeout: float = 30.0,
         max_waiting: int = 0,
diff --git a/psycopg_pool/psycopg_pool/null_pool_async.py b/psycopg_pool/psycopg_pool/null_pool_async.py
index 51bde7d52..2528ff33f 100644
--- a/psycopg_pool/psycopg_pool/null_pool_async.py
+++ b/psycopg_pool/psycopg_pool/null_pool_async.py
@@ -29,13 +29,13 @@ class AsyncNullConnectionPool(_BaseNullConnectionPool, AsyncConnectionPool[ACT])
         self: AsyncNullConnectionPool[AsyncConnection[TupleRow]],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        check: Optional[AsyncConnectionCB[ACT]] = ...,
-        configure: Optional[AsyncConnectionCB[ACT]] = ...,
-        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[AsyncConnectionCB[ACT]] = ...,
+        check: Optional[AsyncConnectionCB[ACT]] = ...,
+        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -52,14 +52,14 @@ class AsyncNullConnectionPool(_BaseNullConnectionPool, AsyncConnectionPool[ACT])
         self: AsyncNullConnectionPool[ACT],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        connection_class: Type[ACT],
-        check: Optional[AsyncConnectionCB[ACT]] = ...,
-        configure: Optional[AsyncConnectionCB[ACT]] = ...,
-        reset: Optional[AsyncConnectionCB[ACT]] = ...,
+        connection_class: Type[ACT] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[AsyncConnectionCB[ACT]] = ...,
+        check: Optional[AsyncConnectionCB[ACT]] = ...,
+        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -75,14 +75,14 @@ class AsyncNullConnectionPool(_BaseNullConnectionPool, AsyncConnectionPool[ACT])
         self,
         conninfo: str = "",
         *,
-        open: bool | None = None,
         connection_class: Type[ACT] = cast(Type[ACT], AsyncConnection),
-        check: Optional[AsyncConnectionCB[ACT]] = None,
-        configure: Optional[AsyncConnectionCB[ACT]] = None,
-        reset: Optional[AsyncConnectionCB[ACT]] = None,
         kwargs: Optional[Dict[str, Any]] = None,
         min_size: int = 0,  # Note: min_size default value changed to 0.
         max_size: Optional[int] = None,
+        open: bool | None = None,
+        configure: Optional[AsyncConnectionCB[ACT]] = None,
+        check: Optional[AsyncConnectionCB[ACT]] = None,
+        reset: Optional[AsyncConnectionCB[ACT]] = None,
         name: Optional[str] = None,
         timeout: float = 30.0,
         max_waiting: int = 0,
diff --git a/psycopg_pool/psycopg_pool/pool.py b/psycopg_pool/psycopg_pool/pool.py
index 4a7ce0dfd..288473fc0 100644
--- a/psycopg_pool/psycopg_pool/pool.py
+++ b/psycopg_pool/psycopg_pool/pool.py
@@ -45,13 +45,13 @@ class ConnectionPool(Generic[CT], BasePool):
         self: ConnectionPool[Connection[TupleRow]],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        check: Optional[ConnectionCB[CT]] = ...,
-        configure: Optional[ConnectionCB[CT]] = ...,
-        reset: Optional[ConnectionCB[CT]] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[ConnectionCB[CT]] = ...,
+        check: Optional[ConnectionCB[CT]] = ...,
+        reset: Optional[ConnectionCB[CT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -68,14 +68,14 @@ class ConnectionPool(Generic[CT], BasePool):
         self: ConnectionPool[CT],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        connection_class: Type[CT],
-        check: Optional[ConnectionCB[CT]] = ...,
-        configure: Optional[ConnectionCB[CT]] = ...,
-        reset: Optional[ConnectionCB[CT]] = ...,
+        connection_class: Type[CT] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[ConnectionCB[CT]] = ...,
+        check: Optional[ConnectionCB[CT]] = ...,
+        reset: Optional[ConnectionCB[CT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -91,14 +91,14 @@ class ConnectionPool(Generic[CT], BasePool):
         self,
         conninfo: str = "",
         *,
-        open: bool | None = None,
         connection_class: Type[CT] = cast(Type[CT], Connection),
-        check: Optional[ConnectionCB[CT]] = None,
-        configure: Optional[ConnectionCB[CT]] = None,
-        reset: Optional[ConnectionCB[CT]] = None,
         kwargs: Optional[Dict[str, Any]] = None,
         min_size: int = 4,
         max_size: Optional[int] = None,
+        open: bool | None = None,
+        configure: Optional[ConnectionCB[CT]] = None,
+        check: Optional[ConnectionCB[CT]] = None,
+        reset: Optional[ConnectionCB[CT]] = None,
         name: Optional[str] = None,
         timeout: float = 30.0,
         max_waiting: int = 0,
diff --git a/psycopg_pool/psycopg_pool/pool_async.py b/psycopg_pool/psycopg_pool/pool_async.py
index 67220d10f..25cec3f95 100644
--- a/psycopg_pool/psycopg_pool/pool_async.py
+++ b/psycopg_pool/psycopg_pool/pool_async.py
@@ -44,13 +44,13 @@ class AsyncConnectionPool(Generic[ACT], BasePool):
         self: AsyncConnectionPool[AsyncConnection[TupleRow]],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        check: Optional[AsyncConnectionCB[ACT]] = ...,
-        configure: Optional[AsyncConnectionCB[ACT]] = ...,
-        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[AsyncConnectionCB[ACT]] = ...,
+        check: Optional[AsyncConnectionCB[ACT]] = ...,
+        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -67,14 +67,14 @@ class AsyncConnectionPool(Generic[ACT], BasePool):
         self: AsyncConnectionPool[ACT],
         conninfo: str = "",
         *,
-        open: bool | None = ...,
-        connection_class: Type[ACT],
-        check: Optional[AsyncConnectionCB[ACT]] = ...,
-        configure: Optional[AsyncConnectionCB[ACT]] = ...,
-        reset: Optional[AsyncConnectionCB[ACT]] = ...,
+        connection_class: Type[ACT] = ...,
         kwargs: Optional[Dict[str, Any]] = ...,
         min_size: int = ...,
         max_size: Optional[int] = ...,
+        open: bool | None = ...,
+        configure: Optional[AsyncConnectionCB[ACT]] = ...,
+        check: Optional[AsyncConnectionCB[ACT]] = ...,
+        reset: Optional[AsyncConnectionCB[ACT]] = ...,
         name: Optional[str] = ...,
         timeout: float = ...,
         max_waiting: int = ...,
@@ -90,14 +90,14 @@ class AsyncConnectionPool(Generic[ACT], BasePool):
         self,
         conninfo: str = "",
         *,
-        open: bool | None = None,
         connection_class: Type[ACT] = cast(Type[ACT], AsyncConnection),
-        check: Optional[AsyncConnectionCB[ACT]] = None,
-        configure: Optional[AsyncConnectionCB[ACT]] = None,
-        reset: Optional[AsyncConnectionCB[ACT]] = None,
         kwargs: Optional[Dict[str, Any]] = None,
         min_size: int = 4,
         max_size: Optional[int] = None,
+        open: bool | None = None,
+        configure: Optional[AsyncConnectionCB[ACT]] = None,
+        check: Optional[AsyncConnectionCB[ACT]] = None,
+        reset: Optional[AsyncConnectionCB[ACT]] = None,
         name: Optional[str] = None,
         timeout: float = 30.0,
         max_waiting: int = 0,