Skip to content
Back to top

# `adapt` – Types adaptation

The `psycopg.adapt` module exposes a set of objects useful for the configuration of data adaptation, which is the conversion of Python objects to PostgreSQL data types and back.

These objects are useful if you need to configure data adaptation, i.e. if you need to change the default way that Psycopg converts between types or if you want to adapt custom data types and objects. You don’t need this object in the normal use of Psycopg.

See Data adaptation configuration for an overview of the Psycopg adaptation system.

## Dumpers and loaders

class psycopg.adapt.Dumper(cls, context=None)

  Convert Python object of the type `cls` to PostgreSQL representation.

  This is an abstract base class, partially implementing the `Dumper` protocol. Subclasses must at least implement the `dump()` method and optionally override other members.

  abstractmethod dump(obj: Any) → bytes | bytearray | memoryview | None

    Convert the object `obj` to PostgreSQL representation.

    Parameters:

      obj – the object to convert.

    Changed in version 3.2: `dump()` can also return `None`, to represent a `NULL` in the database.

  format: psycopg.pq.Format = TEXT

    Class attribute. Set it to `BINARY` if the class `dump()` methods converts the object to binary format.

  quote(obj: Any) → bytes | bytearray | memoryview

    By default return the `dump()` value quoted and sanitised, so that the result can be used to build a SQL string. This works well for most types and you won’t likely have to implement this method in a subclass.

  get_key(obj: Any, format: PyFormat) → abc.DumperKey

    Implementation of the `get_key()` member of the `Dumper` protocol. Look at its definition for details.

    This implementation returns the `cls` passed in the constructor. Subclasses needing to specialise the PostgreSQL type according to the value of the object dumped (not only according to to its type) should override this class.

  upgrade(obj: Any, format: PyFormat) → Dumper

    Implementation of the `upgrade()` member of the `Dumper` protocol. Look at its definition for details.

    This implementation just returns `self`. If a subclass implements `get_key()` it should probably override `upgrade()` too.

class psycopg.adapt.Loader(oid, context=None)

  Convert PostgreSQL values with type OID `oid` to Python objects.

  This is an abstract base class, partially implementing the `Loader` protocol. Subclasses must at least implement the `load()` method and optionally override other members.

  abstractmethod load(data: bytes | bytearray | memoryview) → Any

    Convert a PostgreSQL value to a Python object.

  format: psycopg.pq.Format = TEXT

    Class attribute. Set it to `BINARY` if the class `load()` methods converts the object from binary format.

## Other objects used in adaptations

class psycopg.adapt.PyFormat(*values)

  Enum representing the format wanted for a query argument.

  The value `AUTO` allows psycopg to choose the best format for a certain parameter.

  AUTO = 's'
  TEXT = 't'
  BINARY = 'b'

class psycopg.adapt.AdaptersMap(template: AdaptersMap | None = None, types: TypesRegistry | None = None)

  Establish how types should be converted between Python and PostgreSQL in an `AdaptContext`.

  `AdaptersMap` maps Python types to `Dumper` classes to define how Python types are converted to PostgreSQL, and maps OIDs to `Loader` classes to establish how query results are converted to Python.

  Every `AdaptContext` object has an underlying `AdaptersMap` defining how types are converted in that context, exposed as the `adapters` attribute: changing such map allows to customise adaptation in a context without changing separated contexts.

  When a context is created from another context (for instance when a `Cursor` is created from a `Connection`), the parent’s `adapters` are used as template for the child’s `adapters`, so that every cursor created from the same connection use the connection’s types configuration, but separate connections have independent mappings.

  Once created, `AdaptersMap` are independent. This means that objects already created are not affected if a wider scope (e.g. the global one) is changed.

  The connections adapters are initialised using a global `AdptersMap` template, exposed as `psycopg.adapters`: changing such mapping allows to customise the type mapping for every connections created afterwards.

  The object can start empty or copy from another object of the same class. Copies are copy-on-write: if the maps are updated make a copy. This way extending e.g. global map by a connection or a connection map from a cursor is cheap: a copy is only made on customisation.

  See also

  Data adaptation configuration for an explanation about how contexts are connected.

  register_dumper(cls: type | str | None, dumper: type[Dumper]) → None

    Configure the context to use `dumper` to convert objects of type `cls`.

    If two dumpers with different `format` are registered for the same type, the last one registered will be chosen when the query doesn’t specify a format (i.e. when the value is used with a `%s` “`AUTO`” placeholder).

    Parameters:

      - cls – The type to manage.

      - dumper – The dumper to register for `cls`.

    If `cls` is specified as string it will be lazy-loaded, so that it will be possible to register it without importing it before. In this case it should be the fully qualified name of the object (e.g. `"uuid.UUID"`).

    If `cls` is None, only use the dumper when looking up using `get_dumper_by_oid()`, which happens when we know the Postgres type to adapt to, but not the Python type that will be adapted (e.g. in COPY after using `set_types()`).

  register_loader(oid: int | str, loader: type[Loader]) → None

    Configure the context to use `loader` to convert data of oid `oid`.

    Parameters:

      - oid – The PostgreSQL OID or type name to manage.

      - loader – The loar to register for `oid`.

    If `oid` is specified as string, it refers to a type name, which is looked up in the `types` registry.

  types

    The object where to look up for types information (such as the mapping between type names and oids in the specified context).

    Type:

      `TypesRegistry`

  get_dumper(cls: type, format: PyFormat) → type[Dumper]

    Return the dumper class for the given type and format.

    Raise `ProgrammingError` if a class is not available.

    Parameters:

      - cls – The class to adapt.

      - format – The format to dump to. If `AUTO`, use the last one of the dumpers registered on `cls`.

  get_dumper_by_oid(oid: int, format: Format) → type[Dumper]

    Return the dumper class for the given oid and format.

    Raise `ProgrammingError` if a class is not available.

    Parameters:

      - oid – The oid of the type to dump to.

      - format – The format to dump to.

  get_loader(oid: int, format: Format) → type[Loader] | None

    Return the loader class for the given oid and format.

    Return `None` if not found.

    Parameters:

      - oid – The oid of the type to load.

      - format – The format to load from.

class psycopg.adapt.Transformer(context=None)

  An object that can adapt efficiently between Python and PostgreSQL.

  The life cycle of the object is the query, so it is assumed that attributes such as the server version or the connection encoding will not change. The object have its state so adapting several values of the same type can be optimised.

  Parameters:

    context (`AdaptContext`) – The context where the transformer should operate.