SqlAlchemy 2.0 中文文档（五十八）（7）

SqlAlchemy 2.0 中文文档（五十八）（6）https://developer.aliyun.com/article/1563138

2.0.20

发布日期：2023 年 8 月 15 日

orm

• [orm] [用例]
  实现了 ORM 启用的 DML 语句的“RETURNING '*”用例。这将在尽可能多的情况下呈现，并返回未过滤的结果集，但不支持具有特定列呈现要求的多参数“ORM 批量 INSERT”语句。
  参考资料：#10192
  
• [orm] [错误]
  修复了阻止某些形式的 ORM“注释”对使用Select.join()对关系目标进行连接的子查询进行的问题。在特殊情况下使用这些注释，例如在PropComparator.and_()和其他 ORM 特定场景中使用子查询时。
  此更改也被回溯到：1.4.50
  参考资料：#10223
  
• [orm] [错误]
  修复了 ORM 从具有同名列的超类和子类的连接继承模型中生成 SELECT 时出现问题的问题，当生成 RECURSIVE 列列表时，不会发送正确的列名列表到CTE构造。。
  参考资料：#10169
  
• [orm] [错误]
  修复了一个相当严重的问题，即传递给Session.execute()的执行选项以及本身 ORM 执行的语句的执行选项将不会传递给 eager loaders，例如 selectinload()、immediateload() 和 sqlalchemy.orm.subqueryload()，从而使得禁用单个语句的缓存或者为单个语句使用 schema_translate_map 等操作变得不可能，以及使用用户自定义执行选项。已经做出了更改，即现在所有对于 Session.execute() 的用户界面执行选项都将传递到附加的 loaders 中。
  作为这一更改的一部分，对于导致禁用缓存的“过度深层” eager loaders 的警告现在可以通过向 Session.execute() 发送 execution_options={"compiled_cache": None} 来在每个语句的基础上消除，这将禁用该范围内所有语句的缓存。
  参考文献：#10231
  
• 【orm】【错误】
  修复了 ORM 内部克隆的问题，该克隆用于像 Comparator.any() 这样的表达式，以生成相关 EXISTS 构造，会干扰 SQL 编译器的“笛卡尔积警告”特性，导致 SQL 编译器在语句的所有元素都正确连接时发出警告。
  参考文献：#10124
  
• 【orm】【错误】
  修复了lazy="immediateload"加载策略在某些情况下会将内部加载令牌放入 ORM 映射属性中的问题，例如在递归自引用加载时不应发生加载。作为这一更改的一部分，lazy="immediateload"策略现在与其他 eager loaders 一样尊重 relationship.join_depth 参数，对于自引用 eager 加载，如果将其设置为未设置或设置为零，将不会发生自引用 immediateload，如果将其设置为大于零的值，将会立即加载直到给定的深度。
  参考文献：#10139
  
• 【orm】【错误】
  修复了一个问题，即基于字典的集合（如attribute_keyed_dict()）未正确地完全序列化/反序列化，导致在反序列化后尝试突变此类集合时出现问题。
  参考文献：#10175
  
• [orm] [bug]
  修复了一个问题，即从另一个急切加载器使用aliased()对于连接的继承子类链的超类的本地列失败时，链接load_only()或其他通配符使用defer()。
  参考文献：#10125
  
• [orm] [bug]
  修复了一个问题，其中启用 ORM 的select()结构不会呈现仅通过Select.add_cte()方法添加的任何 CTEs，而这些 CTEs 在语句中没有被引用。
  参考文献：#10167
  

示例

• [examples] [bug]
  dogpile_caching 示例已更新为 2.0 样式的查询。在“缓存查询”逻辑内部，添加了一个条件来区分Query和select()在执行无效操作时。
  

引擎

• [engine] [bug]
  修复了一个严重问题，即将create_engine.isolation_level设置为AUTOCOMMIT（而不是使用Engine.execution_options()方法），如果临时选择了替代隔离级别，则会导致无法将“autocommit”恢复到池化连接中，使用Connection.execution_options.isolation_level。
  参考文献：#10147
  

sql

• [sql] [bug]
  修复了一个问题，即对Column或其他ColumnElement进行反序列化会失败恢复正确的“比较器”对象，该对象用于生成特定于类型对象的 SQL 表达式。
  此更改也已回溯至：1.4.50
  参考文献：#10213
  

类型

• [typing] [usecase]
  添加了新的仅用于类型的实用函数Nullable()和NotNullable()，用于分别将列或 ORM 类的类型定义为可空或不可空。这些函数在运行时不起作用，返回不变的输入。
  参考：#10173
  
• [typing] [bug]类型改进：

• 当使用无返回的 DML 时，对于某些形式的Session.execute()，将返回CursorResult
  
• 修正了Query.with_for_update.of参数的类型，该参数在Query.with_for_update()中被修复为正确的类型。
  
• 改进了某些 DML 方法中使用的 _DMLColumnArgument 类型，用于传递列表达式
  
• 给 literal() 添加了重载，以便在未提供literal.type_参数时推断出返回类型为 BindParameter[NullType]
  
• 给 ColumnElement.op() 添加了重载，以便在未提供ColumnElement.op.return_type时推断出的类型为 Callable[[Any], BinaryExpression[Any]]
  
• 给 ColumnElement.__add__() 添加了缺失的重载
  

• Pull request 由 Mehdi Gmira 提供。
  参考：#9185
  
• [typing] [bug]
  修复了Session和AsyncSession方法中的问题，例如Session.connection()，其中Session.connection.execution_options参数被硬编码为不面向用户的内部类型。
  参考：#10182
  

asyncio

• [asyncio] [usecase]
  添加了新方法 AsyncConnection.aclose() 作为 AsyncConnection.close() 的同义词，以及 AsyncSession.aclose() 作为 AsyncSession.close() 的同义词，添加到 AsyncConnection 和 AsyncSession 对象中，以提供与 Python 标准库 @contextlib.aclosing 构造的兼容性。拉取请求由 Grigoriev Semyon 提供。
  参考：#9698
  

mysql

• [mysql] [usecase]
  由于 aiomysql 方言再次得到维护，已更新 aiomysql 方言。重新添加到 ci 测试中，使用版本 0.2.0。
  此更改也 回溯 到：1.4.50
  

orm

• [orm] [usecase]
  实现了 ORM 启用的 DML 语句的 “RETURNING ‘*’” 用例。这将尽可能地呈现，并返回未经过滤的结果集，但不支持具有特定列呈现要求的多参数 “ORM 批量插入” 语句。
  参考：#10192
  
• [orm] [bug]
  修复了一些形式的 ORM “注释” 无法对使用 Select.join() 进行的子查询进行注释的根本问题，这些子查询在特殊情况下使用，比如在 PropComparator.and_() 和其他 ORM 特定场景中使用。
  此更改也 回溯 到：1.4.50
  参考：#10223
  
• [orm] [bug]
  修复了 ORM 从具有同名列的超类和子类的联合继承模型生成 SELECT 时，当生成递归列列表时，某种方式未正确发送列名列表到 CTE 构造的问题，当递归列列表被生成时。
  参考：#10169
  
• [orm] [bug]
  修复了将执行选项传递给Session.execute()以及 ORM 执行语句本身的执行选项不会传播到selectinload()、immediateload()和sqlalchemy.orm.subqueryload()等急切加载器的问题，使得无法禁用单个语句的缓存或对单个语句使用schema_translate_map，以及使用用户自定义执行选项。已经进行了更改，所有针对Session.execute()的用户可见执行选项都将传播到其他加载器。
  作为这一变化的一部分，可以通过向Session.execute()发送execution_options={"compiled_cache": None}来在每个语句的基础上消除“过度深入”急切加载器导致缓存被禁用的警告，这将禁用该范围内所有语句的缓存。
  参考：#10231
  
• [orm] [bug]
  修复了内部克隆在 ORM 中用于生成类似Comparator.any()的表达式以产生相关的 EXISTS 结构时会干扰 SQL 编译器的“笛卡尔积警告”功能的问题，导致 SQL 编译器在所有语句元素正确连接时发出警告。
  参考：#10124
  
• [orm] [bug]
  修复了lazy="immediateload"加载策略在某些情况下会将内部加载标记放入 ORM 映射属性中的问题，例如在递归自引用加载中不应发生加载的情况。作为这一变化的一部分，lazy="immediateload"策略现在以与其他急切加载器相同的方式尊重relationship.join_depth参数用于自引用急切加载，其中将其未设置或设置为零将导致自引用的 immediateload 不会发生，将其设置为一个或更大的值将会 immediateload 直到给定深度。
  参考：#10139
  
• [orm] [bug]
  修复了诸如attribute_keyed_dict()之类基于字典的集合在反序列化时未能完全正确地 pickle/unpickle 的问题，导致在反序列化后尝试修改此类集合时出现问题。
  参考：#10175
  
• [orm] [bug]
  修复了从另一个急切加载器使用aliased()针对连接继承子类的情况下，链式调用load_only()或其他通配符使用defer()会导致对于超类本地列无法生效的问题。
  参考：#10125
  
• [orm] [bug]
  修复了 ORM 启用的select()构造不会呈现仅通过Select.add_cte()方法添加的任何 CTE，而这些 CTE 在语句中没有被引用。
  参考：#10167
  

examples

• [examples] [bug]
  dogpile_caching 示例已更新为 2.0 风格的查询。在“缓存查询”逻辑中，添���了一个条件来区分在执行无效操作时Query和select()之间的区别。
  

engine

• [engine] [bug]
  修复了将create_engine.isolation_level设置为AUTOCOMMIT（而不是使用Engine.execution_options()方法）会导致如果使用Connection.execution_options.isolation_level临时选择了替代隔离级别，则无法将“autocommit”恢复到池化连接的关键问题。
  参考：#10147
  

sql

• [sql] [bug]
  修复了反序列化Column或其他ColumnElement时无法恢复正确的“比较器”对象的问题，该对象用于生成特定于类型对象的 SQL 表达式。
  此更改也回溯到：1.4.50
  参考：#10213
  

typing

• [typing] [usecase]
  添加了新的仅用于类型的实用函数Nullable()和NotNullable()，用于分别将列或 ORM 类类型化为可空或不可空。这些函数在运行时不起作用，返回不变的输入。
  参考：#10173
  
• [typing] [bug]类型改进：

• 一些形式的Session.execute()中返回了CursorResult，其中使用了没有返回的 DML
  
• 修正了Query.with_for_update.of参数的类型，在Query.with_for_update()内部。
  
• 对一些 DML 方法使用的_DMLColumnArgument类型进行了改进，以传递列表达式。
  
• 添加了对literal()的重载，以便推断返回类型为BindParameter[NullType]，其中literal.type_参数为 None
  
• 添加了对ColumnElement.op()的重载，以便在未提供ColumnElement.op.return_type时推断类型为Callable[[Any], BinaryExpression[Any]]。
  
• 添加了对ColumnElement.__add__()的缺失重载
  

• 拉取请求由 Mehdi Gmira 提供。
  参考：#9185
  
• [typing] [bug]
  修复了Session和AsyncSession方法中的问题，例如Session.connection()，其中Session.connection.execution_options参数被硬编码为不是面向用户的内部类型。
  参考：#10182
  

asyncio

• [asyncio] [usecase]
  新增了AsyncConnection.aclose()作为AsyncConnection.close()的同义词，以及AsyncSession.aclose()作为AsyncSession.close()的同义词，用于AsyncConnection和AsyncSession对象，以与 Python 标准库@contextlib.aclosing构造兼容。感谢 Grigoriev Semyon 提交的拉取请求。
  参考：#9698
  

mysql

• [mysql] [usecase]
  更新了 aiomysql 方言，因为该方言似乎再次得到维护。重新使用版本 0.2.0 进行 ci 测试。
  此更改也已回溯至：1.4.50
  

2.0.19

发布日期：2023 年 7 月 15 日

orm

• [orm] [bug]
  修复了直接设置关系集合的问题，其中新集合中的对象已经存在时，不会触发该对象的级联事件，导致如果该对象尚未存在，则不会添加到Session中。这与#6471类似，并且由于在 2.0 系列中删除了cascade_backrefs，这个问题更加明显。作为#6471的一部分，现在还为已存在于相同集合的批量设置中的现有成员触发AttributeEvents.append_wo_mutation()事件。
  参考：#10089
  
• [orm] [bug]
  修复了通过 backref 与未合并到 Session 中的加载集合相关联的对象的问题，由于在 2.0 系列中删除了 cascade_backrefs，这些对象不会发出警告，即使它们是集合的待定成员；在其他类似情况下，当要刷新的集合包含将被实质性丢弃的未附加对象时，会发出警告。为  backref-待定集合成员添加警告增加了与可能存在或不存在的集合以及基于不同关系加载策略在不同时间可能刷新或不刷新的集合的一致性。
  引用：#10090
  
• [orm] [bug] [regression]
  通过 #9805 引起的额外回归被修复，其中对语句上的“ORM”标志更积极的传播可能导致在包含没有 ORM 实体的 ORM Query 构造中引发内部属性错误，即使在这种情况下 ORM 启用的 UPDATE 和 DELETE 语句中也不包含 ORM 实体。
  引用：#10098
  

engine

• [engine] [bug]
  将 Row.t 和 Row.tuple() 重命名为 Row._t 和 Row._tuple()；这是为了遵循所有在Row上的方法和预定义属性应该以 Python 标准库 namedtuple 的风格命名的政策，所有固定名称都有一个前导下划线，以避免与现有列名称发生冲突。以前的方法/属性现在已被弃用，并将发出弃用警告。
  引用：#10093
  
• [engine] [bug]
  对make_url()函数添加了对非字符串、非URL对象的检测，允许立即抛出ArgumentError，而不是在后来导致失败。特殊逻辑确保模拟形式的URL可以通过。感谢 Grigoriev Semyon 的拉取请求。
  引用：#10079
  

postgresql

• [postgresql] [bug]
  由于在#10004中对 PostgreSQL URL 解析进行了改进，导致的回归问题已修复，其中“host”查询字符串参数中包含冒号，以支持各种第三方代理服务器和/或方言，将无法正确解析，因为这些被视为host:port组合。解析已更新，只有当主机名仅包含字母数字字符，点或破折号（例如没有斜杠），后跟一个冒号，然后跟着一个零个或多个整数的令牌时，才将冒号视为指示host:port值。在所有其他情况下，整个字符串被视为主机。
  参考：#10069
  
• [postgresql] [bug]
  修复了与CITEXT数据类型的比较会将右侧转换为VARCHAR的问题，导致右侧不被解释为CITEXT数据类型，适用于 asyncpg、psycopg3 和 pg80000 方言。这导致CITEXT类型在实际使用中基本上无法使用；现在已修复此问题，并且测试套件已经更正，以正确断言表达式是否被正确渲染。
  参考：#10096
  

orm

• [orm] [bug]
  修复了直接设置关系集合的问题，其中新集合中的对象已经存在时，不会触发该对象的级联事件，导致如果该对象不存在，则不会被添加到Session中。这与#6471类似，并且由于在 2.0 系列中删除了cascade_backrefs，这个问题更加明显。作为#6471的一部分添加的AttributeEvents.append_wo_mutation()事件现在也会对已存在于同一集合的批量设置中的现有成员发出。
  参考：#10089
  
• [orm] [bug]
  修复了一个问题，即通过反向引用与未合并到Session的未加载集合相关联的对象，因为在 2.0 系列中删除了cascade_backrefs，所以不会发出警告，即这些对象未被包含在刷新中，即使它们是集合的待处理成员；在其他类似情况下，当正在刷新的集合包含将被基本丢弃的非附加对象时，将发出警告。对于反向引用挂起的集合成员添加警告，可以建立更大一致性，这些集合可能存在或不存在，并可能根据不同的关系加载策略在不同的时间进行刷新或不刷新。
  参考：#10090
  
• [orm] [bug] [regression]
  修复了由#9805导致的额外回归，其中对语句上的“ORM”标志的更积极传播可能导致在嵌入了 ORM Query 构造的核心 SQL 语句中包含没有 ORM 实体的情况下导致内部属性错误，即使在这种情况下，ORM 启用的 UPDATE 和 DELETE 语句也不包含 ORM 实体。
  参考：#10098
  

引擎

• [engine] [bug]
  将Row.t和Row.tuple()重命名为Row._t和Row._tuple()；这是为了符合所有方法和预定义属性在Row上应采用 Python 标准库namedtuple风格的政策，其中所有固定名称都带有前导下划线，以避免与现有列名称发生冲突。以前的方法/属性现已弃用，并将发出弃用警告。
  参考：#10093
  
• [engine] [bug]
  添加了对非字符串、非URL对象的检测到make_url()函数，允许立即抛出ArgumentError，而不是后来导致失败。特殊逻辑确保允许通过 URL 的模拟形式。感谢 Grigoriev Semyon 的拉取请求。
  参考：#10079
  

postgresql

• [postgresql] [bug]
  修复了在#10004中改进 PostgreSQL URL 解析时引起的回归，其中在主机查询字符串参数中含有冒号的情况下，以支持各种第三方代理服务器和/或方言，将无法正确解析，因为这些被评估为host:port组合。 解析已更新为仅在主机名仅包含字母数字字符以及仅包含点或破折号（例如没有斜杠）的情况下，考虑冒号表示host:port值，后跟零个或多个整数的全整数标记的情况下，才表示主机。 在所有其他情况下，将完整字符串视为主机。
  引用：#10069
  
• [postgresql] [bug]
  修复了与CITEXT数据类型的比较问题，导致右侧被转换为VARCHAR，导致右侧未被解释为CITEXT数据类型，适用于 asyncpg、psycopg3 和 pg80000 方言。 这导致CITEXT类型在实际使用中基本不可用；现已修复此问题，并已更正测试套件以正确断言表达式是否被正确呈现。
  引用：#10096
  

2.0.18

发布日期：2023 年 7 月 5 日

引擎

• [引擎] [bug]
  调整了create_engine.schema_translate_map功能，使得语句中的所有模式名称现在都被标记化，而不管特定名称是否在给定的立即模式翻译映射中，并且在执行时当键不在实际模式翻译映射中时回退到替换原始名称。   这两个更改允许在每次运行时使用包含或不包含各种键的模式翻译映射来重复使用已编译的对象，从而使得当每次使用时都使用具有不同键集的模式翻译映射时，缓存的  SQL 结构可以继续在运行时正常工作。 另外，还添加了在相同语句的调用间获得或失去None键的 schema_translate_map 字典的检测，这会影响语句的编译，并且与缓存不兼容； 这些情况下会引发异常。
  引用：#10025
  

sql

• [sql] [bug]
  修复了当使用“标志”时 ColumnOperators.regexp_match() 不会产生“稳定”的缓存密钥的问题，即，缓存密钥每次都会更改，导致缓存污染。对于带有标志和实际替换表达式的 ColumnOperators.regexp_replace() 也存在相同的问题。现在，标志被表示为固定的修饰符字符串，呈现为 safestring，而不是绑定参数，替换表达式在“二进制”元素的主要部分中确定，因此它生成适当的缓存密钥。
  请注意，作为此更改的一部分，ColumnOperators.regexp_match.flags 和 ColumnOperators.regexp_replace.flags 已修改为仅渲染为文字字符串，而以前它们被渲染为完整的 SQL 表达式，通常是绑定参数。这些参数应始终作为普通的 Python 字符串传递，而不是作为 SQL 表达式构造；不希望在实践中使用 SQL 表达式构造此参数，因此这是一个不兼容的更改。
  此更改还修改了生成的表达式的内部结构，对于带有或不带有标志的 ColumnOperators.regexp_replace() 和带有标志的 ColumnOperators.regexp_match()。可能已经实现了自己的正则表达式实现的第三方方言（在搜索中找不到此类方言，因此预期影响很小）需要调整结构的遍历以适应。
  此更改还 回溯到：1.4.49
  参考：#10042
  
• [sql] [错误]
  修复了在主要内部CacheKey 构造中的问题，其中__ne__() 运算符未正确实现，导致当比较 CacheKey 实例时产生荒谬的结果。
  此更改还 回溯到：1.4.49
  

扩展

• [扩展] [用例]
  向 association_proxy() association_proxy.create_on_none_assignment 添加了新选项；当一个关联代理引用一个标量关系并被赋予值 None，并且引用的对象不存在时，通过创建者创建一个新对象。这显然是 1.2 系列中的一个未定义行为，已经被悄悄移除了。
  参考资料：#10013
  

类型提示

• [类型提示] [用例]
  当使用sqlalchemy.sql.operators中的独立运算符函数（例如sqlalchemy.sql.operators.eq）时，改进了类型提示。
  参考资料：#10054
  
• [类型提示] [错误]
  修正了 aliased() 结构内部的一些类型提示，以正确接受已使用 Table.alias() 别名的 Table 对象，以及对传递为“可选择”参数的 FromClause 对象的一般支持，因为这都得到了支持。
  参考资料：#10061
  

postgresql

• [postgresql] [用例]
  为 asyncpg 方言添加了多主机支持。还添加了对“多主机”用例的 PostgreSQL URL 例程的一般改进和错误检查。拉取请求由 Ilia Dmitriev 提供。
  请参阅
  多主机连接
  参考资料：#10004
  
• [postgresql] [错误]
  向所有 PostgreSQL 方言添加了新参数 native_inet_types=False，该参数指示 DBAPI 使用的转换器将 PostgreSQL 的 INET 和 CIDR 列中的行转换为 Python ipaddress 数据类型时应禁用，返回字符串。这样，编写用于这些数据类型的字符串的代码可以在无需代码更改的情况下添加此参数到 create_engine() 或 create_async_engine() 函数调用中而迁移到 asyncpg、psycopg 或 pg8000。
  请参阅
  网络数据类型
  参考：#9945
  

mariadb

• [mariadb] [用例] [反射]
  允许从 MariaDB 反射 UUID 列。这使得 Alembic 能够正确地检测现有 MariaDB 数据库中这些列的类型。
  参考：#10028
  

mssql

• [mssql] [用例]
  在 MSSQL 方言中添加了对 COLUMNSTORE 索引的创建和反射支持。可以在指定了 mssql_columnstore=True 的索引上指定。
  参考：#7340
  
• [mssql] [错误] [sql]
  修复了在对具有显式排序规则的字符串类型执行 Cast 时会在 CAST 函数内部呈现 COLLATE 子句的问题，从而导致语法错误。
  参考：#9932
  

引擎

• [引擎] [错误]
  调整了 create_engine.schema_translate_map 功能，使得语句中的所有模式名称现在都被标记化，无论指定了具体名称是否在立即模式翻译映射中，都会在执行时回退到原始名称。这两个变化允许对具有包含或不包含不同键集的模式翻译映射的编译对象进行重复使用，每次运行时使用不同的模式翻译映射，从而使得缓存的  SQL 构造在运行时继续工作。此外，增加了在同一语句的不同调用中增加或减少 None 键的 schema_translate_map 字典的检测，这会影响语句的编译，并且不兼容缓存；对于这些情况，会引发异常。
  参考：#10025
  

SQL

• [sql] [错误]
  修复了使用“flags”时 ColumnOperators.regexp_match() 未生成“稳定”缓存键的问题，即每次缓存键都会发生变化，导致缓存污染。相同的问题也存在于带有 flags 和实际替换表达式的 ColumnOperators.regexp_replace() 中。现在，flags 被表示为固定的修改器字符串，呈现为安全字符串，而不是绑定参数，并且替换表达式在“binary”元素的主要部分内建立，以生成适当的缓存键。
  注意，作为这一变更的一部分，ColumnOperators.regexp_match.flags 和 ColumnOperators.regexp_replace.flags 已经修改为仅呈现为字面字符串，而以前它们呈现为完整的 SQL 表达式，通常是绑定参数。这些参数应始终作为普通的 Python 字符串传递，而不是作为 SQL 表达式构造；预计实践中不会使用 SQL 表达式构造来传递此参数，因此这是一个不兼容的变更。
  此变更还修改了生成的表达式的内部结构，用于带有或不带有 flags 的 ColumnOperators.regexp_replace()，以及带有 flags 的 ColumnOperators.regexp_match()。可能已经实现了自己的正则表达式的第三方方言（在搜索中找不到这样的方言，因此预期影响很小）需要调整结构的遍历以适应。
  此变更还 回溯 到：1.4.49
  参考文献：#10042
  
• [SQL] [错误]
  修复了大部分内部 CacheKey 构造中 __ne__() 运算符未正确实现的问题，导致在将 CacheKey 实例相互比较时产生荒谬的结果。
  此变更还 回溯 到：1.4.49
  

扩展

• [扩展] [用例]
  为association_proxy()添加了新选项association_proxy.create_on_none_assignment; 当将引用标量关系的关联代理分配为None值时，并且引用的对象不存在时，通过创建器创建一个新对象。在 1.2 系列中，这显然是一种未定义的行为，被默默删除了。
  参考：#10013
  

输入

• [输入] [用例]
  当使用来自sqlalchemy.sql.operators的独立运算符函数（如sqlalchemy.sql.operators.eq）时，改进了类型提示。
  参考：#10054
  
• [输入] [错误]
  修复了aliased()构造中的一些类型提示，以正确接受已使用Table.alias()别名的Table对象，以及一般性对于FromClause对象作为“selectable”参数的支持，因为这都是受支持的。
  参考：#10061
  

postgresql

• [postgresql] [用例]
  为 asyncpg 方言添加了多主机支持。还为“多主机”用例的 PostgreSQL URL 例程添加了一般性改进和错误检查。感谢 Ilia Dmitriev 的拉取请求。
  参见
  多主机连接
  参考：#10004
  
• [postgresql] [错误]
  对所有 PostgreSQL 方言添加了新参数native_inet_types=False，指示 DBAPI 使用的转换器将 PostgreSQL INET和CIDR列的行转换为 Python ipaddress 数据类型时应禁用，而是返回字符串。这允许为这些数据类型编写使用字符串的代码迁移到 asyncpg、psycopg 或 pg8000 而无需其他代码更改，只需将此参数添加到create_engine()或create_async_engine()函数调用中。
  参见
  网络数据类型
  参考：#9945
  

mariadb

• [mariadb] [usecase] [reflection]
  允许从 MariaDB 反射UUID列。 这使得 Alembic 能够正确地检测到现有 MariaDB 数据库中此类列的类型。
  参考：#10028
  

mssql

• [mssql] [usecase]
  添加了对 MSSQL 方言中 COLUMNSTORE 索引的创建和反射支持。 可以在指定mssql_columnstore=True的索引上指定。
  参考：#7340
  
• [mssql] [bug] [sql]
  修复了将具有显式排序规则的字符串类型执行Cast时会在 CAST 函数内部呈现 COLLATE 子句的问题，这导致语法错误。
  参考：#9932
  

2.0.17

发布日期：2023 年 6 月 23 日

orm

• [orm] [bug] [regression]
  修复了 2.0 系列中的回归问题，其中使用undefer_group()与selectinload()或subqueryload()的查询会引发AttributeError。 拉取请求由 Matthew Martin 提供。
  参考：#9870
  
• [orm] [bug]
  修复了在 ORM 注释声明中的问题，该问题阻止了declared_attr在未返回Mapped数据类型的混合类型上使用，而是返回了诸如AssociationProxy之类的补充 ORM 数据类型。 声明式运行时会错误地尝试解释此注释为需要Mapped并引发错误。
  参考：#9957
  
• [orm] [bug] [typing]
  修复了使用declared_attr函数的AssociationProxy返回类型被禁止的类型问题。
  参考：#9957
  
• [orm] [bug] [regression]
  修复了 2.0.16 中由#9879引入的回归，其中将可调用对象传递给mapped_column.default参数时，同时设置init=False会将此值解释为 Dataclass 默认值，该值将直接分配给对象的新实例，绕过了作为底层Column.default值生成器的默认生成器所发生的情况。现在检测到此条件以保持先前的行为，但发出了对此模棱两可用法的弃用警告；为了为Column填充默认生成器，应使用mapped_column.insert_default参数，该参数使其与固定名称的mapped_column.default参数相区分，根据 pep-681。
  参考：#9936
  
• [orm] [bug]
  对 ORM Session “状态更改”系统进行了额外的强化和文档编写，该系统检测到Session和AsyncSession对象的并发使用；在从底层引擎获取连接的过程中添加了额外的检查，在内部连接管理方面是一个关键部分。
  参考：#9973
  
• [orm] [bug]
  修复了 ORM 加载器策略逻辑中的问题，进一步允许在复杂的继承多态/别名/of_type()关系链中横跨长链的contains_eager()加载器选项以正确生效于查询中。
  参考：#10006
  
• [orm] [bug]
  修复了在 registry.type_annotation_map 中首次添加的 Enum 数据类型支持中的问题，其中使用映射中的自定义 Enum 并且在映射中使用固定配置会导致传输 Enum.name 参数失败，其中一个问题是如果枚举值作为单独的值传递，则会阻止 PostgreSQL 枚举正常工作。逻辑已更新，使“name”被传输，但也使默认的 Enum 不会设置一个硬编码的名称为 "enum"。
  参考：#9963
  

ORM 声明性

• [ORM] [声明性] [错误]
  当将 ORM relationship() 和其他 MapperProperty 对象同时分配给两个不同的类属性时，会发出警告；只会映射其中一个属性。对于此情况的警告已经适用于 Column 和 mapped_column 对象。
  参考：#3532
  

扩展

• [扩展] [错误]
  修复了与 mypy 1.4 结合使用的 mypy 插件中的问题。
  此更改还被 回溯 至：1.4.49
  

typing

• [类型] [错误]
  修复了阻止 WriteOnlyMapped 和 DynamicMapped 属性在 ORM 查询中完全使用的类型问题。
  参考：#9985
  

postgresql

• [postgresql] [用例]
  pg8000 方言现在支持  RANGE 和 MULTIRANGE 数据类型，使用现有的 RANGE API 描述在 Range and Multirange  Types。pg8000 驱动程序从版本 1.29.8 开始支持范围和多范围类型。感谢 Tony Locke 提交的拉取请求。
  参考：#9965
  

ORM

• [ORM] [错误] [回归]
  修复了 2.0 系列中的回归问题，即使用undefer_group()与selectinload()或subqueryload()的查询会引发AttributeError。感谢 Matthew Martin 提交的拉取请求。
  参考：#9870
  
• [orm] [bug]
  修复了 ORM 注释声明中的问题，该问题导致无法在未返回Mapped数据类型的混合使用declared_attr，而是返回了诸如AssociationProxy等补充的 ORM 数据类型。声明式运行时错误地尝试将此注释解释为需要Mapped并引发错误。
  参考：#9957
  
• [orm] [bug] [typing]
  修复了使用declared_attr函数中的AssociationProxy返回类型被禁止的类型问题。
  参考：#9957
  
• [orm] [bug] [regression]
  修复了 2.0.16 中由 #9879 引入的回归问题，当将可调用对象传递给 mapped_column.default 参数时，同时设置 init=False 会将此值解释为 Dataclass 的默认值，该值将直接分配给对象的新实例，绕过了基础 Column.default 值生成器在 Column 上发生的默认生成器。现在检测到这种情况以保持先前的行为，但是对于这种模棱两可的使用会发出弃用警告；要为 Column 填充默认生成器，应使用 mapped_column.insert_default 参数，该参数与 mapped_column.default 参数相区分，其名称固定为 pep-681。
  参考：#9936
  
• [orm] [bug]
  对于 ORM Session 的“状态更改”系统进行了额外的加固和文档编制，该系统检测到同时使用 Session 和 AsyncSession 对象；在获取来自底层引擎的连接过程中添加了额外的检查，这是关于内部连接管理的关键部分。
  参考：#9973
  
• [orm] [bug]
  修复了 ORM 加载程序策略逻辑中的问题，进一步允许在复杂的继承多态/别名/ of_type() 关系链上跨长链的 contains_eager() 加载选项，以在查询中产生正确的效果。
  参考：#10006
  
• [orm] [bug]
  修复了在 registry.type_annotation_map 中首次添加的 Enum 数据类型支持中出现的问题，该问题涉及使用映射中的固定配置的自定义 Enum 时会失败传输 Enum.name 参数，其中，如果将枚举值作为单独的值传递，则会导致阻止 PostgreSQL 枚举起作用的问题。逻辑已更新，使“name”被传递，但同时也确保了默认 Enum 不会设置硬编码的名称为"enum"。
  引用：#9963
  

ORM 声明

• [orm] [声明] [错误]
  当 ORM relationship() 和其他 MapperProperty 对象同时分配给两个不同的类属性时，会发出警告；只有其中一个属性会被映射。对于这种情况的警告已经存在于 Column 和 mapped_column 对象中。
  引用：#3532
  

扩展

• [扩展] [错误]
  修复了与 mypy 1.4 一起使用时的 mypy 插件中的问题。
  此更改也被回溯到：1.4.49
  

打字

• [打字] [错误]
  修复了一个打字错误问题，该问题导致WriteOnlyMapped和DynamicMapped属性在 ORM 查询中无法完全使用。
  引用：#9985
  

postgresql

• [postgresql] [用例]
  pg8000 方言现在支持  RANGE 和 MULTIRANGE 数据类型，使用现有的 RANGE 和 Multirange 类型中描述的 RANGE API。Range 和  multirange 类型在 pg8000 驱动程序的版本 1.29.8 中受支持。感谢 Tony Locke 提供的拉取请求。
  引用：#9965
  

2.0.16

发布日期：2023 年 6 月 10 日

平台

• [平台] [用例]
  兼容性改进，允许完整测试套件在 Python 3.12.0b1 上通过。
  

ORM

• [orm] [用例]
  改进 DeferredReflection.prepare()，接受任意的 **kw 参数，这些参数将传递给 MetaData.reflect()，允许用例，例如反射视图以及传递特定于方言的参数。此外，现代化了 DeferredReflection.prepare.bind 参数，使得一个 Engine 或 Connection 都可作为“bind”参数。
  参考：#9828
  
• [orm] [bug]
  修复了DeclarativeBaseNoMeta声明基类无法与非映射的混入或抽象类一起使用的问题，而是引发 AttributeError。
  参考：#9862
  
• [orm] [bug] [regression]
  修复了 2.0 系列中的回归问题，其中 validates.include_backrefs 的默认值在 validates() 函数中更改为 False。现在将此默认值恢复为 True。
  参考：#9820
  
• [orm] [bug]
  修复了一个新功能中的错误，该功能允许在 ORM 通过主键进行批量更新 时与 WHERE 子句一起使用，该功能是在版本 2.0.11 中作为 #9583 的一部分添加的，如果发送的字典不包括每行的主键值，则会通过批量处理过程并为行包含“pk=NULL”，这将导致静默失败。如果未提供批量更新的主键值，则现在会引发异常。
  参考：#9917
  
• [orm] [bug] [dataclasses]
  修复了一个问题，即生成指定了 default 值并设置 init=False 的数据类字段不起作用。在这种情况下，数据类的行为是在类上设置默认值，这与 SQLAlchemy 使用的描述符不兼容。为了支持这种情况，生成数据类时将默认值转换为 default_factory。
  参考：#9879
  
• [orm] [bug]
  每当在 Mapper 上添加属性时，如果已经配置了 ORM  映射属性，或者类上已经存在属性，则会发出弃用警告。以前，对于这种情况有一个不一致地发出的非弃用警告。对于这个警告的逻辑已经改进，以便检测到终端用户替换属性，同时不会误报内部声明式和其他情况，其中替换描述符为新描述符是预期的。
  参考：#9841
  
• [orm] [bug]
  改进了 registry.map_imperatively() 方法的 map_imperatively.local_table 参数上的参数检查，确保仅传递 Table 或其他 FromClause ，而不是现有的映射类，这会导致未定义的行为，因为对象将进一步解释为新的映射。
  参考：#9869
  
• [orm] [bug]
  InstanceState.unloaded_expirable 属性是 InstanceState.unloaded 的同义词，现已弃用；此属性始终是特定于实现的，并且不应该是公共的。
  参考：#9913
  

asyncio

• [asyncio] [usecase]
  在 create_async_engine() 中添加了新的 create_async_engine.async_creator 参数，其作用与 create_engine() 的 create_engine.creator 参数相同。这是一个无参数可调用对象，使用 asyncio 数据库驱动程序直接提供新的 asyncio 连接。create_async_engine() 函数将在适当的结构中包装驱动程序级连接。拉取请求由杰克·沃瑟斯普恩提供。
  参考：#8215
  

postgresql

• [postgresql] [usecase] [reflection]
  在 PostgreSQL 反射中，将 NAME 列转换为 TEXT 当使用 ARRAY_AGG 时。这似乎提高了与一些不支持 NAME 类型聚合的 PostgreSQL 派生产品的兼容性。
  参考：#9838
  
• [postgresql] [usecase]
  统一了自定义的 PostgreSQL 运算符定义，因为它们在多个不同的数据类型之间共享。
  参考：#9041
  
• [postgresql] [usecase]
  增加了对 PostgreSQL 10 NULLS NOT DISTINCT 特性的支持，使用方言选项 postgresql_nulls_not_distinct。更新了反射逻辑，以正确考虑此选项。感谢 Pavel Siarchenia 的拉取请求。
  参考：#8240
  
• [postgresql] [bug]
  在 PostgreSQL 特定运算符上使用正确的优先级，比如 @>。之前的优先级错误，导致在与 ANY 或 ALL 结构渲染时括号错误。
  参考：#9836
  
• [postgresql] [bug]
  修复了 ColumnOperators.like.escape 和类似参数不允许空字符串作为传递的“转义”字符的问题；这是 PostgreSQL 支持的语法。感谢 Martin Caslavsky 的拉取请求。
  参考：#9907
  

platform

• [platform] [usecase]
  兼容性改进，使完整的测试套件能够在 Python 3.12.0b1 上通过。
  

orm

• [orm] [usecase]
  改进了 DeferredReflection.prepare()，接受传递给 MetaData.reflect() 的任意 **kw 参数，允许用例如反射视图以及传递方言特定参数。此外，现代化了 DeferredReflection.prepare.bind 参数，以便接受 Engine 或 Connection 作为“bind”参数。
  参考：#9828
  
• [orm] [bug]
  修复了 DeclarativeBaseNoMeta 声明基类无法与非映射混入类或抽象类一起使用的问题，而是引发 AttributeError。
  参考：#9862
  
• [orm] [bug] [regression]
  修复了 2.0 系列中的回归问题，其中 validates.include_backrefs 的默认值在 validates() 函数中被更改为 False。现在将此默认值恢复为 True。
  参考：#9820
  
• [orm] [bug]
  修复了新功能中的 bug，该功能允许在 ORM 按主键批量更新 中使用 WHERE 子句，该功能在版本 2.0.11 中作为 #9583 的一部分添加，其中发送的字典未包含每行的主键值时，将通过批量处理并为行包括“pk=NULL”，默默失败。如果未提供批量更新的主键值，则现在会引发异常。
  参考：#9917
  
• [orm] [bug] [dataclasses]
  修复了生成指定 default 值并设置 init=False 的 dataclasses 字段不起作用的问题。在这种情况下，dataclasses 的行为是在类上设置默认值，这与 SQLAlchemy 使用的描述符不兼容。为了支持这种情况，在生成 dataclass 时将默认值转换为 default_factory。
  参考：#9879
  
• [orm] [bug]
  当向 Mapper 添加属性时，如果已经配置了 ORM  映射属性，或者类上已经存在属性，则会发出弃用警告。以前，对于这种情况，存在一个不一致发出的非弃用警告。现在已经改进了此警告的逻辑，以便在检测到用户替换属性时发出警告，同时不会对内部  Declarative 和其他情况产生误报，其中预期使用新描述符替换旧描述符。
  参考：#9841
  
• [orm] [bug]
  改进了 registry.map_imperatively() 方法的 map_imperatively.local_table 参数的参数检查，确保只传递了 Table 或其他 FromClause，而不是已存在的映射类，因为这将导致对象在进一步解释时出现未定义的行为。
  参考：#9869
  
• [orm] [错误]
  InstanceState.unloaded_expirable 属性是 InstanceState.unloaded 的同义词，并已弃用；此属性始终是特定于实现的，不应公开。
  参考：#9913
  

asyncio

• [asyncio] [用例]
  向 create_async_engine() 添加了新的 create_async_engine.async_creator 参数，它实现了与 create_engine() 的 create_engine.creator 参数相同的目的。这是一个无参数的可调用对象，提供一个新的 asyncio 连接，直接使用 asyncio 数据库驱动程序。create_async_engine() 函数将以适当的结构包装驱动程序级别的连接。感谢 Jack Wotherspoon 提交的拉取请求。
  参考：#8215
  

postgresql

• [postgresql] [用例] [反射]
  在使用 PostgreSQL 反射时，将 NAME 列转换为 TEXT。这似乎提高了与一些 PostgreSQL 派生产品的兼容性，这些产品可能不支持在 NAME 类型上进行聚合。
  参考：#9838
  
• [postgresql] [用例]
  统一了自定义 PostgreSQL 操作符的定义，因为它们在多个不同的数据类型之间共享。
  参考：#9041
  
• [postgresql] [用例]
  增加了对 PostgreSQL 10 NULLS NOT DISTINCT 特性的支持，该特性使用方言选项 postgresql_nulls_not_distinct。 更新了反射逻辑以正确考虑此选项。 Pavel Siarchenia 的 Pull request 提供支持。
  参考：#8240
  
• [postgresql] [bug]
  在 PostgreSQL 特定运算符上使用正确的优先级，例如 @>。 之前优先级错误，导致在与 ANY 或 ALL 结构进行渲染时出现错误的括号。
  参考：#9836
  
• [postgresql] [bug]
  修复了一个问题，ColumnOperators.like.escape和类似参数不允许空字符串作为参数，该参数将作为“转义”字符传递；这是 PostgreSQL 支持的语法。 感谢 Martin Caslavsky 的 Pull requset。
  参考：#9907
  

2.0.15

发布日期：2023 年 5 月 19 日

orm

• [orm] [bug]
  随着越来越多的项目开始使用新型“2.0” ORM  查询，显然“自动刷新”的条件性质，基于给定语句是否涉及 ORM 实体，正在变得更加关键。直到现在，“ORM”标志对于语句是否返回与 ORM  实体或列对应的行一直是松散的；“ORM”标志的原始目的是启用 ORM 实体获取规则，该规则将后处理应用于核心结果集以及将 ORM  加载器策略应用于语句。 对于不建立在包含 ORM 实体的行上的语句，认为“ORM”标志基本上是不必要的。
  仍然可能是“自动刷新”对于 所有 使用 Session.execute() 和相关方法更好，即使对于纯粹的 Core SQL 构造也是如此。 但是，这可能仍然会影响不期望的遗留情况，并且可能更多地成为 2.1  版本的事情。 然而，目前“ORM 标志”的规则已经放宽，因此任何语句，包括在 WHERE / ORDER BY / GROUP BY 子句中的  ORM 实体或属性，在标量子查询中等都将启用此标志。 这将导致对这些语句进行“自动刷新”，并且还可以通过 ORMExecuteState.is_orm_statement 事件级属性可见。
  参考：#9805
  

postgresql

• [postgresql] [bug] [regression]
  修复了 PostgreSQL 方言的基本Uuid数据类型，以充分利用 PG 特定的 UUID 方言特定数据类型，当选择“native_uuid”时，以便包含 PG 驱动程序的行为。由于作为#9618的一部分进行的 insertmanyvalues 改进，这个问题变得明显，类似于#9739，asyncpg 驱动程序对数据类型转换的存在与否非常敏感，当使用这种通用类型时，必须调用 PostgreSQL 驱动程序特定的本地 UUID 数据类型，以便进行这些转换。
  参考：#9808
  

orm

• [orm] [bug]
  随着越来越多的项目使用新式“2.0” ORM  查询，显而易见的是，“autoflush”的条件性，基于给定语句是否涉及 ORM 实体，正在变得更加关键。直到现在，对于语句是否返回与 ORM  实体或列对应的行，一直是围绕“ORM”标志的松散基础；“ORM”标志的最初目的是启用 ORM 实体获取规则，这些规则将后处理应用于 Core  结果集以及 ORM 加载器策略到语句。对于不建立在包含 ORM 实体的行上的语句，认为“ORM”标志基本上是不必要的。
  仍然可能是“autoflush”对于所有使用Session.execute()和相关方法更好，即使是纯粹的  Core SQL 构造。然而，这可能会影响到不期望的遗留情况，可能更多是 2.1  的事情。但是，目前，“ORM-flag”的规则已经放宽，以便包含 ORM 实体或属性的语句中的任何地方，包括仅在 WHERE / ORDER  BY / GROUP BY 子句中，在标量子查询中等，将启用此标志。这将导致这些语句发生“autoflush”，并且还可以通过ORMExecuteState.is_orm_statement事件级属性可见。
  参考：#9805
  

postgresql

• [postgresql] [bug] [regression]
  修复了基本的Uuid数据类型，使其在选择“native_uuid”时充分利用了 PostgreSQL 方言的 PG 特定 UUID 方言特定数据类型，以便包含 PG 驱动程序的行为。这个问题由于作为#9618的一部分所做的 insertmanyvalues 改进而变得显而易见，其中与#9739类似，asyncpg 驱动程序对是否存在数据类型转换非常敏感，当使用此通用类型时，必须调用 PostgreSQL 驱动程序特定的本地 UUID 数据类型，以便进行这些转换。
  参考：#9808
  

2.0.14

发布日期：2023 年 5 月 18 日

orm

• [orm] [bug]
  修改了JoinedLoader的实现，在一个特定的区域使用了更简单的方法，之前它使用了一个缓存结构，该结构将在线程之间共享。这样做的原因是避免潜在的竞争条件，这被怀疑是导致特定崩溃的原因。所涉及的缓存结构最终仍然通过编译后的 SQL 缓存“缓存”，因此不预期出现性能下降。
  参考：#9777
  
• [orm] [bug] [regression]
  修复了在 CTE 构造中使用 update() 或 delete()，然后在 select() 中使用会引发 CompileError 的回归，原因是 ORM 相关规则执行 ORM 级别的更新/删除语句。
  参考：#9767
  
• [orm] [bug]
  在新的 ORM Annotated Declarative 中修复了使用 ForeignKey（或其他列级约束）位于 mapped_column() 中，然后通过 pep-593 Annotated 复制到模型中时，将每个约束的副本应用到目标 Table 中的 Column，从而导致不正确的 CREATE TABLE DDL 以及 Alembic 下的迁移指令。
  参考：#9766
  
• [orm] [bug]
  修复了使用joinedload()加载器选项时，使用附加的关系条件的问题，其中附加的条件本身包含引用加入实体的相关子查询，因此还需要对别名实体进行“调整”，否则会排除这种调整，导致 joinedload 的 ON 子句错误。
  References: #9779
  

sql

• [sql] [usecase]
  将 MSSQL 的try_cast()函数泛化为`sqlalc