From: Abhishek-Rath (@Abhishek-Rath) <noreply+Abhishek-Rath@github.com>
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
Subject: [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
Date: Sun, 08 Nov 2026 17:17:05 +0000
Message-ID: <gh-psycopg-psycopg-1487@github.com> (raw)
Close #1135.
As discussed in the issue, this collects the documentation of the
`psycopg.types.*` objects in the single `api/types.rst` page, with one
section per submodule.
**Moved** from the conceptual pages to `api/types.rst` (the conceptual
pages keep their explanations and examples, and their existing
cross-references now point to the API page):
- `range`: `Range`, `RangeInfo`, `register_range()` (from `basic/pgtypes.rst`)
- `multirange`: `Multirange`, `MultirangeInfo`, `register_multirange()` (from `basic/pgtypes.rst`)
- `composite`: `CompositeInfo`, `register_composite()` (from `basic/pgtypes.rst`)
- `hstore`: `register_hstore()` (from `basic/pgtypes.rst`)
- `shapely`: `register_shapely()` (from `basic/pgtypes.rst`)
- `enum`: `EnumInfo`, `register_enum()` (from `basic/adapt.rst`)
**Added** documentation for the numeric wrappers `Int2`, `Int4`, `Int8`,
`IntNumeric`, `Float4`, `Float8`, `Oid` (`psycopg.types.numeric`), which
were not documented anywhere.
**Also fixed** a broken link in the moved text:
`collection.namedtuple` → `collections.namedtuple`.
The docs build has no new warnings. One commit per module, to make
review easier; happy to squash if preferred.
Questions:
- Should I add a link to the numeric wrappers from the warning in
"Numbers adaptation" (`basic/adapt.rst`)?
- Is an entry in `docs/news.rst` needed for a docs-only change?
inline patch 1: docs/api/types.rst, docs/basic/adapt.rst, docs/basic/pgtypes.rst (+247/-163 lines) download inline-1.patchdiff --git a/docs/api/types.rst b/docs/api/types.rstindex f04659e8c..6fc827abf 100644--- a/docs/api/types.rst+++ b/docs/api/types.rst@@ -166,3 +166,250 @@ object. Otherwise use the function specified by `set_json_dumps()`.
.. autofunction:: set_json_dumps
.. autofunction:: set_json_loads
+++.. _numeric-wrappers:++Numeric wrappers+-----------------++.. currentmodule:: psycopg.types.numeric++Wrappers to force a Python number to be dumped as a specific PostgreSQL+type, overriding the automatic choice described in :ref:`adapt-numbers`.++.. code:: python++ >>> from psycopg.types.numeric import Int8+ >>> conn.execute("SELECT pg_typeof(%s)", [Int8(1)]).fetchone()[0]+ 'bigint'++.. autoclass:: Int2+.. autoclass:: Int4+.. autoclass:: Int8+.. autoclass:: IntNumeric+.. autoclass:: Float4+.. autoclass:: Float8+.. autoclass:: Oid+++.. _range-api:++Range adapters+--------------++See :ref:`adapt-range` for details.++.. currentmodule:: psycopg.types.range++.. autoclass:: Range++ This Python type is only used to pass and retrieve range values to and+ from PostgreSQL and doesn't attempt to replicate the PostgreSQL range+ features: it doesn't perform normalization and doesn't implement all the+ operators__ supported by the database.++ PostgreSQL will perform normalisation on `!Range` objects used as query+ parameters, so, when they are fetched back, they will be found in the+ normal form (for instance ranges on integers will have `[)` bounds).++ .. __: https://www.postgresql.org/docs/current/static/functions-range.html#RANGE-OPERATORS-TABLE++ `!Range` objects are immutable, hashable, and support the `!in` operator+ (checking if an element is within the range). They can be tested for+ equivalence. Empty ranges evaluate to `!False` in a boolean context,+ nonempty ones evaluate to `!True`.++ `!Range` objects have the following attributes:++ .. autoattribute:: isempty+ .. autoattribute:: lower+ .. autoattribute:: upper+ .. autoattribute:: lower_inc+ .. autoattribute:: upper_inc+ .. autoattribute:: lower_inf+ .. autoattribute:: upper_inf++.. autoclass:: RangeInfo++ `!RangeInfo` is a `~psycopg.types.TypeInfo` subclass: check its+ documentation for generic details, especially the+ `~psycopg.types.TypeInfo.fetch()` method.++.. autofunction:: register_range+++.. _multirange-api:++Multirange adapters+-------------------++See :ref:`adapt-multirange` for details.++.. currentmodule:: psycopg.types.multirange++.. autoclass:: Multirange++ This Python type is only used to pass and retrieve multirange values to+ and from PostgreSQL and doesn't attempt to replicate the PostgreSQL+ multirange features: overlapping items are not merged, empty ranges are+ not discarded, the items are not ordered, the behaviour of `multirange+ operators`__ is not replicated in Python.++ PostgreSQL will perform normalisation on `!Multirange` objects used as+ query parameters, so, when they are fetched back, they will be found+ ordered, with overlapping ranges merged, etc.++ .. __: https://www.postgresql.org/docs/current/static/functions-range.html#MULTIRANGE-OPERATORS-TABLE++ `!Multirange` objects are a `~collections.abc.MutableSequence` and are+ totally ordered: they behave pretty much like a list of `!Range`. Like+ Range, they are `~typing.Generic` on the subtype of their range, so you+ can declare a variable to be `!Multirange[date]` and mypy will complain if+ you try to add it a `Range[Decimal]`.++.. autoclass:: MultirangeInfo++ `!MultirangeInfo` is a `~psycopg.types.TypeInfo` subclass: check its+ documentation for general details, especially the+ `~psycopg.types.TypeInfo.fetch()` method.++.. autofunction:: register_multirange+++.. _composite-api:++Composite adapters+------------------++See :ref:`adapt-composite` for details.++.. currentmodule:: psycopg.types.composite++.. autoclass:: CompositeInfo++ `!CompositeInfo` is a `~psycopg.types.TypeInfo` subclass: check its+ documentation for the general usage, especially the+ `~psycopg.types.TypeInfo.fetch()` method.++ .. attribute:: field_names+ :type: tuple[str, ...]++ Tuple containing the field names of the composite type.++ .. attribute:: field_types+ :type: tuple[int, ...]++ Tuple containing the field OIDs of the composite type.++ .. attribute:: python_type+ :type: Callable | None++ After `register_composite()` is called, it will contain the Python type+ adapting the registered composite.++.. autofunction:: register_composite++ After registering the `CompositeInfo`, fetching data of the registered+ composite type will invoke `!factory` to create corresponding Python+ objects. If no factory is specified, Psycopg will generate a+ `~collections.namedtuple` with the same fields of the composite type, and+ use it to return fetched data. The factory will be made available on+ `!info.`\ `~CompositeInfo.python_type`.++ If the `!factory` is a type (and not a generic callable) then dumpers for+ such type are created and registered too, so that passing objects of that+ type to a query will adapt them to the registered composite type. This+ assumes that the `!factory` type is a sequence; if this is not the case you+ can specify the `!make_sequence` parameter: a function taking the object to+ dump and the composite info and returning a sequence of values. See+ :ref:`composite-non-sequence`.++ The `!factory` callable will be called with the sequence of value from the+ composite. If passing the sequence of positional arguments is not suitable+ for the `!factory` type you can specify the `!make_object` parameter: a+ function taking the sequence of composite values and the type info, and+ which should return a new instance of the object to load. See+ :ref:`composite-non-sequence`.++ .. versionadded:: 3.3+ the `!make_object` and `!make_sequence` parameters.+++.. _hstore-api:++Hstore adapters+---------------++See :ref:`adapt-hstore` for details.++.. currentmodule:: psycopg.types.hstore++.. autofunction:: register_hstore+++.. _shapely-api:++Shapely adapters+----------------++See :ref:`adapt-shapely` for details.++.. currentmodule:: psycopg.types.shapely++.. function:: register_shapely++ Register Shapely dumper and loaders.++ After invoking this function on an adapter, the queries retrieving+ PostGIS geometry objects will return Shapely's shape object instances+ both in text and binary mode.++ Similarly, shape objects can be sent to the database.++ This requires the Shapely library to be installed.++ :param info: The object with the information about the geometry 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.+++.. _enum-api:++Enum adapters+-------------++See :ref:`adapt-enum` for details.++.. currentmodule:: psycopg.types.enum++.. autoclass:: EnumInfo++ `!EnumInfo` is a subclass of `~psycopg.types.TypeInfo`: refer to the+ latter's documentation for generic usage, especially the+ `~psycopg.types.TypeInfo.fetch()` method.++ .. attribute:: labels++ After `~psycopg.types.TypeInfo.fetch()`, it contains the labels defined+ in the PostgreSQL enum type.++ .. attribute:: enum++ After `register_enum()` is called, it will contain the Python type+ mapping to the registered enum.++.. autofunction:: register_enum++ After registering, fetching data of the registered enum will cast+ PostgreSQL enum labels into corresponding Python enum members.++ If no `!enum` is specified, a new `Enum` is created based on+ PostgreSQL enum labels.diff --git a/docs/basic/adapt.rst b/docs/basic/adapt.rstindex b0b5342c8..8af2e490c 100644--- a/docs/basic/adapt.rst+++ b/docs/basic/adapt.rst@@ -531,30 +531,6 @@ and registered enums is different.
- The registered PostgreSQL enum is loaded back as the registered Python
enum members.
-.. autoclass:: psycopg.types.enum.EnumInfo-- `!EnumInfo` is a subclass of `~psycopg.types.TypeInfo`: refer to the- latter's documentation for generic usage, especially the- `~psycopg.types.TypeInfo.fetch()` method.-- .. attribute:: labels-- After `~psycopg.types.TypeInfo.fetch()`, it contains the labels defined- in the PostgreSQL enum type.-- .. attribute:: enum-- After `register_enum()` is called, it will contain the Python type- mapping to the registered enum.--.. autofunction:: psycopg.types.enum.register_enum-- After registering, fetching data of the registered enum will cast- PostgreSQL enum labels into corresponding Python enum members.-- If no `!enum` is specified, a new `Enum` is created based on- PostgreSQL enum labels.-
Example::
>>> from enum import Enum, auto
diff --git a/docs/basic/pgtypes.rst b/docs/basic/pgtypes.rstindex b796c87ca..9390e0461 100644--- a/docs/basic/pgtypes.rst+++ b/docs/basic/pgtypes.rst@@ -35,56 +35,6 @@ Before using a composite type it is necessary to get information about it
using the `~psycopg.types.composite.CompositeInfo` class and to register it
using `~psycopg.types.composite.register_composite()`.
-.. autoclass:: psycopg.types.composite.CompositeInfo-- `!CompositeInfo` is a `~psycopg.types.TypeInfo` subclass: check its- documentation for the general usage, especially the- `~psycopg.types.TypeInfo.fetch()` method.-- .. attribute:: field_names- :type: tuple[str, ...]-- Tuple containing the field names of the composite type.-- .. attribute:: field_types- :type: tuple[int, ...]-- Tuple containing the field OIDs of the composite type.-- .. attribute:: python_type- :type: Callable | None-- After `register_composite()` is called, it will contain the Python type- adapting the registered composite.--.. autofunction:: psycopg.types.composite.register_composite-- After registering the `CompositeInfo`, fetching data of the registered- composite type will invoke `!factory` to create corresponding Python- objects. If no factory is specified, Psycopg will generate a- `~collection.namedtuple` with the same fields of the composite type, and- use it to return fetched data. The factory will be made available on- `!info.`\ `~CompositeInfo.python_type`.-- If the `!factory` is a type (and not a generic callable) then dumpers for- such type are created and registered too, so that passing objects of that- type to a query will adapt them to the registered composite type. This- assumes that the `!factory` type is a sequence; if this is not the case you- can specify the `!make_sequence` parameter: a function taking the object to- dump and the composite info and returning a sequence of values. See- :ref:`composite-non-sequence`.-- The `!factory` callable will be called with the sequence of value from the- composite. If passing the sequence of positional arguments is not suitable- for the `!factory` type you can specify the `!make_object` parameter: a- function taking the sequence of composite values and the type info, and- which should return a new instance of the object to load. See- :ref:`composite-non-sequence`.-- .. versionadded:: 3.3- the `!make_object` and `!make_sequence` parameters.--
.. _composite-sequence:
Example: Python sequence
@@ -193,34 +143,6 @@ All the PostgreSQL range types are loaded as the `~psycopg.types.range.Range`
Python type, which is a `~typing.Generic` type and can hold bounds of
different types.
-.. autoclass:: psycopg.types.range.Range-- This Python type is only used to pass and retrieve range values to and- from PostgreSQL and doesn't attempt to replicate the PostgreSQL range- features: it doesn't perform normalization and doesn't implement all the- operators__ supported by the database.-- PostgreSQL will perform normalisation on `!Range` objects used as query- parameters, so, when they are fetched back, they will be found in the- normal form (for instance ranges on integers will have `[)` bounds).-- .. __: https://www.postgresql.org/docs/current/static/functions-range.html#RANGE-OPERATORS-TABLE-- `!Range` objects are immutable, hashable, and support the `!in` operator- (checking if an element is within the range). They can be tested for- equivalence. Empty ranges evaluate to `!False` in a boolean context,- nonempty ones evaluate to `!True`.-- `!Range` objects have the following attributes:-- .. autoattribute:: isempty- .. autoattribute:: lower- .. autoattribute:: upper- .. autoattribute:: lower_inc- .. autoattribute:: upper_inc- .. autoattribute:: lower_inf- .. autoattribute:: upper_inf-
The built-in range objects are adapted automatically: if a `!Range` objects
contains `~datetime.date` bounds, it is dumped using the :sql:`daterange` OID,
and of course :sql:`daterange` values are loaded back as `!Range[date]`.
@@ -229,14 +151,6 @@ If you create your own range type you can use `~psycopg.types.range.RangeInfo`
and `~psycopg.types.range.register_range()` to associate the range type with
its subtype and make it work like the builtin ones.
-.. autoclass:: psycopg.types.range.RangeInfo-- `!RangeInfo` is a `~psycopg.types.TypeInfo` subclass: check its- documentation for generic details, especially the- `~psycopg.types.TypeInfo.fetch()` method.--.. autofunction:: psycopg.types.range.register_range-
Example::
>>> from psycopg.types.range import Range, RangeInfo, register_range
@@ -270,26 +184,6 @@ All the PostgreSQL range types are loaded as the
`~psycopg.types.multirange.Multirange` Python type, which is a mutable
sequence of `~psycopg.types.range.Range` elements.
-.. autoclass:: psycopg.types.multirange.Multirange-- This Python type is only used to pass and retrieve multirange values to- and from PostgreSQL and doesn't attempt to replicate the PostgreSQL- multirange features: overlapping items are not merged, empty ranges are- not discarded, the items are not ordered, the behaviour of `multirange- operators`__ is not replicated in Python.-- PostgreSQL will perform normalisation on `!Multirange` objects used as- query parameters, so, when they are fetched back, they will be found- ordered, with overlapping ranges merged, etc.-- .. __: https://www.postgresql.org/docs/current/static/functions-range.html#MULTIRANGE-OPERATORS-TABLE-- `!Multirange` objects are a `~collections.abc.MutableSequence` and are- totally ordered: they behave pretty much like a list of `!Range`. Like- Range, they are `~typing.Generic` on the subtype of their range, so you- can declare a variable to be `!Multirange[date]` and mypy will complain if- you try to add it a `Range[Decimal]`.-
Like for `~psycopg.types.range.Range`, built-in multirange objects are adapted
automatically: if a `!Multirange` object contains `!Range` with
`~datetime.date` bounds, it is dumped using the :sql:`datemultirange` OID, and
@@ -300,14 +194,6 @@ If you have created your own range type you can use
`~psycopg.types.multirange.register_multirange()` to associate the resulting
multirange type with its subtype and make it work like the builtin ones.
-.. autoclass:: psycopg.types.multirange.MultirangeInfo-- `!MultirangeInfo` is a `~psycopg.types.TypeInfo` subclass: check its- documentation for general details, especially the- `~psycopg.types.TypeInfo.fetch()` method.--.. autofunction:: psycopg.types.multirange.register_multirange-
Example::
>>> from psycopg.types.multirange import \
@@ -363,8 +249,6 @@ resulting object can be passed to
|hstore| and parsing |hstore| back to `!dict`, in the context where the
adapter is registered.
-.. autofunction:: psycopg.types.hstore.register_hstore-
Example::
>>> from psycopg.types import TypeInfo
@@ -415,29 +299,6 @@ to configure dumping `shape`_ instances to :sql:`geometry` columns and parsing
:sql:`geometry` data back to `!shape` instances, in the context where the
adapters are registered.
-.. function:: psycopg.types.shapely.register_shapely-- Register Shapely dumper and loaders.-- After invoking this function on an adapter, the queries retrieving- PostGIS geometry objects will return Shapely's shape object instances- both in text and binary mode.-- Similarly, shape objects can be sent to the database.-- This requires the Shapely library to be installed.-- :param info: The object with the information about the geometry 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.-
Example::
>>> from psycopg.types import TypeInfo