source: trunk/docs/contents/pg/db_types.rst @ 798

Last change on this file since 798 was 798, checked in by cito, 3 years ago

Port type cache and typecasting from pgdb to pg

So far, the typecasting in the classic module was been only done by
the C extension module and was not extensible through typecasting
functions in Python. This has now been made extensible by adding
a cast hook to the C extension module which has been hooked up to
a new type cache object that holds information on the types and the
associated typecast functions. All of this works very similar to the
pgdb module now, except that the basic types are still handled by
the C extension module and the Python typecast functions are only
called via the hook for types which are not supported internally.

Also added tests and a chapter on the type cache in the documentation,
and cleaned up the error messages in the C extension module.

File size: 3.3 KB
Line 
1DbTypes -- The internal cache for database types
2================================================
3
4.. py:currentmodule:: pg
5
6.. class:: DbTypes
7
8.. versionadded:: 5.0
9
10The :class:`DbTypes` object is essentially a dictionary mapping PostgreSQL
11internal type names and type OIDs to PyGreSQL "type names" (which are also
12returned by :meth:`DB.get_attnames` as dictionary values).
13
14These type names are strings which are equal to the simple PyGreSQL name or
15to regular type names if these have been enabled with :meth:`DB.use_regtypes`.
16Besides being strings, they are also carrying additional information about the
17associated PostgreSQL type in the following attributes:
18
19        - *oid* -- the PostgreSQL type OID
20        - *pgtype* -- the PostgreSQL type name
21        - *regtype* -- the regular type name
22        - *simple* -- the simple PyGreSQL type name
23        - *typtype* -- `b` = base type, `c` = composite type etc.
24        - *category* -- `A` = Array, `b` =Boolean, `C` = Composite etc.
25        - *delim* -- delimiter for array types
26        - *relid* -- corresponding table for composite types
27        - *attnames* -- attributes for composite types
28
29For details, see the PostgreSQL documentation on `pg_type
30<http://www.postgresql.org/docs/current/static/catalog-pg-type.html>`_.
31
32In addition to the dictionary methods, the :class:`DbTypes` class also
33provides the following methods:
34
35.. method:: DbTypes.get_attnames(typ)
36
37    Get the names and types of the fields of composite types
38
39    :param typ: PostgreSQL type name or OID of a composite type
40    :type typ: str or int
41    :returns: an ordered dictionary mapping field names to type names
42
43.. method:: DbTypes.get_typecast(typ)
44
45    Get the cast function for the given database type
46
47    :param str typ: PostgreSQL type name
48    :returns: the typecast function for the specified type
49    :rtype: function or None
50
51.. method:: DbTypes.set_typecast(typ, cast)
52
53    Set a typecast function for the given database type(s)
54
55    :param typ: PostgreSQL type name or list of type names
56    :type typ: str or list
57    :param cast: the typecast function to be set for the specified type(s)
58    :type typ: str or int
59
60.. method:: DbTypes.reset_typecast([typ])
61
62    Reset the typecasts for the specified (or all) type(s) to their defaults
63
64    :param str typ: PostgreSQL type name or list of type names,
65        or None to reset all typecast functions
66    :type typ: str, list or None
67
68.. method:: DbTypes.typecast(value, typ)
69
70    Cast the given value according to the given database type
71
72    :param str typ: PostgreSQL type name or type code
73    :returns: the casted value
74
75.. note::
76
77    Note that :class:`DbTypes` object is always bound to a database connection.
78    You can also get and set and reset typecast functions on a global level
79    using the functions :func:`pg.get_typecast` and :func:`pg.set_typecast`.
80    If you do this, the current database connections will continue to use their
81    already cached typecast functions unless you reset the typecast functions
82    by calling the :meth:`DbTypes.reset_typecast` method on :attr:`DB.dbtypes`
83    objects of the running connections.
84
85    Also note that the typecasting for all of the basic types happens already
86    in the C extension module.  The typecast functions that can be set with
87    the above methods are only called for the types that are not already
88    supported by the C extension module.
Note: See TracBrowser for help on using the repository browser.