`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) → Optional[Union[bytes, bytearray, memoryview]]#

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) → 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.

adapt – Types adaptation#

Dumpers and loaders#

Other objects used in adaptations#

`adapt` – Types adaptation#