types – Types information and adapters

The psycopg.types package exposes the concrete implementation of Loader and Dumper to manage builtin objects, together with objects to describe PostgreSQL types and wrappers to help or customise the types conversion.

Types information

The TypeInfo object describes simple information about a PostgreSQL data type, such as its name, oid and array oid. The class can be used to query a database for custom data types: this allows for instance to load automatically arrays of a custom type, once a loader for the base type has been registered.

The TypeInfo object doesn’t instruct Psycopg to convert a PostgreSQL type into a Python type: this is the role of a Loader. However it can extend the behaviour of the adapters: if you create a loader for MyType, using TypeInfo you will be able to manage seamlessly arrays of MyType or ranges and composite types using it as a subtype.

See also

Data adaptation configuration describes about how to convert from Python types to PostgreSQL types and back.

from psycopg.adapt import Loader
from psycopg.types import TypeInfo

t = TypeInfo.fetch(conn, "mytype")
t.register(conn)

for record in conn.execute("SELECT mytypearray FROM mytable"):
    # records will return lists of "mytype" as string

class MyTypeLoader(Loader):
    def load(self, data):
        # parse the data and return a MyType instance

conn.adapters.register_loader("mytype", MyTypeLoader)

for record in conn.execute("SELECT mytypearray FROM mytable"):
    # records will return lists of MyType instances
class psycopg.types.TypeInfo(name, oid, array_oid, alt_name='', delimiter=',')

Hold information about a PostgreSQL base type.

classmethod fetch(conn, name)

Query a system catalog to read information about a type.

Parameters
  • conn (Connection[Any]) – the connection to query

  • name (str or Identifier) – the name of the type to query. It can include a schema name.

Return type

Optional[~T]

Returns

a TypeInfo object populated with the type information, None if not found.

async classmethod fetch_async(conn, name)

Query a system catalog to read information about a type.

Similar to fetch() but can use an asynchronous connection.

Return type

Optional[~T]

register(context=None)

Register the type information, globally or in the specified context.

The context can be a Connection or Cursor. Specifying no context will register the TypeInfo globally.

Registering the TypeInfo in a context allows the adapters of that context to look up type information: for instance it allows to recognise automatically arrays of that type and load them from the database as a list of the base type (how the base type is converted to Python is demanded to a Loader.

class psycopg.types.TypesRegistry(template=None)

Container for the information about types in a database.

The following TypeInfo subclasses allow to fetch more specialised information from certain class of PostgreSQL types and to create more specialised adapters configurations.

class psycopg.types.composite.CompositeInfo(name, oid, array_oid, field_names, field_types)

Manage information about a composite type.

register(context=None, factory=None)

Register the type information, globally or in the specified context.

Using CompositeInfo.register() will also register a specialised loader to fetch the composite type as a Python named tuple, or a custom object if factory is specified.

class psycopg.types.range.RangeInfo(name, oid, array_oid, subtype_oid)

Manage information about a range type.

register(context=None)

Register the type information, globally or in the specified context.

Using RangeInfo.register() will also register a specialised loaders and dumpers. For instance, if you create a PostgreSQL range on the type inet, loading these object with the database will use the loader for the inet type to parse the range bounds - either the builtin ones or any one you might have configured.

The type information will also be used by the Range dumper so that if you dump a Range(address1, address2) object it will use the correct oid for your inetrange type.

Objects wrappers

TODO

Document the various objects wrappers

  • Int2, Int4, Int8, …

  • Range

JSON adapters

See JSON adaptation for details.

class psycopg.types.json.Json(obj, dumps=None)
class psycopg.types.json.Jsonb(obj, dumps=None)

Wrappers to signal to convert obj to a json or jsonb PostgreSQL value.

Any object supported by the underlying dumps() function can be wrapped.

If a dumps function is passed to the wrapper, use it to dump the wrapped object. Otherwise use the function specified by set_json_dumps().

psycopg.types.json.set_json_dumps(dumps, context=None)

Set the JSON serialisation function to store JSON objects in the database.

Parameters
  • dumps (Callable[[Any], str]) – The dump function to use.

  • context (Connection or Cursor) – Where to use the dumps function. If not specified, use it globally.

By default dumping JSON uses the builtin json.dumps. You can override it to use a different JSON library or to use customised arguments.

If the Json wrapper specified a dumps function, use it in precedence of the one set by this function.

psycopg.types.json.set_json_loads(loads, context=None)

Set the JSON parsing function to fetch JSON objects from the database.

Parameters
  • loads (Callable[[bytes], Any]) – The load function to use.

  • context (Connection or Cursor) – Where to use the loads function. If not specified, use it globally.

By default loading JSON uses the builtin json.loads. You can override it to use a different JSON library or to use customised arguments.