source: trunk/docs/contents/pgdb/typecache.rst @ 798

Last change on this file since 798 was 798, checked in by cito, 4 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.1 KB
Line 
1TypeCache -- The internal cache for database types
2==================================================
3
4.. py:currentmodule:: pgdb
5
6.. class:: TypeCache
7
8.. versionadded:: 5.0
9
10The internal :class:`TypeCache` of PyGreSQL is not part of the DB-API 2
11standard, but is documented here in case you need full control and
12understanding of the internal handling of database types.
13
14The TypeCache is essentially a dictionary mapping PostgreSQL internal
15type names and type OIDs to DB-API 2 "type codes" (which are also returned
16as the *type_code* field of the :attr:`Cursor.description` attribute).
17
18These type codes are strings which are equal to the PostgreSQL internal
19type name, but they are also carrying additional information about the
20associated PostgreSQL type in the following attributes:
21
22        - *oid* -- the OID of the type
23        - *len*  -- the internal size
24        - *type*  -- ``'b'`` = base, ``'c'`` = composite, ...
25        - *category*  -- ``'A'`` = Array, ``'B'`` = Boolean, ...
26        - *delim*  -- delimiter to be used when parsing arrays
27        - *relid*  -- the table OID 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:`TypeCache` provides
33the following methods:
34
35.. method:: TypeCache.get_fields(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: a list of pairs of field names and types
42    :rtype: list
43
44.. method:: TypeCache.get_typecast(typ)
45
46    Get the cast function for the given database type
47
48    :param str typ: PostgreSQL type name or type code
49    :returns: the typecast function for the specified type
50    :rtype: function or None
51
52.. method:: TypeCache.set_typecast(typ, cast)
53
54    Set a typecast function for the given database type(s)
55
56    :param typ: PostgreSQL type name or type code, or list of such
57    :type typ: str or list
58    :param cast: the typecast function to be set for the specified type(s)
59    :type typ: str or int
60
61.. method:: TypeCache.reset_typecast([typ])
62
63    Reset the typecasts for the specified (or all) type(s) to their defaults
64
65    :param str typ: PostgreSQL type name or type code, or list of such,
66        or None to reset all typecast functions
67    :type typ: str, list or None
68
69.. method:: TypeCache.typecast(value, typ)
70
71    Cast the given value according to the given database type
72
73    :param str typ: PostgreSQL type name or type code
74    :returns: the casted value
75
76.. note::
77
78    Note that the :class:`TypeCache` is always bound to a database connection.
79    You can also get, set and reset typecast functions on a global level using
80    the functions :func:`pgdb.get_typecast`, :func:`pgdb.set_typecast` and
81    :func:`pgdb.reset_typecast`.  If you do this, the current database
82    connections will continue to use their already cached typecast functions
83    unless call the :meth:`TypeCache.reset_typecast` method on the
84    :attr:`Connection.type_cache` objects of the running connections.
Note: See TracBrowser for help on using the repository browser.