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: pq.Format

The format this class dumps, TEXT or BINARY. This is a class attribute.

dump(obj)

Convert the object obj to PostgreSQL representation.

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.

Return type

Union[bytes, bytearray, memoryview]

Tip

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.

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

todo

Document how to find type OIDs in a database.

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

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 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 implmement upgrade().

Return type

Union[type, Tuple[type, …]]

upgrade(obj, format)

Return a new dumper to manage obj.

Parameters

  • obj (Any) – The object to convert

  • format (PyFormat) – 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.

Return type

Dumper

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

Convert PostgreSQL objects with 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 this class can load, TEXT or BINARY. This is a class attribute.

load(data)
Return type

Any

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.

property adapters: AdaptersMap

The adapters configuration that this object uses.

Return type

AdaptersMap

property connection: Optional[BaseConnection[Any]]

The connection used by this object, if available.

Return type

Connection or AsyncConnection or None