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 everything except dump()) is available as psycopg.adapt.Dumper.

format*: Format*

The format that this class dump() method produces, TEXT or BINARY.

This is a class attribute.

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

Convert the object obj to PostgreSQL representation.

PARAMETERS:

obj – the object to convert.

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

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

Convert the object obj to escaped representation.

PARAMETERS:

obj – the object to convert.

This method will be used by 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.types registry to find the OID of builtin types, and you can use TypeInfo to extend the registry to custom types.

get_key(obj: Any, format: PyFormat) → Union[type, Tuple[Union[type, Tuple[DumperKey, …]], …]]

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

PARAMETERS:

• obj – The object to convert
• format – The format to convert to

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

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

• A Python 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 identify 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: Any, format: PyFormat) → Dumper

Return a new dumper to manage obj.

PARAMETERS:

• obj – The object to convert
• format – The format to convert to

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 everything except load()) is available as psycopg.adapt.Loader.

format*: Format*

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

This is a class attribute.

load(data: Union[bytes, bytearray, memoryview]) → Any

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

PARAMETERS:

data – the data to convert.

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

A context describing how types are adapted.

Example of AdaptContext are Connection, Cursor, Transformer, AdaptersMap.

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

Data adaptation configuration for an explanation about how contexts are connected.

property adapters*: AdaptersMap*

The adapters configuration that this object uses.

property connection*: Optional[BaseConnection[Any]]*

The connection used by this object, if available.

RETURN TYPE:

Connection or AsyncConnection or None