Document that the connection pool is in a separate package

diff --git a/docs/advanced/pool.rst b/docs/advanced/pool.rst
index ed232ac14abc5b0597934a73c66a4c63647e2b69..7d4ce441b5a437e8df017b753b9d0825c112f6f3 100644 (file)
--- a/docs/advanced/pool.rst
+++ b/docs/advanced/pool.rst
@@ -16,6 +16,11 @@ This page explains a few basic concepts of Psycopg connection pool's
 behaviour. Please refer to the `ConnectionPool` object API for details about
 the pool operations.
 
+.. note:: The connection pool objects are distributed in a package separate
+   from the main `psycopg` package: use ``pip install psycopg[pool]`` or ``pip
+   install psycopg_pool`` to make the `psycopg_pool` package available. See
+   :ref:`pool-installation`.
+
 
 Pool life cycle
 ---------------
@@ -27,6 +32,8 @@ however, and not the necessary one; in particular the connection pool acts as
 a context manager and can be closed automatically at the end of its ``with``
 block::
 
+    from psycopg_pool import ConnectionPool
+
     with ConnectionPool(conninfo, **kwargs) as my_pool:
         run_app(my_pool)
 

diff --git a/docs/api/pool.rst b/docs/api/pool.rst
index 5b1483ee7a1830ca91d8b07a6fda43d359262d0f..08eafea8ab2e8546ec1a708ab620e420016b1b99 100644 (file)
--- a/docs/api/pool.rst
+++ b/docs/api/pool.rst
@@ -1,5 +1,5 @@
-`pool` -- Connection pool implementations
-=========================================
+`!psycopg_pool` -- Connection pool implementations
+==================================================
 
 .. index::
     double: Connection; Pool
@@ -22,6 +22,10 @@ a global object exposed by a module in your application, and use the same
 instance from the rest of the code (especially the
 `~ConnectionPool.connection()` method.
 
+.. note:: The `!psycopg_pool` package is distributed separately from the main
+   `psycopg` package: use ``pip install psycopg[pool]`` or ``pip install
+   psycopg_pool`` to make it available. See :ref:`pool-installation`.
+
 
 The `!ConnectionPool` class
 ---------------------------

diff --git a/docs/basic/install.rst b/docs/basic/install.rst
index 6e13c4164d1297ba0ebef9cc6d8560873133cff3..a6f6ef1c3dfe841d3f404345870497ab161cebcf 100644 (file)
--- a/docs/basic/install.rst
+++ b/docs/basic/install.rst
@@ -141,6 +141,20 @@ If you are not able to fulfill this requirement please follow the `binary
 installation`_.
 
 
+.. _pool-installation:
+
+Installing the connection pool
+------------------------------
+
+The :ref:`Psycopg connection pools <connection-pools>` are distributed in a
+separate package from the `!psycopg` package itself, in order to allow a
+different release cycle.
+
+In order to use the pool you must install the ``pool`` extra, using ``pip
+install psycopg[pool]``, or install the `psycopg_pool` package separately,
+which would allow to specify the release to install more precisely.
+
+
 Handling dependencies
 ---------------------