From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 4 Oct 2021 12:46:27 +0000 (+0200)
Subject: Improve TypeInfo docs
X-Git-Tag: 3.0~31
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=90c9987d43d5b86cce9f5e42bc17aa35f01c4f4a;p=thirdparty%2Fpsycopg.git

Improve TypeInfo docs
---

diff --git a/docs/api/types.rst b/docs/api/types.rst
index 86b25ec80..b9a78a9d2 100644
--- a/docs/api/types.rst
+++ b/docs/api/types.rst
@@ -16,18 +16,23 @@ Types information
 -----------------
 
 The `TypeInfo` object describes simple information about a PostgreSQL data
-type, such as its name, oid and array oid. The class can be used to query a
-database for custom data types: this allows for instance to load automatically
-arrays of a custom type, once a loader for the base type has been registered.
+type, such as its name, oid and array oid. Subclasses may hold more
+information, for instance the components of a composite type.
+
+You can use `TypeInfo.fetch()` to query information from a database catalog,
+which is then used by helper functions, such as
+`~psycopg.types.hstore.register_hstore()`, to register adapters on types whose
+OID is not known upfront or to create more specialised adapters.
 
 The `!TypeInfo` object doesn't instruct Psycopg to convert a PostgreSQL type
 into a Python type: this is the role of a `~psycopg.abc.Loader`. However it
-can extend the behaviour of the adapters: if you create a loader for
-`!MyType`, using `TypeInfo` you will be able to manage seamlessly arrays of
-`!MyType` or ranges and composite types using it as a subtype.
+can extend the behaviour of other adapters: if you create a loader for
+`!MyType`, using the `TypeInfo` information, Psycopg will be able to manage
+seamlessly arrays of `!MyType` or ranges and composite types using `!MyType`
+as a subtype.
 
-.. seealso:: :ref:`adaptation` describes about how to convert from Python
-    types to PostgreSQL types and back.
+.. seealso:: :ref:`adaptation` describes how to convert from Python objects to
+    PostgreSQL types and back.
 
 .. code:: python
 
@@ -89,11 +94,12 @@ can extend the behaviour of the adapters: if you create a loader for
 
 
 For recursive types, Psycopg offers a few `!TypeInfo` subclasses which can be
-used to extract more complete information, for instance
-`~psycopg.types.composite.CompositeInfo` and `~psycopg.types.range.RangeInfo`.
+used to extract more complete information, such as
+`~psycopg.types.composite.CompositeInfo`, `~psycopg.types.range.RangeInfo`,
+`~psycopg.types.multirange.MultirangeInfo`.
 
 `!TypeInfo` objects are collected in `TypesRegistry` instances, which help type
-information lookup. Every `~psycopg.adapt.AdaptersMap` expose its type map on
+information lookup. Every `~psycopg.adapt.AdaptersMap` exposes its type map on
 its `~psycopg.adapt.AdaptersMap.types` attribute.
 
 .. autoclass:: TypesRegistry
@@ -126,6 +132,9 @@ its `~psycopg.adapt.AdaptersMap.types` attribute.
            >>> psycopg.adapters.types.get_oid("text[]")
            1009
 
+   .. automethod:: get_by_subtype
+
+
 .. _numeric-wrappers:
 
 Numeric wrappers
diff --git a/psycopg/psycopg/_typeinfo.py b/psycopg/psycopg/_typeinfo.py
index 11438b121..a9b6ac60f 100644
--- a/psycopg/psycopg/_typeinfo.py
+++ b/psycopg/psycopg/_typeinfo.py
@@ -407,9 +407,14 @@ class TypesRegistry:
         self, cls: Type[T], subtype: Union[int, str]
     ) -> Optional[T]:
         """
-        Return info about a TypeInfo subclass by its element name or oid
-
-        Return None if the element or its range are not found.
+        Return info about a `TypeInfo` subclass by its element name or oid.
+
+        :param cls: the subtype of `!TypeInfo` to look for. Currently
+            supported are `~psycopg.types.range.RangeInfo` and
+            `~psycopg.types.multirange.MultirangeInfo`.
+        :param subtype: The name or OID of the subtype of the element to look for.
+        :return: The `!TypeInfo` object of class *cls* whose subtype is
+            *subtype*. `!None` if the element or its range are not found.
         """
         try:
             info = self[subtype]