DbTypes – The internal cache for database types

class pg.DbTypes

Added 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 either the simple PyGreSQL names or to the more fine-grained registered PostgreSQL type names if these have been enabled with DB.use_regtypes(). Type names are strings that are augmented with additional information about the associated PostgreSQL type that can be inspected using the following attributes:

• oid – the PostgreSQL type OID

• pgtype – the internal PostgreSQL data type name

• regtype – the registered PostgreSQL data type name

• simple – the more coarse-grained PyGreSQL type name

• typlen – internal size of the type, negative if variable

• typtype – b = base type, c = composite type etc.

• category – A = 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 low-level 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.