source: trunk/docs/contents/pgdb/module.rst @ 751

Last change on this file since 751 was 751, checked in by cito, 4 years ago

Mention the SQLSTATE error code in the pgdb docs

File size: 3.8 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
40Module constants
41----------------
42
43.. data:: apilevel
44
45    The string constant ``'2.0'``, stating that the module is DB-API 2.0 level
46    compliant.
47
48.. data:: threadsafety
49
50    The integer constant 1, stating that the module itself is thread-safe,
51    but the connections are not thread-safe, and therefore must be protected
52    with a lock if you want to use them from different threads.
53
54.. data:: paramstyle
55
56   The string constant ``pyformat``, stating that parameters should be passed
57   using Python extended format codes, e.g. ``" ... WHERE name=%(name)s"``.
58
59Errors raised by this module
60----------------------------
61
62The errors that can be raised by the :mod:`pgdb` module are the following:
63
64.. exception:: Warning
65
66    Exception raised for important warnings like data truncations while
67    inserting.
68
69.. exception:: Error
70
71    Exception that is the base class of all other error exceptions. You can
72    use this to catch all errors with one single except statement.
73    Warnings are not considered errors and thus do not use this class as base.
74
75.. exception:: InterfaceError
76
77    Exception raised for errors that are related to the database interface
78    rather than the database itself.
79
80.. exception:: DatabaseError
81
82    Exception raised for errors that are related to the database.
83
84    In PyGreSQL, this also has a :attr:`DatabaseError.sqlstate` attribute
85    that contains the ``SQLSTATE`` error code of this error.
86
87.. exception:: DataError
88
89    Exception raised for errors that are due to problems with the processed
90    data like division by zero or numeric value out of range.
91
92.. exception:: OperationalError
93
94    Exception raised for errors that are related to the database's operation
95    and not necessarily under the control of the programmer, e.g. an unexpected
96    disconnect occurs, the data source name is not found, a transaction could
97    not be processed, or a memory allocation error occurred during processing.
98
99.. exception:: IntegrityError
100
101    Exception raised when the relational integrity of the database is affected,
102    e.g. a foreign key check fails.
103
104.. exception:: ProgrammingError
105
106    Exception raised for programming errors, e.g. table not found or already
107    exists, syntax error in the SQL statement or wrong number of parameters
108    specified.
109
110.. exception:: NotSupportedError
111
112    Exception raised in case a method or database API was used which is not
113    supported by the database.
Note: See TracBrowser for help on using the repository browser.