DbTypes – The internal cache for database types

class pg.DbTypes

New in version 5.0.

The DbTypes object is essentially a dictionary mapping PostgreSQL internal type names and type OIDs to PyGreSQL “type names” (which are also returned by DB.get_attnames() as dictionary values).

These type names are strings which are equal to the simple PyGreSQL name or to regular type names if these have been enabled with DB.use_regtypes(). Besides being strings, they are also carrying additional information about the associated PostgreSQL type in the following attributes:

  • oid – the PostgreSQL type OID
  • pgtype – the PostgreSQL type name
  • regtype – the regular type name
  • simple – the simple PyGreSQL type name
  • typtypeb = base type, c = composite type etc.
  • categoryA = Array, b =Boolean, C = Composite etc.
  • delim – delimiter for array types
  • relid – corresponding table for composite types
  • attnames – attributes for composite types

For details, see the PostgreSQL documentation on pg_type.

In addition to the dictionary methods, the DbTypes class also provides the following methods:

DbTypes.get_attnames(typ)

Get the names and types of the fields of composite types

Parameters:typ (str or int) – PostgreSQL type name or OID of a composite type
Returns:an ordered dictionary mapping field names to type names
DbTypes.get_typecast(typ)

Get the cast function for the given database type

Parameters:typ (str) – PostgreSQL type name
Returns:the typecast function for the specified type
Return type:function or None
DbTypes.set_typecast(typ, cast)

Set a typecast function for the given database type(s)

Parameters:
  • typ (str or int) – PostgreSQL type name or list of type names
  • cast – the typecast function to be set for the specified type(s)

The typecast function must take one string object as argument and return a Python object into which the PostgreSQL type shall be casted. If the function takes another parameter named connection, then the current database connection will also be passed to the typecast function. This may sometimes be necessary to look up certain database settings.

DbTypes.reset_typecast([typ])

Reset the typecasts for the specified (or all) type(s) to their defaults

Parameters:typ (str, list or None) – PostgreSQL type name or list of type names, or None to reset all typecast functions
DbTypes.typecast(value, typ)

Cast the given value according to the given database type

Parameters:typ (str) – PostgreSQL type name or type code
Returns:the casted value

Note

Note that DbTypes object is always bound to a database connection. You can also get and set and reset typecast functions on a global level using the functions pg.get_typecast() and pg.set_typecast(). If you do this, the current database connections will continue to use their already cached typecast functions unless you reset the typecast functions by calling the DbTypes.reset_typecast() method on DB.dbtypes objects of the running connections.

Also note that the typecasting for all of the basic types happens already in the C extension module. The typecast functions that can be set with the above methods are only called for the types that are not already supported by the C extension module.