Specify better that registering adapters only affects new object

It is unclear that registering adapters globally doesn't affect existing
connections, including the one used to fetch info... See
https://github.com/sqlalchemy/sqlalchemy/issues/6842#issuecomment-924425360
for instance.

diff --git a/docs/advanced/adapt.rst b/docs/advanced/adapt.rst
index 5f28c57a286a978444b261f94cd4c5f7e189c08c..5d40e0c78b65352db2f4298726e12f83fad3a54f 100644 (file)
--- a/docs/advanced/adapt.rst
+++ b/docs/advanced/adapt.rst
@@ -18,7 +18,7 @@ returned.
 
 - Adaptation configuration is performed by changing the
   `~psycopg.abc.AdaptContext.adapters` object of objects implementing the
-  `~psycopg.abc.AdaptContext` protocols, for instance `~psycopg.Connection`
+  `~psycopg.abc.AdaptContext` protocol, for instance `~psycopg.Connection`
   or `~psycopg.Cursor`.
 
 - Every context object derived from another context inherits its adapters
@@ -52,6 +52,12 @@ returned.
   - Dumpers and loaders are instantiated on demand by a `~Transformer` object
     when a query is executed.
 
+.. note::
+    Changing adapters in a context only affects that context and its children
+    objects created *afterwards*; the objects already created are not
+    affected. For instance, changing the global context will only change newly
+    created connections, not the ones already existing.
+
 
 .. _adapt-example-xml:
 

diff --git a/docs/basic/pgtypes.rst b/docs/basic/pgtypes.rst
index 260ccd738e59848fa0d6ddd1662f6e68e681b4be..03c8ae6cc1317cf6a30dc62eaa17100b5392cbae 100644 (file)
--- a/docs/basic/pgtypes.rst
+++ b/docs/basic/pgtypes.rst
@@ -184,7 +184,7 @@ Only dictionaries with string keys and values are supported. `!None` is also
 allowed as value but not as a key.
 
 In order to use the |hstore| data type it is necessary to load it in a
-database using 
+database using:
 
 .. code:: none
 

diff --git a/psycopg/psycopg/_adapters_map.py b/psycopg/psycopg/_adapters_map.py
index 4fdcc9c0ce15d492b7ee9ff6267834f2801f6a17..a2a9681e4b7931594e779b358c23324362e1fe45 100644 (file)
--- a/psycopg/psycopg/_adapters_map.py
+++ b/psycopg/psycopg/_adapters_map.py
@@ -39,17 +39,20 @@ class AdaptersMap:
     `~psycopg.Cursor` is created from a `~psycopg.Connection`), the parent's
     `!adapters` are used as template for the child's `!adapters`, so that every
     cursor created from the same connection use the connection's types
-    configuration, but separate connections have independent mappings. Once
-    created, `!AdaptersMap` are independent.
+    configuration, but separate connections have independent mappings.
+
+    Once created, `!AdaptersMap` are independent. This means that objects
+    already created are not affected if a wider scope (e.g. the global one) is
+    changed.
 
     The connections adapters are initialised using a global `!AdptersMap`
     template, exposed as `psycopg.adapters`: changing such mapping allows to
-    customise the type mapping for the entire application.
+    customise the type mapping for every connections created afterwards.
 
     The object can start empty or copy from another object of the same class.
     Copies are copy-on-write: if the maps are updated make a copy. This way
     extending e.g. global map by a connection or a connection map from a cursor
-    is cheap: a copy is made only on customisation.
+    is cheap: a copy is only made on customisation.
     """
 
     __module__ = "psycopg.adapt"

diff --git a/psycopg/psycopg/types/composite.py b/psycopg/psycopg/types/composite.py
index c8011187547208ba1ac4ea0237f487a96c6594cf..eb966c75e7beba79fea6ebbace4a55a7cf0afc9f 100644 (file)
--- a/psycopg/psycopg/types/composite.py
+++ b/psycopg/psycopg/types/composite.py
@@ -215,6 +215,13 @@ def register_composite(
         register it globally.
     :param factory: Callable to convert the sequence of attributes read from
         the composite into a Python object.
+
+    .. note::
+
+        Registering the adapters doesn't affect objects already created, even
+        if they are children of the registered context. For instance,
+        registering the adapter globally doesn't affect already existing
+        connections.
     """
 
     # A friendly error warning instead of an AttributeError in case fetch()

diff --git a/psycopg/psycopg/types/hstore.py b/psycopg/psycopg/types/hstore.py
index 2980994a5447861ffa5cf8b7aa23187a24aa6429..80129123c264fc3281986036789963b4e2c821c8 100644 (file)
--- a/psycopg/psycopg/types/hstore.py
+++ b/psycopg/psycopg/types/hstore.py
@@ -106,6 +106,13 @@ def register_hstore(
     :param info: The object with the information about the hstore type.
     :param context: The context where to register the adapters. If `!None`,
         register it globally.
+
+    .. note::
+
+        Registering the adapters doesn't affect objects already created, even
+        if they are children of the registered context. For instance,
+        registering the adapter globally doesn't affect already existing
+        connections.
     """
     # A friendly error warning instead of an AttributeError in case fetch()
     # failed and it wasn't noticed.

diff --git a/psycopg/psycopg/types/range.py b/psycopg/psycopg/types/range.py
index 59fa04dd35aa91dc341d723ff0d0415247790cb4..c8f1ba5161d1200a887df39a720e0e490e92d1dc 100644 (file)
--- a/psycopg/psycopg/types/range.py
+++ b/psycopg/psycopg/types/range.py
@@ -441,6 +441,13 @@ def register_range(
 
     Register loaders so that loading data of this type will result in a `Range`
     with bounds parsed as the right subtype.
+
+    .. note::
+
+        Registering the adapters doesn't affect objects already created, even
+        if they are children of the registered context. For instance,
+        registering the adapter globally doesn't affect already existing
+        connections.
     """
     # A friendly error warning instead of an AttributeError in case fetch()
     # failed and it wasn't noticed.

diff --git a/psycopg/psycopg/types/shapely.py b/psycopg/psycopg/types/shapely.py
index e17fbbde6856b466cba88bd658927a40eabdb15a..12d5bcb0ef930e66c380749855b5cd45d46b1532 100644 (file)
--- a/psycopg/psycopg/types/shapely.py
+++ b/psycopg/psycopg/types/shapely.py
@@ -68,6 +68,12 @@ def register_shapely(
     :param context: The context where to register the adapters. If `!None`,
         register it globally.
 
+    .. note::
+
+        Registering the adapters doesn't affect objects already created, even
+        if they are children of the registered context. For instance,
+        registering the adapter globally doesn't affect already existing
+        connections.
     """
 
     # A friendly error warning instead of an AttributeError in case fetch()