xml adaptation example and more about types registry

diff --git a/docs/advanced/adapt.rst b/docs/advanced/adapt.rst
index 48fa518c844b26b7db92b44141621a6dcca671bd..eaa0b0d9e84eb117283ce53372a08ffa1c6fb783 100644 (file)
--- a/docs/advanced/adapt.rst
+++ b/docs/advanced/adapt.rst
@@ -53,6 +53,43 @@ returned.
     when a query is executed.
 
 
+Writing a custom loader: XML
+----------------------------
+
+Psycopg doesn't provide a loader for the XML data type because there are just
+too many ways of handling it in Python. Creating a loader to parse the
+`PostgreSQL xml type`__ to `~xml.etree.ElementTree` is very simple, using the
+`psycopg.adapt.Loader` base class.
+
+Note that it is possible to use a `~psycopg.types.TypesRegistry`, exposed by
+any `~psycopg.abc.AdaptContext`, to obtain information on builtin types, or
+extension types if they have been registered::
+
+    >>> import xml.etree.ElementTree as ET
+    >>> from psycopg.adapt import Loader
+
+    >>> # Create a class setting the `format` and implementing the `load()` method.
+    >>> class XmlLoader(Loader):
+    ...     format = psycopg.pq.Format.TEXT
+    ...     def load(self, data):
+    ...         return ET.fromstring(data)
+
+    >>> # Register the loader on the adapters of a context.
+    >>> conn.adapters.register_loader(conn.adapters.types["xml"].oid, XmlLoader)
+
+    >>> # Now just query the database returning XML data.
+    >>> cur = conn.execute(
+    ...     """select XMLPARSE (DOCUMENT '
+    ...            <?xml version="1.0"?>
+    ...            <book><title>Manual</title><chapter>...</chapter></book>')
+    ...     """)
+
+    >>> cur.fetchone()[0]
+    <Element 'book' at 0x7ffb55142ef0>
+
+.. __: https://www.postgresql.org/docs/current/datatype-xml.html
+
+
 Example: PostgreSQL numeric to Python float
 -------------------------------------------
 

diff --git a/docs/api/module.rst b/docs/api/module.rst
index a9c98e31aa979fe1ac8b4aab2fe72623a8dfa649..653c349be84fc7ac12d333cc4c96777cb3e26e28 100644 (file)
--- a/docs/api/module.rst
+++ b/docs/api/module.rst
@@ -44,8 +44,16 @@ exceptions, mapping to the database error states (see
 
 .. data:: adapters
 
-   The global, default adapters map establishing how Python and PostgreSQL
-   types are converted into each other. This map is used as template when new
-   connections are created, using `psycopg.connect()`.
+   The default adapters map establishing how Python and PostgreSQL types are
+   converted into each other.
+
+   This map is used as template when new connections are created, using
+   `psycopg.connect()`. Its `~psycopg.adapt.AdaptersMap.types` attribute is a
+   `~psycopg.types.TypesRegistry` containing information about every
+   PostgreSQL builtin type, useful for adaptation customisation (see
+   :ref:`adaptation`)::
+
+       >>> psycopg.adapters.types["int4"]
+       <TypeInfo: int4 (oid: 23, array oid: 1007)>
 
    :type: `~psycopg.adapt.AdaptersMap`

diff --git a/docs/api/types.rst b/docs/api/types.rst
index 6414e71c8a71bda1c45ddca3712a0b962c1d58aa..f9c653a4f4aedd3b9cc0dbc329d6262a7e3caa1a 100644 (file)
--- a/docs/api/types.rst
+++ b/docs/api/types.rst
@@ -98,6 +98,13 @@ its `~psycopg.adapt.AdaptersMap.types` attribute.
 
 .. autoclass:: TypesRegistry
 
+   `!TypeRegistry` instances are typically exposed by
+   `~psycopg.adapt.AdaptersMap` objects in adapt contexts such as
+   `~psycopg.Connection` or `~psycopg.Cursor` (e.g. `!conn.adapters.types`).
+
+   The global registry, from which the others inherit from, is available as
+   `psycopg.adapters`\ ``.types``.
+
 
 .. _numeric-wrappers: