1
2
3 """
4 Introduction
5 ============
6
7 The ``db`` module is a DB API wrapper. It provides a DB API-compliant API that
8 wraps real underlying DB API drivers, simplifying some non-portable operations
9 like ``connect()`` and providing some new operations.
10
11 Some drivers come bundled with this package. Others can be added on the fly.
12
13 Getting the List of Drivers
14 ===========================
15
16 To get a list of all drivers currently registered with this module, use the
17 ``get_driver_names()`` method:
18
19 .. python::
20
21 import db
22
23 for driver_name in db.get_driver_names():
24 print driver_name
25
26 Currently, this module provides the following bundled drivers:
27
28 +------------------+------------+-------------------+
29 | Driver Name, | | |
30 | as passed to | | Underlying Python |
31 | ``get_driver()`` | Database | DB API module |
32 +==================+============+===================+
33 | dummy | None | ``db.DummyDB`` |
34 +------------------+------------+-------------------+
35 | gadfly | Gadfly | ``gadfly`` |
36 +------------------+------------+-------------------+
37 | mysql | MySQL | ``MySQLdb`` |
38 +------------------+------------+-------------------+
39 | oracle | Oracle | ``cx_Oracle`` |
40 +------------------+------------+-------------------+
41 | postgresql | PostgreSQL | ``psycopg2`` |
42 +------------------+------------+-------------------+
43 | sqlserver | SQL Server | ``pymssql`` |
44 +------------------+------------+-------------------+
45 | sqlite | SQLite 3 | ``sqlite3`` |
46 +------------------+------------+-------------------+
47
48 To use a given driver, you must have the corresponding Python DB API module
49 installed on your system.
50
51 Adding a Driver
52 ===============
53
54 It's possible to add a new driver to the list of drivers supplied by this
55 module. To do so:
56
57 1. The driver class must extend ``DBDriver`` and provide the appropriate
58 methods. See examples in this module.
59 2. The driver's module (or the calling program) must register the driver
60 with this module by calling the ``add_driver()`` function.
61
62
63 DB API Factory Functions
64 ========================
65
66 The ``Binary()``, ``Date()``, ``DateFromTicks()``, ``Time()``,
67 ``TimeFromTicks()``, ``TimeStamp()`` and ``TimestampFromTicks()`` DB API
68 functions can be found in the DB class. Thus, to make a string into a BLOB
69 with this API, you use:
70
71 .. python::
72
73 driver = db.get_driver(driver_name)
74 db = driver.connect(...)
75 blob = db.Binary(some_string)
76 """
77
78 __docformat__ = "restructuredtext en"
79
80
81
82
83
84 import re
85 import time
86 import os
87 import sys
88 from datetime import date, datetime
89
90 from grizzled.exception import ExceptionWithMessage
91 from grizzled.decorators import abstract
92 from grizzled.db import (base, dummydb, dbgadfly, mysql, oracle, postgresql,
93 sqlite, sqlserver)
94 from grizzled.db.base import *
95
96
97
98
99
100 __all__ = ['get_driver', 'add_driver', 'get_driver_names', 'DBDriver',
101 'DB', 'Cursor', 'DBError', 'Error', 'Warning', 'apilevel',
102 'threadsafety', 'paramstyle']
103
104
105
106
107
108 DummyDriver = dummydb.DummyDriver
109 GadflyDriver = dbgadfly.GadflyDriver
110 MySQLDriver = mysql.MySQLDriver
111 OracleDriver = oracle.OracleDriver
112 PostgreSQLDriver = postgresql.PostgreSQLDriver
113 SQLite3Driver = sqlite.SQLite3Driver
114 SQLServerDriver = sqlserver.SQLServerDriver
115
116 drivers = { 'dummy' : 'DummyDriver',
117 'mysql' : 'MySQLDriver',
118 'postgresql' : 'PostgreSQLDriver',
119 'sqlserver' : 'SQLServerDriver',
120 'sqlite' : 'SQLite3Driver',
121 'oracle' : 'OracleDriver',
122 'gadfly' : 'GadflyDriver'}
123
124 apilevel = '2.0'
125 threadsafety = '1'
126 paramstyle = None
127
128
129
130
131
133 """
134 Add a driver class to the list of drivers.
135
136 :Parameters:
137 key : str
138 the key, also used as the driver's name
139 driver_class : class
140 the ``DBDriver`` subclass object
141 force : bool
142 ``True`` to force registration of the driver, even if there's an
143 existing driver with the same key; ``False`` to throw an exception
144 if there's an existing driver with the same key.
145
146 :raise ValueError: There's an existing driver with the same key, and
147 ``force`` is ``False``
148 """
149 try:
150 drivers[key]
151 if not force:
152 raise ValueError, 'A DB driver named "%s" is already installed' %\
153 key
154 except KeyError:
155 pass
156
157 drivers[key] = driver_class
158
160 """
161 Get the list of drivers currently registered with this API. The result is
162 a list of ``DBDriver`` subclasses. Note that these are classes, not
163 instances. Once way to use the resulting list is as follows:
164
165 .. python::
166
167 for driver in db.get_drivers():
168 print driver.__doc__
169
170 :rtype: list
171 :return: list of ``DBDriver`` class names
172 """
173 return [str(d) for d in drivers.values()]
174
176 """
177 Get the list of driver names currently registered with this API.
178 Each of the returned names may be used as the first parameter to
179 the ``get_driver()`` function.
180 """
181 return drivers.keys()
182
184 """
185 Get the DB API object for the specific database type. The list of
186 legal database types are available by calling ``get_driver_names()``.
187
188 :Parameters:
189 driver_name : str
190 name (key) of the driver
191
192 :rtype: DBDriver
193 :return: the instantiated driver
194
195 :raise ValueError: Unknown driver name
196 """
197 try:
198 o = drivers[driver_name]
199 if type(o) == str:
200 exec 'd = %s()' % o
201 else:
202 d = o()
203 return d
204 except KeyError:
205 raise ValueError, 'Unknown driver name: "%s"' % driver_name
206