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