pg.ddx.io psycopg/psycopg GitHub issues and pull requests
help / color / mirror / Atom feed[psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
4+ messages / 2 participants
[nested] [flat]
* [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
@ 2026-11-08 17:17 "Abhishek-Rath (@Abhishek-Rath)" <noreply+Abhishek-Rath@github.com>
0 siblings, 0 replies; 4+ messages in thread
From: Abhishek-Rath (@Abhishek-Rath) @ 2026-11-08 17:17 UTC (permalink / raw)
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
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.patch
diff --git a/docs/api/types.rst b/docs/api/types.rst
index 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.rst
index 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.rst
index 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
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
@ 2026-11-17 13:49 "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: dvarrazzo (@dvarrazzo) @ 2026-11-17 13:49 UTC (permalink / raw)
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
Thank you for this work! I have rebased it and made a few small changes (added a link from the numeric adaptations to the wrapper, and fixed a few pre-existing errors).
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
@ 2026-11-17 13:50 "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: dvarrazzo (@dvarrazzo) @ 2026-11-17 13:50 UTC (permalink / raw)
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
@dvarrazzo merged this (commit cf390ed00b24).
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page
@ 2026-11-17 13:50 "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: dvarrazzo (@dvarrazzo) @ 2026-11-17 13:50 UTC (permalink / raw)
To: psycopg/psycopg <noreply+psycopg-psycopg@github.com>
@dvarrazzo closed this.
^ permalink raw [nested|flat] 4+ messages in thread
end of thread, other threads:[~2026-11-17 13:50 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-11-08 17:17 [psycopg/psycopg] PR #1487: docs: move psycopg.types objects documentation to the types API page "Abhishek-Rath (@Abhishek-Rath)" <noreply+Abhishek-Rath@github.com>
2026-11-17 13:49 ` "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
2026-11-17 13:50 ` "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
2026-11-17 13:50 ` "dvarrazzo (@dvarrazzo)" <noreply+dvarrazzo@github.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox