python pymssql - _mssql模块官方文档的翻译

译者注：译者博客(http://blog.csdn.net/lin_strong)，转载请保留这条。此为_mssql模块version2.1.4官方文档的翻译，仅供学习交流使用，请勿用于商业用途。

模块级符号

_mssql. version

见 pymssql. version.

_mssql.VERSION

见 pymssql.VERSION.
这是版本 2.2.0. 中新加的特性。

_mssql. full_version

见 pymssql. full_version.

你可以修改其值以改变全局行为的变量：

_mssql.login_timeout

用秒表示的连接和登录超时时间，默认60秒。

_mssql.min_error_severity

抛出异常的最小错误等级。默认值6在大部分情况下应该是合适的。

函数

_mssql.set_max_connections(number)

设置同一时刻处于开启状态的链接的最大数量。默认25。

_mssql.get_max_connections()

获取同一时刻处于开启状态的链接的最大数量。

MSSQLConnection 类

class _mssql.MSSQLConnection

这个类代表一个MS SQL数据库链接。你可以通过数据库链接发出queries并获取结果。

你可以通过调用_mssql.connect()来创建这个类的一个实例。它接收以下参数。注意，除了位置定位的参数外，你还可以使用关键字参数。

参数名(类型)	说明
server (str)	你想要连接的数据库服务器和实体。如： r’.\SQLEXPRESS’ –本地机器上的SQLEXPRESS实体(仅Windows) r’(local)\SQLEXPRESS’ – 同上(仅Windows) ‘SQLHOST’ – 默认端口上的默认实体(仅Windows) ‘SQLHOST’ – 在freetds.conf中设置的指定端口上的指定实体 (仅Linux/*nix) ‘SQLHOST,1433’ – 指定主机上的指定TCP端口 ’SQLHOST:1433’ – 同上 ’SQLHOST,5000’ – 如果你已经设置了一个实体在端口5000进行监听 ’SQLHOST:5000’ – 同上
user (str)	用于连接的数据库用户
password (str)	用户的密码
charset (str)	连接到数据库所使用的字符集名字
database (str)	链接初始化的数据库。默认情况下，SQL服务器会选择设置中特定用户所对应的默认数据库。
appname (str)	设置链接使用的应用名
port (str)	连接到服务器所使用的TCP端口号
tds_version (str)	使用的TDS协议版本，默认为None
conn_properties	当链接建立时发送给服务器的SQL queries。可以是一个字符串或者另一类可迭代的字符串组。默认值：见下面

SET ARITHABORT ON;
SET CONCAT_NULL_YIELDS_NULL ON;
SET ANSI_NULLS ON;
SET ANSI_NULL_DFLT_ON ON;
SET ANSI_PADDING ON;
SET ANSI_WARNINGS ON;
SET ANSI_NULL_DFLT_ON ON;
SET CURSOR_CLOSE_ON_COMMIT ON;
SET QUOTED_IDENTIFIER ON;
SET TEXTSIZE 2147483647; -- http://msdn.microsoft.com/en-us/library/aa259190%28v=sql.80%29.aspx

版本2.1.1中新特性：conn_properties参数。
版本2.1.1的变化：在2.1.1之前，现在由conn_properties指定的初始化请求不是可定制的，其值硬编码为以上文本。
版本2.1.1中新特性: 能连接Azure。
版本2.2.0的变化: 参数tds_version的默认值变为了None。在版本2.0.0与版本2.1.2之间，其默认值为’7.1’。

警告：

参数tds_version的默认值为None。这意味着：
1 .你不能依赖于旧的默认值’7.1’。
2 .你得做以下其中一件事：
· 通过传递值给这个参数直接指定它的值，或者
· 使用FreeTDS提供的方法配置它
可能这看起来很麻烦，但同时意味着你可以使用pymssql/_mssql完整地配置链接的特性，而不用再管freetds.conf了。从版本2.0.0到版本2.1.2，已经可以设置连接到服务器时请求的TDS协议版本了，但如果没有指定的话，则使用版本7.1。

警告：

FreeTDS在版本0.95中添加了对TDS协议版本7.3的支持。如果你知道由pymssql使用的底层FreeTDS的版本是0.91的话，要小心不要要求TDS7.3，因为这即不会引发任何错误也没有机制阻止你传递这个无效值。

警告：

FreeTDS在版本0.95中添加了对TDS协议版本7.3的支持。如果你知道由pymssql使用的底层FreeTDS的版本更旧的话，要小心不要要求TDS7.3，因为这即不会引发任何错误也没有机制阻止你传递这个无效值。

属性

MSSQLConnection.connected

如果connection对象拥有一个已经打开的数据库链接则为True，否则为False。

MSSQLConnection.charset

传递给_mssql.connect()的字符集名。

MSSQLConnection.identity

返回上一个插入的行的标识值。如果之前的操作没涉及向带有标识列的表中插入行，则返回None。用例 - 假设persons表包含一个标识列加上一个name列：

conn.execute_non_query("INSERT INTO persons (name) VALUES('John Doe')")
print "Last inserted row has id = " + conn.identity

MSSQLConnection.query_timeout

用秒表示的query超时时间，默认为0，0的意思是无限等待。由于DB库的工作方式，设置这个属性会影响所有从当前Python脚本打开的链接(或从技术上说，所有从这个dbinit()实例创建的链接) 。

MSSQLConnection.rows_affected

上一个query所影响的行数。对于SELECT语句，只有在读了所有行后这个值才有意义。

MSSQLConnection.debug_queries

如果设为true，所有query都会在格式化并完成参数引用后打印到stderr，然后才发送给SQL服务器。如果你怀疑格式化或参数引用上出了问题的话，这应该会有帮助。

MSSQLConnection.tds_version

这个链接使用的TDS版本。可能为4.2、5.0、7.0、 7.1、7.2、7.3，或者如果没有探测到任何TDS版本的话为None。
版本2.1.4的变化：为了正确性和一致性，在pymssql2.1.4中，用于指示TDS 7.1的值从8.0改为了7.1。
版本2.1.3的变化：加入了7.3这个选项。

MSSQLConnection.tds_version_tuple

这是版本 2.2.0. 中新加的特性。
元组形式的这条链接使用的TDS 版本，这样在程序中更容易处理(转换、比较)。可能为(4, 2)、 (5, 0)、 (7, 0)、 (7, 1)、 (7, 2)、 (7, 3) 或者如果没有探测到任何TDS版本的话为None。
版本2.1.3的变化：加入了7.3这个选项。

方法

MSSQLConnection.cancel()

取消所有从上个SQL操作以来挂起的结果。可以在同一行上多次调用。这种情况下不会抛出异常。

MSSQLConnection.close()

关闭链接并释放所有内存。可以在同一行上多次调用。这种情况下不会抛出异常。

MSSQLConnection.execute_query(query_string)
MSSQLConnection.execute_query(query_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。
在调用这个方法之后，你可以迭代这个链接对象来获取query返回的行。
你可以使用Python格式化，所有值都会被合理地引用。
这个方法应该用于会返回结果的query，即SELECT。

MSSQLConnection.execute_non_query(query_string)
MSSQLConnection.execute_non_query(query_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库。它的结果(如果有)会被抛弃。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。
你可以使用Python格式化，所有值都会被合理地引用。
这个方法很适合INSERT、 UPDATE、 DELETE和数据定义语言(Data Definition Language)，即当你想改变你的数据库的schema时。

MSSQLConnection.execute_scalar(query_string)
MSSQLConnection.execute_scalar(query_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库，然后返回结果的首行首列。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。
你可以使用Python格式化，所有值都会被合理地引用。
如果你的query只返回一个值的话，这个方法就很有用了，如下例所示。这个方法的工作方式相当于iter(conn).next()[0]。如果还有剩下的行的话，你还是可以在调用这条命令后进行迭代。

count = conn.execute_scalar("SELECT COUNT(*) FROM employees")

MSSQLConnection.execute_row(query_string)
MSSQLConnection.execute_row(query_string, params)

这个方法发送一条query给这个对象实例所连接的MS SQL数据库，然后返回结果的首行。当失败时会抛出一条异常。如果在执行这个命令之前有挂起的结果或者行，它们会被默默地丢掉。
你可以使用Python格式化，所有值都会被合理地引用。
如果你的query只返回一行并且不想或不需要迭代链接对象的话，这个方法就很有用了。这个方法的工作方式相当于iter(conn).next()。如果还有剩下的行的话，你还是可以在调用这条命令后进行迭代。

empinfo = conn.execute_row("SELECT * FROM employees WHERE empid=10")

MSSQLConnection.get_header()

这个方法是一个基础函数，不需要由你的代码调用。它获取遵从Python DB-API的头信息。返回一个描述当前结果头的一个有7个元素的元组。只填充了名字和遵从的DB-API类型，剩下的都是None，这是规范许可的。

MSSQLConnection.init_procedure(name)

创建一个MSSQLStoredProcedure对象，用于调用名字由name指定的存储过程。

MSSQLConnection.nextresult()

移到下一个结果集，跳过所有挂起的结果。这个方法获取并抛弃当前操作剩下的所有行，然后移到下一个结果(如果有的话)。如果有下一个结果集，则返回True，否则返回None。当失败时会抛出一条异常。

MSSQLConnection.select_db(dbname)

这个函数把指定数据库变为当前数据库。当失败时会抛出一条异常。

MSSQLConnection. iter()
MSSQLConnection.next()

这是版本 2.1.0. 中新加的特性。
这两方法实现了Python迭代器协议。很可能你不会直接，而是间接使用迭代器调用它。

MSSQLConnection.set_msghandler(handler)

这是版本 2.1.1. 中新加的特性。

这个方法为链接设置一个消息handler函数，这样客户端就可以访问从服务器返回的信息了。
传递给这个方法的消息handler函数的签名应该是这样的：

def my_msg_handler(msgstate, severity, srvname, procname, line, msgtext):
    # The body of the message handler.

msgstate、severity和line是整型值；srvname、procname和msgtext是字符串.

MSSQLStoredProcedure 类

class _mssql.MSSQLStoredProcedure

这个类代表一个存储过程。你可以通过调用MSSQLConnection对象上的init_procedure()方法来创建这个类的一个实例。

属性

MSSQLStoredProcedure.connection

底层的MSSQLConnection对象。

MSSQLStoredProcedure.name

这个对象代表的存储过程的名字。

MSSQLStoredProcedure.parameters

绑定到这个存储过程的参数们。

方法

MSSQLStoredProcedure.bind(value, dbtype, name=None, output=False, null=False, max_length=-1)

这个方法绑定一个参数到存储过程。value和dbtype是强制的，剩下的都是可选的。

参数名	说明
value	存储在参数中的值
dbtype	以下之一: SQLBINARY、SQLBIT、SQLBITN、SQLCHAR、SQLDATETIME、SQLDATETIM4、SQLDATETIMN、SQLDECIMAL、SQLFLT4、SQLFLT8、SQLFLTN、SQLIMAGE、SQLINT1、SQLINT2、SQLINT4、SQLINT8、SQLINTN、SQLMONEY、SQLMONEY4、SQLMONEYN、SQLNUMERIC、SQLREAL、SQLTEXT、SQLVARBINARY、SQLVARCHAR、SQLUUID
name	参数的名字。需要为"@name"这样的形式。
output	参数的方向。True表示是一个输出参数，即在存储过程执行后它返回一个值(在SQL DDL中是通过一个"output"后缀来声明它们的，如"@aname varchar(10) output")
null	Boolean类型。表明这个输入参数的值是NULL
max_length	从存储过程返回的这个参数的最大数据长度

MSSQLStoredProcedure.execute()

执行这个存储过程。

模块级异常

异常继承树：

MSSQLException
|
+-- MSSQLDriverException
|
+-- MSSQLDatabaseException

exception _mssql.MSSQLDriverException

只要_mssql内部发生了问题，就会抛出MSSQLDriverException – 如数据结构的内存不足等。

exception _mssql.MSSQLDatabaseException

只要数据库发生了问题，就会抛出MSSQLDatabaseException – 如query语法错误、无效对象名等。这种情况下，你可以使用以下属性来获得错误细节：
number：错误码，是由SQL服务器返回的。
severity：严重级别，是由SQL服务器返回的。如果这个属性的值低于_mssql.min_error_severity的值，这个错误会被忽略，不会抛出异常。
state：第三个错误码，是由SQL服务器返回的。
message：错误信息，是由SQL服务器返回的。