pythonpymssql-pymssql模块官⽅⽂档的翻译
译者注：译者博客()，转载请保留这条。此为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 – 线程可以共享模块, 但不能共享连接。
函数
charset=‘UTF-8’, as_dict=False, host=’’, appname=None, port=‘1433’, conn_properties=None,
autocommit=False, tds_version=None)
⼀个构造器(Constructor)，⽤于创建到数据库的链接。返回⼀个Connection对象。
注意：⼤部分情况下你应该会更倾向于使⽤关键字参数，⽽不是位置确定的参数。
参数说明：
参数名(类型)说明
server (str)数据库主机
user (str)⽤于连接的数据库⽤户
password (str)⽤户的密码
database (str)链接初始化的数据库。默认情况下，SQL服务器会选择设置中特定⽤户所对应的默认数据库。
timeout (int)⽤秒表⽰的查询超时时间，默认为0(⽆超时)
login_timeout (int)⽤秒表⽰的连接与登陆超时时间，默认为60
charset (str)连接到数据库所使⽤的字符集
as_dict (bool)是否每⼀⾏作为字典⽽不是元组返回。你可以使⽤基于0的索引或者使⽤名字来访问列。
host (str)你想要连接的数据库主机或实体。如：
r’.\SQLEXPRESS’ –本地机器上的SQLEXPRESS实体(仅Windows)
r’(local)\SQLEXPRESS’ – 同上(仅Windows)
‘SQLHOST’ – 默认端⼝上的默认实体(仅Windows)
‘SQLHOST’ – 在f中设置的指定端⼝上的指定实体 (仅Linux/*nix)‘SQLHOST,1433’ – 指定主机上的指定TCP端⼝
’SQLHOST:1433’ – 同上
’SQLHOST,5000’ – 如果你已经设置了⼀个实体在端⼝5000进⾏监听
’SQLHOST,5000’ – 如果你已经设置了⼀个实体在端⼝5000进⾏监听
’SQLHOST:5000’ – 同上
参数名(类型)说明
’.’ (本地主机)默认设置，如果没有指定host。
appname (str)设置链接使⽤的应⽤名
port (str)连接到服务器所使⽤的TCP端⼝号
conn_properties当链接建⽴时发送给服务器的SQLqueries。可以是⼀个字符串或者另⼀类可迭代的字符串组。默认值：见_t() autocommit (bool)是否使⽤默认⾃动提交模式
tds_version (str)使⽤的TDS协议版本
警告：
⽬前，设置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代码中完整地配置链接的特性，⽽不⽤再管f了。在版本
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，因为这即不会引发任何错误也没有机制阻⽌你传递这个⽆效值。
<_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的扩展
<_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 数据库链接。你可以通过调⽤构建器t()来创建这个类的⼀个实例。
属性
这个类没有有⽤的属性和数据成员。
⽅法
Connection.autocommit(status)
status是⼀个boolean值。这个⽅法返回autocommit模式是否启⽤
默认的，autocommit模式是关闭的，这意味着如果要在数据库中保存变化的数据，必须明确地提交每个会话。
你可以启⽤autocommit模式，这样，每个操作⼀旦成功就会提交⾃⾝。
这是pymssql对于DB-API 2.0的扩展
Connection.close()
关闭链接。
Connection.cursor()
返回⼀个Cursor对象，这可以⽤于发送请求并从数据库获取结果。
Connectionmit()
提交当前会话。你必须调⽤这个⽅法来保存你的数据，如果autocommit为默认的False。
回滚当前会话。
Cursor类
class pymssql.Cursor
这个类代表⼀个Cursor(Python DB-API规范的术语)，其⽤于向数据库发送请求并获取结果。通过调⽤⼀个打开的
Connection链接对象的cursor()⽅法来创建Cursor实例。
属性
返回上⼀次操作中受影响的⾏数。对于SELECT语句，只有在所有⾏都被fetched后它才会返回有⽤的信息。
这是对于DB-API规范的扩展。返回对创建cursor的Connection对象的引⽤。
Cursor.lastrowid
这是对于DB-API规范的扩展。返回上⼀个插⼊的⾏的标识值。如果之前的操作没涉及向带有标识列的表中插⼊⾏，则返回None。
这是对于DB-API规范的扩展。返回在当前结果集中，基于0的当前索引值。
⽅法
Cursor.close()
关闭cursor。之后这个cursor就不可⽤了。
operation是⼀个字符串；⽽params，如果⽤到了的话，是⼀个简单的值、元组、字典或None。
对数据库执⾏operation，可能会⽤给的值替换占位符。⽐起⼿动连接字符串，这应该是更受欢迎的创建SQL命令的⽅法，⼿动连接字符串有受到SQL注⼊式攻击的风险。这个⽅法的格式化⽅式接近于Python内建的⽅式。但是，由于格式化和类型转换是内部进⾏的，只⽀持%s和%d占位符。这两个占位符在功能上与Python内建的是⼀样的。
如果你给params传递的是字典的话，则⽀持关键字占位符。
如果你调⽤了只带⼀个参数的execute()，%符号就丧失了它的特殊意义，这样你就可以如平常⼀样在查询字符串中使⽤它，⽐如⽤在LIKE操作符中。
在调⽤execute()后，你必须调⽤Connectionmit()，否则数据不会被存到数据库中。如果你想要⾃动完成这件事的话，你也可以设置connection.autocommit。这个⾏为是DB-API要求的，如果你不喜欢的话，那就改⽤_mssql模块吧。
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跳到下⼀个可得的结果集，抛弃当前集的所有剩下的⾏。如果有下⼀个结果集的话，返回True，否则返回None。
Cursor. iter()
<()
这个⽅法实现了Python迭代器协议。很可能你不会直接，⽽是间接使⽤迭代器调⽤它。
这是pymssql对于DB-API 2.0的扩展
Cursor.setinputsizes()
Cursor.setoutputsize()
python官方文档中文版这两⽅法啥都不做，这是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，然后调⽤ ute() 时发现结果中没有列名时抛出。InterfaceError的⼦类。
注意：
ColumnsWithoutNamesError不是PEP-249授权的异常，⽽是⼀个pymssql扩展。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论