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.patchdiff --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