Add API docs for pool open method/param.

diff --git a/docs/api/pool.rst b/docs/api/pool.rst
index 66b6de2abfa110ff91b089900e460a6141343544..0ae7244b7cb1b11a21f65419650dc7281d62fec9 100644 (file)
--- 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 08a1b70e0d201e96b7192a004366feef886a45f5..0a6b2055b3c1a9758f760c9ffa7d886d7e985d1a 100644 (file)
--- 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 98112daa72bc819791370d385ff4ae90190770c3..69310829751f31010f48102cd8d00e139d29a9b6 100644 (file)
--- 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 <with-connection>` (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.