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 949a5224a9ef3657f8b953597383cef507e3e590..76aed2b7db7c5e59c3e1a9c80c1d2e652b46f3e4 100644 (file)
--- 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 7f67c1cf11ecaa16e0d0392ca28adadcf2f45c7b..bf062d0fd14d71fbc3b6c018afc86cf36f82dd6e 100644 (file)
--- 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 51bde7d52da90477a50a1f24eaa1c280b7d37881..2528ff33fa659712ae1331a840783bd6219fd1e7 100644 (file)
--- 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 4a7ce0dfda94f4b8ce56400633c20cf8ae2aa13b..288473fc06ba75debe81caf85b6b944fe59dc9ee 100644 (file)
--- 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 67220d10fbf02ec147228f3621f1a084f5742d6d..25cec3f9544e7a221946271163e03040bdc07a44 100644 (file)
--- 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,