python Database API Specification v2.0

1.模組介面
  a.方法:
    connect(parameters...)
 建立一個資料庫連接,返回Connection對象
 可能的參數有:
        dsn         資料來源名稱
        user        使用者名稱
        password    密碼
        host        主機名稱
        database    資料庫名
  b.常量
    apilevel
 字串常量,用於指明支援的DB API 版本.目前僅僅允許 "1.0" 和 "2.0",如果沒有指定,預設是"1.0"

   threadsafety
 整數常量,用於指明支援的安全執行緒(thread safety)層級,可能的值有:
     0      線程不能共用模組
        1     線程除了串連以外可以共用模組
        2     線程可以共用串連和模組
        3     線程可以共用串連,遊標和模組
        共用意味著兩個線程可以使用資源,而不需要使用互斥鎖鎖住資源

    paramstyle
 字串常量,用於指明支援的sql參數格式,可能的值有:
     'qmark'         支援'...WHERE name=?'的'?'佔位格式
        'numeric'       支援'...WHERE name=:1'的位置參數
        'named'         支援'...WHERE name=:name'的具名引數
        'format'        支援'...WHERE name=%s'的C語言printf風格
        'pyformat'      支援'...WHERE name=%(name)s'的python擴充格式化格式

  c.異常
    StandardError
    |
    |－Warning
 |  當插入資料時截斷等操作發生時,引發Warning,Warning必須是Python StandardError
 |  (定義在exceptions模組中)的子類
 |－Error
    | 其他異常的超類,可以使用Error捕獲所有資料庫操作異常.Warning不認為是異常.Error必須是
    | Python StandardError的子類
    |
    |－InterfaceError
    | 代表Python DB API 實現的介面錯誤而並非資料庫本身的錯誤,Error的子類
    |
    |－DatabaseError
        | 代表資料庫相關的錯誤,Error的子類
        |
        |－DataError
     |     資料處理的錯誤,比如除0錯誤,整數超過精度等,DatabaseError的子類
     |
     |－OperationalError
     |  資料庫操作錯誤,比如資料來源未找到,事務無法處理,記憶體配置錯誤等等,DatabaseError的子類
     |
     |－IntegrityError
     |  資料完整性不一致錯誤,比如外鍵檢查錯誤等.DatabaseError的子類
     |
     |－InternalError
     |  資料庫內部錯誤,比如遊標無效(遊標關閉後繼續調用),事務不同步等.DatabaseError的子類
     |
     |－ProgrammingError
     |  編程錯誤,比如表不存在,SQL語法錯誤等.DatabaseError的子類
     |
     |－NotSupportedError
     資料庫不支援DB API中某些方法錯誤,比如,在不支援事務的資料庫上調用rollback操作.
     DatabaseError的子類

2.Connection對象
  a.方法
    close()
 關閉串連,調用close()以後Connection對象將不再可用,此後在此Connection對象以及該串連建立的Cursor對象上調用方法
    將引發異常.注意:在沒有提交事務的情況下關閉串連將隱式的復原事務.

    commit()
 提交當前事務.如果資料庫支援自動認可的特性,初始化連線物件的時候這個特性是被關閉的.在不支援事務的資料庫上此方法無效.

 rollback()
 復原當前事務.在不支援事務的資料庫上引發異常

 cursor()
 返回該Connection對象建立的Cursor對象

3.Cursor對象
  Cursor對象代表了資料庫的遊標,用於管理資料庫操作的上下文環境.同一個Connection建立的Cursor對象並不隔離,也就是說其中
  一個Cursor對象修改的資料可以被立刻反映給另一個Cursor對象.而不同Connection建立的Cursor對象可以也可以不隔離,這要
  取決於資料庫支援隔離的程度.
  a.屬性
    description
 由7個元素組成的序列,格式為
 (name, type_code,display_size, internal_size, precision, scale,null_ok).
 前兩個元素(name和type_code)是必須的,後五個可選並且當不能提供有意義的值時必須設定成None
 description屬性當沒有返回記錄或者Cursor對象沒有調用executeXXX()方法時可能返回None
 type_code可以被下面介紹的Type對象解釋

 rowcount
 最後一個查詢(select)返回的記錄數或者最後一次操作(insert,update)影響的記錄數
 如果沒有執行executeXXX,這個屬性返回-1(以後的DB API可能會改成返回None)

 arraysize
 這個設定指定了fetchmany方法一次取多少行記錄,預設值是1

  b.方法
 callproc(procname[,parameters])
 調用預存程序,由於並非所有資料庫支援預存程序,所以這個方法是可選的
 參數procname是預存程序名,參數parameters序列必須符合預存程序需要的參數.調用的結果是輸入的parameters序列的修改後
 的一個拷貝.預存程序輸入參數不會改變,輸出參數和輸入/輸出參數可能會替換成新的值
 預存程序也可以返回一個結果集,這可以通過fetchXXX方法擷取

 close()
 關閉遊標.調用close()以後Cursor對象將不再可用,此後在此Cursor對象上調用方法將引發異常

 execute(operation[,parameters])
 執行資料庫操作(查詢或者命令).parameters可以以序列或者映射的形式綁定到operation.
 Cursor對象可以保留operation的引用,這樣當相同的operation再次執行的時候,Cursor對象能夠最佳化操作.這是在執行相同
 operation但提供不同的參數的情況下最有效最佳化演算法.

 executemany(operation[,seq_of_parameters])
 使用seq_of_parameters所有的元素(序列或者映射)執行資料庫操作(查詢或者命令)
 一些DB API實現可能是通過在方法中多次調用execute來完成這個操作的

 fetchone()
 獲得查詢結果集的下一行資料,返回一個序列,這個序列中包含了資料表每一列的值,當沒有下一行資料時返回None
 如果之前的executeXXX方法沒有返回結果集或者根本沒有調用executeXXX的時候,這個方法將拋出異常

 fetchmany([size = cursor.arraysize])
 返回查詢結果集中指定長度的子集,通常是一個包含序列元素的序列(如:由tuple組成的list).當沒有子集的時候返回空序列
 子集的長度是由size參數指定的,沒有指定的情況下使用Cursor對象的arraysize屬性,如果資料表中沒有指定長度的資料行,
 那麼將返回最大的可能值.
 如果之前的executeXXX方法沒有返回結果集或者根本沒有調用executeXXX的時候,這個方法將拋出異常

 fetchall()
 返回查詢結果集中所有剩餘行的序列,通常是一個包含序列元素的序列(如:由tuple組成的list).
 注意:Cursor對象的arraysize屬性將影響這個方法的效能.
 如果之前的executeXXX方法沒有返回結果集或者根本沒有調用executeXXX的時候,這個方法將拋出異常

 nextset()
 使Cursor對象跳轉到下一個結果集,由於並非所有資料庫都支援多重結果集,所以這個方法是可選的
 如果沒有更多的結果集,這個方法返回None.否則將返回true,在以後調用fetchXXX方法後將會得到資料
 如果之前的executeXXX方法沒有返回結果集或者根本沒有調用executeXXX的時候,這個方法將拋出異常

4.Type對象和構造器
 許多資料庫在將參數綁定到指定的操作上需要有特殊的格式.比如,網DATA類型的列上插入資料的時候就需要有不同的格式.現在
 的問題是:由於傳遞到executeXXX方法上的參數是沒有類型的(僅僅是string),那麼資料庫如何知道您將要插入的是日期格式呢?
 為瞭解決這個問題,DB API實現模組必須提供下面的構造器,用於建立指定類型的對象.當把這些對象傳遞給Cursor後,此時就可以
 準確的探測類型並正確的綁定了.

 構造器

 Date(year,month,day)       日期
 Time(hour,minute,second)       時間
 Timestamp(year,month,day,hour,minute,second)  日期和時間
 DateFromTicks(ticks)       從新紀元以來的秒數計算出來的日期
    TimeFromTicks(ticks)       從新紀元以來的秒數計算出來的時間
    TimestampFromTicks(ticks)      從新紀元以來的秒數計算出來的日期和時間
    Binary(string)         給定字串的二進位值

 Cursor對象的descriptor方法返回的序列中,type_code必須是下面的某個類型,而Type對象可以和多個type_code相等.

    STRING           描述資料庫的字元列,如CHAR
    BINARY           描述資料庫的二進位列,如LONG, RAW, BLOBs
    NUMBER           描述資料庫的數字列
    DATETIME          描述資料庫的日期/時間列
    ROWID           描述資料庫的"Row ID"列

    SQL NULL 值用python的None表示

5.使用MySQLdb(python DB API實現)串連mysql資料庫的樣本

 #資料庫名misc
 #表指令碼
 #CREATE TABLE user (
 #  id int(11) NOT NULL auto_increment,
 #  name varchar(20) NOT NULL default '',
 #  email varchar(255) default NULL,
 #  mobile varchar(40) default NULL,
 #  createtime timestamp(14) NOT NULL,
 #  PRIMARY KEY  (id)
 #  ) TYPE=InnoDB;

 import MySQLdb as mysql
 import time

 class User(object):
     attributes = ['id','name','email','mobile']  #使用者物件允許的屬性
     def __init__(self,dbrow=()):
      """
      初始化使用者

      dbrow - 資料表的一行資料
      """

      #從一行資料表構造User對象
         if dbrow:
             for attr,value in zip(User.attributes,dbrow):
                 self.__dict__[attr] = value

     def __setitem__(self,key,value):
         if not key in User.attributes:
             raise AttributeError,"%s not acceptable" %key
         self.__dict__[key] = value

     def __getitem__(self,key):
         if not key in self.__dict__:
             raise AttributeError,"%s not found" %key
         return self.__dict__[key]

     def __str__(self):
         return "%(name)s,%(email)s,%(mobile)s" %self.__dict__

 class UserService(object):
     def __init__(self,connection):
         self.connection = connection

     def createUser(self,user):
      """
      建立新使用者

      user - User類執行個體
      """
         insertsql = "insert into user (name,email,mobile,createtime) values (%s,%s,%s,%s)"
         cursor = self.connection.cursor()
         cursor.execute(insertsql,(user.name,user.email,user.mobile,mysql.TimestampFromTicks(time.time())))
         self.connection.commit()
         cursor.close()

     def findAllUsers(self):
      """
      查詢所有使用者
      """
         selectsql = "select * from user"
         cursor = self.connection.cursor()
         cursor.execute(selectsql)
         allusers = []    #方法返回list,其中的元素為每個user對象
         for row in cursor.fetchall():
             allusers.append(User(row))
         cursor.close()
         return allusers

 if __name__ == "__main__":

     connection = mysql.connect(db="misc")
     print connection
     userService = UserService(connection)
     user = User()
     user['name'] = '中文使用者名稱'
     user['email'] = 'snowway.xue@gmail.com'
     user['mobile'] = '13916766714'
     userService.createUser(user)

     for user in userService.findAllUsers():
         print user
     connection.close()