譯者注：譯者部落格(http://blog.csdn.net/lin_strong)，轉載請保留這條。此為pymssql模組version2.1.4官方文件的翻譯，僅供學習交流使用，請勿用於商業用途。

模組級符號

pymssql.version

Unicode常量表示的pymssql版本。如：u"2.1.1", u"2.2.0"

pymssql.VERSION

元組形式的pymssql版本，這樣在程式中更容易處理(轉換、比較)。如：(2, 1, 1), (2, 2, 0) 這是版本 2.2.0. 中新加的特性。

pymssql.full_version

Unicode常量表示的pymssql版本，不同的是，它包括了字尾(PEP 440)。如：u"2.1.0.dev2", u"2.2.0.dev"

以下是DB-API 2.0規範中要求的常量：

pymssql.apilevel

‘2.0’ – pymssql 儘可能地遵從 DB-API 2.0.

pymssql.paramstyle

‘pyformat’ – pymssql 使用擴充套件的python格式程式碼.

pymssql.threadsafety

1 – 執行緒可以共享模組, 但不能共享連線。

函式

pymssql.connect(server=’.’, user=None, password=None, database=’’, timeout=0, login_timeout=60, charset=‘UTF-8’, as_dict=False, host=’’, appname=None, port=‘1433’, conn_properties=None, autocommit=False, tds_version=None)

一個構造器(Constructor)，用於建立到資料庫的連結。返回一個Connection物件。

注意：大部分情況下你應該會更傾向於使用關鍵字引數，而不是位置確定的引數。

引數說明：

警告：

目前，設定timeout或login_timeout會有一個過程級的影響，因為用於實現超時的FreeTDS db-lib API函式是全域性效果的。

版本2.1.1中新特性: 能連線Azure。 版本2.1.1中新特性: conn_properties引數。 版本2.1.1中新特性: autocommit引數。 版本2.1.2中新特性: tds_version引數。 版本2.2.0的變化: 引數tds_version的預設值變為了None。在版本2.1.2中，其預設值為’7.1’。

警告：

引數tds_version的預設值為None。這意味著： 你不能依賴於舊的預設值’7.1’。現在，你得做以下其中一件事： · 通過傳遞值給這個引數直接指定它的值，或者 · 使用FreeTDS提供的方法配置它 可能這看起來很麻煩，但同時意味著你可以在Python程式碼中完整地配置連結的特性，而不用再管freetds.conf了。在版本2.1.1及之前版本，沒法控制TDS協議版本；在版本2.1.2中，可以設定它。如果沒有指定的話，則使用版本7.1。

警告：

FreeTDS在版本0.95中添加了對TDS協議版本7.3的支援。如果你知道由pymssql使用的底層FreeTDS的版本是0.91的話，要小心不要要求TDS7.3，因為這即不會引發任何錯誤也沒有機制阻止你傳遞這個無效值。

警告：

FreeTDS在版本0.95中添加了對TDS協議版本7.3的支援。如果你知道由pymssql使用的底層FreeTDS的版本更舊的話，要小心不要要求TDS7.3，因為這即不會引發任何錯誤也沒有機制阻止你傳遞這個無效值。

pymssql.get_dbversion()

封裝了DB庫的dbversion()函式，這個函式會以字串形式返回FreeTDS的版本(DB-Lib的實際版本)。如：“freetds v0.95”。 不幸的是： 1 )返回的值沒有說明更小的修訂號(如：v0.95.50) 2 )它的資料型別使得它難以比較或程式設計處理 3 )在FreeTDS發行歷史中，它並沒有被堅持更新 這是pymssql對於DB-API 2.0的擴充套件

pymssql.set_max_connections(number)

設定允許同時連線到資料庫的連結的最大數量。預設是25。 這是pymssql對於DB-API 2.0的擴充套件

pymssql.get_max_connections()

獲取允許同時連線到資料庫的連結的最大數量。 這是pymssql對於DB-API 2.0的擴充套件

pymssql.set_wait_callback(wait_callback_callable)

版本2.1.0. 中的新特性

這個特性使得pymssql能用於協作的多工系統，使其在等待伺服器響應時呼叫一個回撥函式。

傳遞的可呼叫的回撥函式應該接受一個引數：連線到伺服器的網路socket的檔案描述符/handle，所以其簽名應該是這樣的

def wait_callback_callable(read_fileno):
    #...
    pass

它的程式碼體應該呼叫你所使用的多工框架的適當API，以使得當socket中沒有輸入資料時，當前greenlet主動交出CPU時間。

這是pymssql對於DB-API 2.0的擴充套件

Connection類

class pymssql.Connection(user, password, host, database, timeout, login_timeout, charset, as_dict)

這個類代表了一條MS SQL 資料庫連結。你可以通過呼叫構建器pymssql.connect()來建立這個類的一個例項。

屬性

這個類沒有有用的屬性和資料成員。

方法

Connection.autocommit(status)

status是一個boolean值。這個方法返回autocommit模式是否啟用 預設的，autocommit模式是關閉的，這意味著如果要在資料庫中儲存變化的資料，必須明確地提交每個會話。 你可以啟用autocommit模式，這樣，每個操作一旦成功就會提交自身。 這是pymssql對於DB-API 2.0的擴充套件

Connection.close()

關閉連結。

Connection.cursor()

返回一個Cursor物件，這可以用於傳送請求並從資料庫獲取結果。

Connection.commit()

提交當前會話。你必須呼叫這個方法來儲存你的資料，如果autocommit為預設的False。

Connection.rollback()

回滾當前會話。

Cursor類

class pymssql.Cursor

這個類代表一個Cursor(Python DB-API規範的術語)，其用於向資料庫傳送請求並獲取結果。通過呼叫一個開啟的Connection連結物件的cursor()方法來建立Cursor例項。

屬性

Cursor.rowcount

返回上一次操作中受影響的行數。對於SELECT語句，只有在所有行都被fetched後它才會返回有用的資訊。

Cursor.connection

這是對於DB-API規範的擴充套件。返回對建立cursor的Connection物件的引用。

Cursor.lastrowid

這是對於DB-API規範的擴充套件。返回上一個插入的行的標識值。如果之前的操作沒有向表中插入行，返回None。

Cursor.rownumber

這是對於DB-API規範的擴充套件。返回在當前結果集中，基於0的當前索引值。

方法

Cursor.close()

關閉cursor。之後這個cursor就不可用了。

Cursor.execute(operation)Cursor.execute(operation, params)

operation是一個字串；而params，如果用到了的話，是一個簡單的值、元組、字典或None。 對資料庫執行operation，可能會用給的值替換佔位符。比起手動連線字串，這應該是更受歡迎的建立SQL命令的方法，手動連線字串有受到SQL注入式攻擊的風險。這個方法的格式化方式接近於Python內建的方式。但是，由於格式化和型別轉換是內部進行的，只支援%s和%d佔位符。這兩個佔位符在功能上與Python內建的是一樣的。 如果你給params傳遞的是字典的話，則支援關鍵字佔位符。 如果你呼叫了只帶一個引數的execute()，%符號就喪失了它的特殊意義，這樣你就可以如平常一樣在查詢字串中使用它，比如用在LIKE操作符中。 在呼叫execute()後，你必須呼叫Connection.commit()，否則資料不會被存到資料庫中。如果你想要自動完成這件事的話，你也可以設定connection.autocommit。這個行為是DB-API要求的，如果你不喜歡的話，那就改用_mssql模組吧。

Cursor.executemany(operation, params_seq)

operation是一個字串；而params_seq是一個元組的序列(比如一個列表)。為引數序列中的每一個元素重複執行operation這一資料庫操作。

Cursor.fetchone()

獲取查詢結果的下一行，返回一個元組，或者如果as_dict為True的話返回一個字典。如果沒有更多可獲取的資料了，返回None。如果前一個對execute*() 的呼叫沒有產生任何結果集或者還沒有提交呼叫，則丟擲OperationalError (PEP 249#operationalerror)。

Cursor.fetchmany(size=None)

獲取下一批查詢結果，返回一個元組的列表，或者如果as_dict為True的話返回一個字典。如果沒有更多可獲取的資料了，返回一個空列表。你可以使用size引數調整之後每一批獲取的行數，這個值會一直保留使用。如果前一個對execute*() 的呼叫沒有產生任何結果集或者還沒有提交呼叫，則丟擲OperationalError (PEP 249#operationalerror)。

Cursor.fetchall()

獲取查詢結果的所有剩餘行，返回一個元組的列表，或者如果as_dict為True的話返回一個字典。如果沒有更多可獲取的資料了，返回一個空列表。如果前一個對execute*() 的呼叫沒有產生任何結果集或者還沒有提交呼叫，則丟擲OperationalError (PEP 249#operationalerror)。

Cursor.nextset()

這個方法使cursor跳到下一個可得的結果集，拋棄當前集的所有剩下的行。如果有下一個結果集的話，返回True，否則返回None。

Cursor.iter()Cursor.next()

這個方法實現了Python迭代器協議。很可能你不會直接，而是間接使用迭代器呼叫它。 這是pymssql對於DB-API 2.0的擴充套件

Cursor.setinputsizes()Cursor.setoutputsize()

這兩方法啥都不做，這是DB-API規範同意的。

異常

exception pymssql.StandardError

異常繼承樹的根。

exception pymssql.Warning

在重要的警告時丟擲，如當插入時發生資料截斷。StandardError的子類。

exception pymssql.Error

其他所有錯誤異常的基類。你可以用它來通過一個except語句捕獲所有錯誤。StandardError的子類。

exception pymssql.InterfaceError

當發生與資料庫介面相關而不是資料庫本身相關的錯誤時丟擲。Error的子類。

exception pymssql.DatabaseError

當發生與資料庫相關的錯誤時丟擲。Error的子類。

exception pymssql.DataError

當發生與處理資料相關的錯誤時丟擲，如除以0、數值超出範圍等。DatabaseError的子類。

exception pymssql.OperationalError

當發生與資料庫運作相關但不應該是由程式設計師操作導致的錯誤時丟擲，如意外的連線中斷、沒有找到資料來源名字，無法處理一個會話、處理過程中的記憶體分配錯誤等。DatabaseError的子類。

exception pymssql.IntegrityError

當資料庫的關係完整性受到影響時丟擲，如外來鍵檢查失敗。DatabaseError的子類。

exception pymssql.InternalError

當資料庫遇到內部錯誤時丟擲，如cursor不再有效、會話不同步。DatabaseError的子類。

exception pymssql.ProgrammingError

當傳送程式設計錯誤時丟擲，如沒有發現表或表已存在、SQL語法錯誤、指定了錯誤數量的引數等。DatabaseError的子類。

exception pymssql.NotSupportedError

當使用了資料庫不支援的方法或資料庫API，如在一個不支援會話或者會話已關閉的連結上要求rollback()。DatabaseError的子類。

exception pymssql.ColumnsWithoutNamesError

當開啟連結時指定as_dict=True，然後呼叫 Cursor.execute() 時發現結果中沒有列名時丟擲。InterfaceError的子類。

注意：

ColumnsWithoutNamesError不是PEP-249授權的異常，而是一個pymssql擴充套件。