Package grizzled :: Package db
[hide private]
[frames] | no frames]

Source Code for Package grizzled.db

  1  # $Id: fa873c96e7b5ed23437473a2b6d0b9a3871d4a18 $ 
  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  # Imports 
 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  # Exports 
 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  # Globals 
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  # Functions 
130  # --------------------------------------------------------------------------- 
131   
132 -def add_driver(key, driver_class, force=False):
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
159 -def get_drivers():
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
175 -def get_driver_names():
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
183 -def get_driver(driver_name):
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