From: Daniele Varrazzo Date: Mon, 3 Jan 2022 14:10:54 +0000 (+0100) Subject: Add API docs for pool open method/param. X-Git-Tag: pool-3.1~45^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=929d304538cc8273f495be8713351c320dfa3e4c;p=thirdparty%2Fpsycopg.git Add API docs for pool open method/param. --- diff --git a/docs/api/pool.rst b/docs/api/pool.rst index 66b6de2ab..0ae7244b7 100644 --- a/docs/api/pool.rst +++ b/docs/api/pool.rst @@ -31,7 +31,7 @@ instance from the rest of the code (especially the The `!ConnectionPool` class --------------------------- -.. autoclass:: ConnectionPool(conninfo, *, **arguments) +.. autoclass:: ConnectionPool This class implements a connection pool serving `~psycopg.Connection` instances (or subclasses). The constructor has *alot* of arguments, but @@ -67,6 +67,12 @@ The `!ConnectionPool` class 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 @@ -119,7 +125,7 @@ The `!ConnectionPool` class the connection attempt is aborted and the *reconnect_failed* callback invoked. :type reconnect_timeout: `!float`, default: 5 minutes - + :param reconnect_failed: Callback invoked if an attempt to create a new connection fails for more than *reconnect_timeout* seconds. The user may decide, for instance, to @@ -135,29 +141,41 @@ The `!ConnectionPool` class they are returned to the pool. :type num_workers: `!int`, default: 3 + .. versionchanged:: psycopg_pool 3.1 + + Added `!open` parameter to init method. + + .. note:: In a future version, the deafult value for the `!open` parameter + might be changed to `!false`. If you rely on this behaviour (e.g. if + you don't use the pool as a context manager) you might want to specify + this parameter explicitly. + .. automethod:: wait .. automethod:: connection - + .. code:: python with my_pool.connection() as conn: conn.execute(...) # the connection is now back in the pool - + .. automethod:: open + .. versionadded:: psycopg_pool 3.1 + + .. automethod:: close - .. note:: - - The pool can be used as context manager too, in which case it will - be closed at the end of the block: + .. note:: - .. code:: python + The pool can be also used as a context manager, in which case it will + be opened (if necessary) on entering the block and closed on exiting it: - with ConnectionPool(...) as pool: - # code using the pool + .. code:: python + + with ConnectionPool(...) as pool: + # code using the pool .. attribute:: name :type: str @@ -170,7 +188,7 @@ The `!ConnectionPool` class The current minimum and maximum size of the pool. Use `resize()` to change them at runtime. - + .. automethod:: resize .. automethod:: check .. automethod:: get_stats @@ -183,6 +201,7 @@ The `!ConnectionPool` class .. automethod:: getconn .. automethod:: putconn + Pool exceptions --------------- @@ -210,7 +229,7 @@ so in the *connection_class* parameter. Only the function with different signature from `!ConnectionPool` are listed here. -.. autoclass:: AsyncConnectionPool(conninfo, *, **arguments) +.. autoclass:: AsyncConnectionPool All the other parameters are the same. @@ -227,27 +246,28 @@ listed here. .. automethod:: wait .. automethod:: connection - + .. code:: python async with my_pool.connection() as conn: await conn.execute(...) # the connection is now back in the pool - + .. automethod:: open .. automethod:: close - .. note:: - - The pool can be used as context manager too, in which case it will - be closed at the end of the block: + .. note:: - .. code:: python + The pool can be also used as an async context manager, in which case it + will be opened (if necessary) on entering the block and closed on + exiting it: + + .. code:: python - async with AsyncConnectionPool(...) as pool: - # code using the pool + async with AsyncConnectionPool(...) as pool: + # code using the pool .. automethod:: resize .. automethod:: check diff --git a/docs/news_pool.rst b/docs/news_pool.rst index 08a1b70e0..0a6b2055b 100644 --- a/docs/news_pool.rst +++ b/docs/news_pool.rst @@ -7,16 +7,18 @@ ``psycopg_pool`` release notes ============================== -Current release +Future releases --------------- -psycopg_pool 3.1.0 -^^^^^^^^^^^^^^^^^^ +psycopg_pool 3.1.0 (unreleased) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Add `ConnectionPool.open()` and `!open` parameter to the pool init + (:ticket:`#151`). -- Add `ConnectionPool.open()` and `AsyncConnectionPool.open()` - (:ticket:`#155`). -- Raise an `~psycopg.OperationalError` when trying to re-open a closed pool - (:ticket:`#155`). + +Current release +--------------- psycopg_pool 3.0.2 ^^^^^^^^^^^^^^^^^^ diff --git a/psycopg_pool/psycopg_pool/pool.py b/psycopg_pool/psycopg_pool/pool.py index 98112daa7..693108297 100644 --- a/psycopg_pool/psycopg_pool/pool.py +++ b/psycopg_pool/psycopg_pool/pool.py @@ -111,7 +111,6 @@ class ConnectionPool(BasePool[Connection[Any]]): :ref:`connection context behaviour ` (commit/rollback the transaction in case of success/error). If the connection is no more in working state replace it with a new one. - """ conn = self.getconn(timeout=timeout) t0 = monotonic() @@ -226,9 +225,11 @@ class ConnectionPool(BasePool[Connection[Any]]): self._return_connection(conn) def open(self) -> None: - """Open the pool by starting worker threads. + """Open the pool by starting connecting and and accepting clients. - No-op if the pool is already opened. + The method is no-op if the pool is already opened (because the method + was already called, or because the pool context was entered, or because + the pool was initialized with ``open=true``. """ with self._lock: if not self._closed: @@ -273,7 +274,7 @@ class ConnectionPool(BasePool[Connection[Any]]): def close(self, timeout: float = 5.0) -> None: """Close the pool and make it unavailable to new clients. - All the waiting and future client will fail to acquire a connection + All the waiting and future clients will fail to acquire a connection with a `PoolClosed` exception. Currently used connections will not be closed until returned to the pool.