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

古城微笑少年丶 2022-05-10 11:24 342阅读 0赞

译者注：译者博客([http://blog.csdn.net/lin\_strong][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对象。

注意：大部分情况下你应该会更倾向于使用关键字参数，而不是位置确定的参数。

参数说明：

<table> 
 <thead> 
  <tr> 
   <th align="center">参数名(类型)</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="center">server (str)</td> 
   <td align="left">数据库主机</td> 
  </tr> 
  <tr> 
   <td align="center">user (str)</td> 
   <td align="left">用于连接的数据库用户</td> 
  </tr> 
  <tr> 
   <td align="center">password (str)</td> 
   <td align="left">用户的密码</td> 
  </tr> 
  <tr> 
   <td align="center">database (str)</td> 
   <td align="left">链接初始化的数据库。默认情况下，SQL服务器会选择设置中特定用户所对应的默认数据库。</td> 
  </tr> 
  <tr> 
   <td align="center">timeout (int)</td> 
   <td align="left">用秒表示的查询超时时间，默认为0(无超时)</td> 
  </tr> 
  <tr> 
   <td align="center">login_timeout (int)</td> 
   <td align="left">用秒表示的连接与登陆超时时间，默认为60</td> 
  </tr> 
  <tr> 
   <td align="center">charset (str)</td> 
   <td align="left">连接到数据库所使用的字符集</td> 
  </tr> 
  <tr> 
   <td align="center">as_dict (bool)</td> 
   <td align="left">是否每一行作为字典而不是元组返回。你可以使用基于0的索引或者使用名字来访问列。</td> 
  </tr> 
  <tr> 
   <td align="center">host (str)</td> 
   <td align="left">你想要连接的数据库主机或实体。如：<br> r’.\SQLEXPRESS’ –本地机器上的SQLEXPRESS实体(仅Windows)<br>r’(local)\SQLEXPRESS’ – 同上(仅Windows)<br>‘SQLHOST’ – 默认端口上的默认实体(仅Windows) <br>‘SQLHOST’ – 在freetds.conf中设置的指定端口上的指定实体 (仅Linux/*nix)<br>‘SQLHOST,1433’ – 指定主机上的指定TCP端口<br>’SQLHOST:1433’ – 同上<br>’SQLHOST,5000’ – 如果你已经设置了一个实体在端口5000进行监听<br>’SQLHOST:5000’ – 同上<br>’.’ (本地主机)默认设置，如果没有指定host。</td> 
  </tr> 
  <tr> 
   <td align="center">appname (str)</td> 
   <td align="left">设置链接使用的应用名</td> 
  </tr> 
  <tr> 
   <td align="center">port (str)</td> 
   <td align="left">连接到服务器所使用的TCP端口号</td> 
  </tr> 
  <tr> 
   <td align="center">conn_properties</td> 
   <td align="left">当链接建立时发送给服务器的SQLqueries。可以是一个字符串或者另一类可迭代的字符串组。默认值：见_mssql.connect()</td> 
  </tr> 
  <tr> 
   <td align="center">autocommit (bool)</td> 
   <td align="left">是否使用默认自动提交模式</td> 
  </tr> 
  <tr> 
   <td align="center">tds_version (str)</td> 
   <td align="left">使用的TDS协议版本</td> 
  </tr> 
 </tbody> 
</table>

警告：

目前，设置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