Skip to content
Back to top

# `abc` – Psycopg abstract classes

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

See also

Dumpers and loaders life cycle for more information about how these objects are used by Psycopg,

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

  Convert Python objects of type `cls` to PostgreSQL representation.

  This class is a formal `Protocol`. A partial implementation of this protocol (implementing everything except the `dump()` metood) is available as `psycopg.adapt.Dumper`.

  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.

  format: Format

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

    This is a class attribute.

  dump(obj: Any) → bytes | bytearray | memoryview | None

    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.

    Changed in version 3.2: `dump()` can also return `None`, to represent a `NULL` in the database.

  quote(obj: Any) → bytes | bytearray | memoryview

    Convert the object `obj` to escaped representation.

    Parameters:

      obj – the object to convert.

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

  This class is a formal `Protocol`. A partial implementation of this protocol (implementing everything except the `load()` method) is available as `psycopg.adapt.Loader`.

  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.

  format: Format

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

    This is a class attribute.

  load(data: 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.

  See also

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

  property adapters: AdaptersMap

    The adapters configuration that this object uses.

  property connection: BaseConnection[Any] | None

    The connection used by this object, if available.

    Return type:

      `Connection` or `AsyncConnection` or `None`