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.

abstract dump(obj: Any) → Union[bytes, bytearray, memoryview]

Convert the object obj to PostgreSQL representation.

Parameters:

obj – the object to convert.

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) → Union[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) → Union[type, Tuple[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.

abstract load(data: Union[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(value)

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: Optional[AdaptersMap] = None, types: Optional[TypesRegistry] = 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: Optional[Union[type, str]], dumper: Type[Dumper])

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: Union[int, str], loader: Type[Loader])

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) → Optional[Type[Loader]]

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.