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

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

Cache typecast functions and make them configurable

The typecast functions used by the pgdb module are now cached
using a local and a global Typecasts class. The local cache is
bound to the connection and knows how to cast composite types.

Also added functions that allow registering custom typecast
functions on the global and local level.

Also added a chapter on type adaptation and casting to the docs.

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(typ, value)
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
77.. note::
78
79    Note that the :class:`TypeCache` is always bound to a database connection.
80    You can also get, set and reset typecast functions on a global level using
81    the functions :func:`pgdb.get_typecast`, :func:`pgdb.set_typecast` and
82    :func:`pgdb.reset_typecast`.  If you do this, the current database
83    connections will continue to use their already cached typecast functions
84    unless you call the :meth:`TypeCache.reset_typecast` method on the
85    :attr:`Connection.type_cache` of the running connections.
Note: See TracBrowser for help on using the repository browser.