`abc` – Psycopg abstract classes#

The module exposes Psycopg definitions which can be used for static type checking.

class psycopg.abc.Dumper(cls, context=None)#

Convert Python objects of type cls to PostgreSQL representation.

Parameters:

cls (type) – The type that will be managed by this dumper.
context (AdaptContext or None) – The context where the transformation is performed. If not specified the conversion might be inaccurate, for instance it will not be possible to know the connection encoding or the server date format.

A partial implementation of this protocol (implementing everyting except dump()) is available as psycopg.adapt.Dumper.

format: Format#

The format that this class dump() method produces, ~psycopg.pq.Format.TEXT or ~psycopg.pq.Format.BINARY.

This is a class attribute.

dump(obj)#

Convert the object obj to PostgreSQL representation.

Parameters:: obj (Any) – the object to convert.
Return type:: Union[bytes, bytearray, memoryview]

The format returned by dump shouldn’t contain quotes or escaped values.

quote(obj)#

Convert the object obj to escaped representation.

Parameters:: obj (Any) – the object to convert.
Return type:: Union[bytes, bytearray, memoryview]

Tip

This method will be used by ~psycopg.sql.Literal to convert a value client-side.

This method only makes sense for text dumpers; the result of calling it on a binary dumper is undefined. It might scratch your car, or burn your cake. Don’t tell me I didn’t warn you.

oid: int#

The oid to pass to the server, if known; 0 otherwise (class attribute).

If the OID is not specified, PostgreSQL will try to infer the type from the context, but this may fail in some contexts and may require a cast (e.g. specifying %s::type for its placeholder).

You can use the psycopg.adapters.~psycopg.adapt.AdaptersMap.types registry to find the OID of builtin types, and you can use ~psycopg.types.TypeInfo to extend the registry to custom types.

get_key(obj, format)#

Return an alternative key to upgrade the dumper to represent obj.

Parameters:

obj (Any) – The object to convert
format (PyFormat) – The format to convert to

Return type:

Union[type, Tuple[type, ...]]

Normally the type of the object is all it takes to define how to dump the object to the database. For instance, a Python ~datetime.date can be simply converted into a PostgreSQL date.

In a few cases, just the type is not enough. For example:

A Python ~datetime.datetime could be represented as a timestamptz or a timestamp, according to whether it specifies a !tzinfo or not.
A Python int could be stored as several Postgres types: int2, int4, int8, numeric. If a type too small is used, it may result in an overflow. If a type too large is used, PostgreSQL may not want to cast it to a smaller type.
Python lists should be dumped according to the type they contain to convert them to e.g. array of strings, array of ints (and which size of int?…)

In these cases, a dumper can implement !get_key() and return a new class, or sequence of classes, that can be used to indentify the same dumper again. If the mechanism is not needed, the method should return the same cls object passed in the constructor.

If a dumper implements get_key() it should also implement upgrade().

upgrade(obj, format)#

Return a new dumper to manage obj.

Parameters:

obj (Any) – The object to convert
format (PyFormat) – The format to convert to

Return type:

Dumper

Once Transformer.get_dumper() has been notified by get_key() that this Dumper class cannot handle obj itself, it will invoke !upgrade(), which should return a new Dumper instance, which will be reused for every objects for which !get_key() returns the same result.

class psycopg.abc.Loader(oid, context=None)#

Convert PostgreSQL values with type OID oid to Python objects.

Parameters:

oid (int) – The type that will be managed by this dumper.
context (AdaptContext or None) – The context where the transformation is performed. If not specified the conversion might be inaccurate, for instance it will not be possible to know the connection encoding or the server date format.

A partial implementation of this protocol (implementing everyting except load()) is available as psycopg.adapt.Loader.

format: Format#

The format that this class load() method can convert, ~psycopg.pq.Format.TEXT or ~psycopg.pq.Format.BINARY.

This is a class attribute.

load(data)#

Convert the data returned by the database into a Python object.

Parameters:: data (Union[bytes, bytearray, memoryview]) – the data to convert.
Return type:: Any

class psycopg.abc.AdaptContext(*args, **kwargs)#

A context describing how types are adapted.

Example of ~AdaptContext are ~psycopg.Connection, ~psycopg.Cursor, ~psycopg.adapt.Transformer, ~psycopg.adapt.AdaptersMap.

Note that this is a ~typing.Protocol, so objects implementing !AdaptContext don’t need to explicitly inherit from this class.

abc – Psycopg abstract classes#

`abc` – Psycopg abstract classes#