source: trunk/docs/contents/pgdb/module.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: 5.9 KB
Line 
1Module functions and constants
2==============================
3
4.. py:currentmodule:: pgdb
5
6The :mod:`pgdb` module defines a :func:`connect` function that allows to
7connect to a database, some global constants describing the capabilities
8of the module as well as several exception classes.
9
10connect -- Open a PostgreSQL connection
11---------------------------------------
12
13.. function:: connect([dsn], [user], [password], [host], [database])
14
15    Return a new connection to the database
16
17    :param str dsn: data source name as string
18    :param str user: the database user name
19    :param str password: the database password
20    :param str host: the hostname of the database
21    :param database: the name of the database
22    :returns: a connection object
23    :rtype: :class:`Connection`
24    :raises pgdb.OperationalError: error connecting to the database
25
26This function takes parameters specifying how to connect to a PostgreSQL
27database and returns a :class:`Connection` object using these parameters.
28If specified, the *dsn* parameter must be a string with the format
29``'host:base:user:passwd:opt'``. All of the parts specified in the *dsn*
30are optional. You can also specify the parameters individually using keyword
31arguments, which always take precedence. The *host* can also contain a port
32if specified in the format ``'host:port'``. In the *opt* part of the *dsn*
33you can pass command-line options to the server.
34
35Example::
36
37    con = connect(dsn='myhost:mydb', user='guido', password='234$')
38
39
40get/set/reset_typecast -- Control the global typecast functions
41---------------------------------------------------------------
42
43PyGreSQL uses typecast functions to cast the raw data coming from the
44database to Python objects suitable for the particular database type.
45These functions take a single string argument that represents the data
46to be casted and must return the casted value.
47
48PyGreSQL provides built-in typecast functions for the common database types,
49but if you want to change these or add more typecast functions, you can set
50these up using the following functions.
51
52.. note::
53
54    The following functions are not part of the DB-API 2 standard.
55
56.. method:: get_typecast(typ)
57
58    Get the global cast function for the given database type
59
60    :param str typ: PostgreSQL type name or type code
61    :returns: the typecast function for the specified type
62    :rtype: function or None
63
64.. versionadded:: 5.0
65
66.. method:: set_typecast(typ, cast)
67
68    Set a global typecast function for the given database type(s)
69
70    :param typ: PostgreSQL type name or type code, or list of such
71    :type typ: str or list
72    :param cast: the typecast function to be set for the specified type(s)
73    :type typ: str or int
74
75.. versionadded:: 5.0
76
77.. method:: reset_typecast([typ])
78
79    Reset the typecasts for the specified (or all) type(s) to their defaults
80
81    :param str typ: PostgreSQL type name or type code, or list of such,
82        or None to reset all typecast functions
83    :type typ: str, list or None
84
85.. versionadded:: 5.0
86
87Note that database connections cache types and their cast functions using
88connection specific :class:`TypeCache` objects.  You can also get, set and
89reset typecast functions on the connection level using the methods
90:meth:`TypeCache.get_typecast`, :meth:`TypeCache.set_typecast` and
91:meth:`TypeCache.reset_typecast` of the :attr:`Connection.type_cache`.  This
92will not affect other connections or future connections.  In order to be sure
93a global change is picked up by a running connection, you must reopen it or
94call :meth:`TypeCache.reset_typecast` on the :attr:`Connection.type_cache`.
95
96
97Module constants
98----------------
99
100.. data:: apilevel
101
102    The string constant ``'2.0'``, stating that the module is DB-API 2.0 level
103    compliant.
104
105.. data:: threadsafety
106
107    The integer constant 1, stating that the module itself is thread-safe,
108    but the connections are not thread-safe, and therefore must be protected
109    with a lock if you want to use them from different threads.
110
111.. data:: paramstyle
112
113   The string constant ``pyformat``, stating that parameters should be passed
114   using Python extended format codes, e.g. ``" ... WHERE name=%(name)s"``.
115
116Errors raised by this module
117----------------------------
118
119The errors that can be raised by the :mod:`pgdb` module are the following:
120
121.. exception:: Warning
122
123    Exception raised for important warnings like data truncations while
124    inserting.
125
126.. exception:: Error
127
128    Exception that is the base class of all other error exceptions. You can
129    use this to catch all errors with one single except statement.
130    Warnings are not considered errors and thus do not use this class as base.
131
132.. exception:: InterfaceError
133
134    Exception raised for errors that are related to the database interface
135    rather than the database itself.
136
137.. exception:: DatabaseError
138
139    Exception raised for errors that are related to the database.
140
141    In PyGreSQL, this also has a :attr:`DatabaseError.sqlstate` attribute
142    that contains the ``SQLSTATE`` error code of this error.
143
144.. exception:: DataError
145
146    Exception raised for errors that are due to problems with the processed
147    data like division by zero or numeric value out of range.
148
149.. exception:: OperationalError
150
151    Exception raised for errors that are related to the database's operation
152    and not necessarily under the control of the programmer, e.g. an unexpected
153    disconnect occurs, the data source name is not found, a transaction could
154    not be processed, or a memory allocation error occurred during processing.
155
156.. exception:: IntegrityError
157
158    Exception raised when the relational integrity of the database is affected,
159    e.g. a foreign key check fails.
160
161.. exception:: ProgrammingError
162
163    Exception raised for programming errors, e.g. table not found or already
164    exists, syntax error in the SQL statement or wrong number of parameters
165    specified.
166
167.. exception:: NotSupportedError
168
169    Exception raised in case a method or database API was used which is not
170    supported by the database.
Note: See TracBrowser for help on using the repository browser.