From: Daniele Varrazzo Date: Wed, 22 Sep 2021 13:55:19 +0000 (+0200) Subject: Specify better that registering adapters only affects new object X-Git-Tag: 3.0~68 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cda37b6cc255451f0197a1a8989cc4ebf1731ada;p=thirdparty%2Fpsycopg.git 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 5f28c57a2..5d40e0c78 100644 --- 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 260ccd738..03c8ae6cc 100644 --- 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 4fdcc9c0c..a2a9681e4 100644 --- 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 c80111875..eb966c75e 100644 --- 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 2980994a5..80129123c 100644 --- 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 59fa04dd3..c8f1ba516 100644 --- 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 e17fbbde6..12d5bcb0e 100644 --- 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()