adapt – Types adaptation#
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.
- abstract dump(obj)#
Convert the object obj to PostgreSQL representation.
- format: psycopg.pq.Format = TEXT#
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, format)#
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.
- class psycopg.adapt.Loader(oid, context=None)#
Convert PostgreSQL values with type OID oid to Python objects.
Other objects used in adaptations#
- class psycopg.adapt.PyFormat(value)#
Enum representing the format wanted for a query argument.
AUTOallows psycopg to choose the best format for a certain parameter.
- 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
AdaptContextobject has an underlying
AdaptersMapdefining how types are converted in that context, exposed as the
adaptersattribute: 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
Cursoris created from a
Connection), the parent’s
adaptersare 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.
AdaptersMapare 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
AdptersMaptemplate, 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.
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
formatare 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
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.
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
- register_loader(oid, loader)#
Configure the context to use loader to convert data of oid oid.
oidis specified as string, it refers to a type name, which is looked up in the
The object where to look up for types information (such as the mapping between type names and oids in the specified context).
- get_dumper(cls, format)#
Return the dumper class for the given type and format.
ProgrammingErrorif a class is not available.
- get_dumper_by_oid(oid, format)#
Return the dumper class for the given oid and format.
ProgrammingErrorif a class is not available.
- 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.
AdaptContext) – The context where the transformer should operate.