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: subclasses must at least implement the dump() method and specify the format.

The class implements the Dumper protocol.

abstract dump(obj)

Convert the object obj to PostgreSQL representation.

Parameters

obj (Any) – the object to convert.

Return type

Union[bytes, bytearray, memoryview]

quote(obj)

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.

Return type

Union[bytes, bytearray, memoryview]

get_key(obj, format)

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.

Return type

Union[type, Tuple[type, …]]

upgrade(obj, format)

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.

Return type

Dumper

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

Convert PostgreSQL objects with OID oid to Python objects.

This is an abstract base class: subclasses must at least implement the load() method and specify a format.

The class implements the Loader protocol.

abstract load(data)

Convert a PostgreSQL value to a Python object.

Return type

Any

Other objects used in adaptations

class psycopg.adapt.PyFormat(value)

Enum representing the format wanted for a query argument.

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

AUTO = 's'
TEXT = 't'
BINARY = 'b'
class psycopg.adapt.AdaptersMap(template=None, types=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, dumper)

Configure the context to use dumper to convert object 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 %sAUTO” placeholder).

Parameters

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, loader)

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

Parameters
  • oid (Union[int, str]) – The PostgreSQL OID or type name to manage.

  • loader (Type[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, format)

Return the dumper class for the given type and format.

Raise ProgrammingError if a class is not available.

Parameters
  • cls (type) – The class to adapt.

  • format (PyFormat) – The format to dump to. If AUTO, use the last one of the dumpers registered on cls.

Return type

Type[Dumper]

get_dumper_by_oid(oid, format)

Return the dumper class for the given oid and format.

Raise ProgrammingError if a class is not available.

Parameters
  • oid (int) – The oid of the type to dump to.

  • format (Format) – The format to dump to.

Return type

Type[Dumper]

get_loader(oid, format)

Return the loader class for the given oid and format.

Return None if not found.

Parameters
  • oid (int) – The oid of the type to load.

  • format (Format) – The format to load from.

Return type

Optional[Type[Loader]]

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.