支持使用 SQLAlchemy 的各种实用程序函数。

最新版本 20220606：

• BasicTableMixin：提供 DEFAULT_ID_COLUMN='id'，by_id() 有新的可选 id_column 参数。
• RelationProxy 工厂用于创建代理关系的基类，用于您希望最小化对数据库本身的访问的情况。
• ORM.engine_keywords：仅当 $DEBUG 中的“SQL”时才打开回显模式。

功能auto_session(function)

如果未预先提供一个函数，则装饰器在会话中运行一个函数。该函数function在事务中运行，如果会话已经存在则嵌套。

详情请参阅with_session。

班级BasicTableMixin

大多数表的有用方法。

功能find_json_field(column_value, field_name, *, infill=False)

将 JSONable Python 对象下降column_value 到field_name. 返回column_value（可能已填充）, final_field, final_field_name.

这支持作为 JSON 列的数据库行列。

参数：

• column_value: 列的原始值
• field_name：要定位的列中的字段
• infill: 可选关键字参数，默认False。如果为真， column_value它的内部将被填充为dicts 以允许对field_name.

它field_name由str 句点 ( '.') 分隔的字段部分序列组成。每个字段部分都成为索引列映射的键。这些键分为前导字段部分和最终字段部分，final_field_name如上返回。

上面的final_field返回值是final_field_value可能位于和final_field_value可能设置的映射。注意：它可能不存在。

如果缺少前导键并且infill为真，则将 的相应部分column_value设置为空字典，以允许引用前导键。这包括当column_value它本身是时的情况None，这就是为什么column_value是返回的一部分。

如果缺少前导键并且为假，则此函数将为失败 的部分infill引发 a 。KeyErrorfield_name

例子：

>>> find_json_field({'a':{'b':{}}}, 'a.b')
({'a': {'b': {}}}, {'b': {}}, 'b')
>>> find_json_field({'a':{}}, 'a.b')
({'a': {}}, {}, 'b')
>>> find_json_field({'a':{'b':{}}}, 'a.b.c.d')
Traceback (most recent call last):
    ...
KeyError: 'a.b.c'
>>> find_json_field({'a':{'b':{}}}, 'a.b.c.d', infill=True)
({'a': {'b': {'c': {}}}}, {}, 'd')
>>> find_json_field(None, 'a.b.c.d')
Traceback (most recent call last):
    ...
KeyError: 'a'
>>> find_json_field(None, 'a.b.c.d', infill=True)
({'a': {'b': {'c': {}}}}, {}, 'd')

功能get_json_field(column_value, field_name, *, default=None)

如果字段不存在，则返回field_namefrom的值或默认值。column_value

参数：

• column_value: 列的原始值
• field_name：要定位的列中的字段
• default：如果该字段不存在，则返回默认值，默认值：None

例子：

>>> get_json_field({'a': 1}, 'a')
1
>>> get_json_field({'b': 1}, 'a')
>>> get_json_field({'a': {}}, 'a.b')
>>> get_json_field({'a': {'b': 2}}, 'a.b')
2

班级HasIdMixin

包括一个“id”Column作为主键。

功能json_column(*da, **dkw)

类装饰器在表上声明一个虚拟列名，其中值驻留在表的 JSON 列中。

参数：

• cls: 要注释的类
• attr: 显示为行属性的虚拟列名
• json_field_name: JSON 列中用于存储该值的字段，默认为attr
• json_column_name: 关联 JSON 列的名称，默认'info'
• default: 如果字段不存在，getter 返回的默认值，默认None

示例使用：

Base = declarative_base()
...
@json_column('virtual_name', 'json.field.name')
class TableClass(Base):
  ...

.virtual_name这使用可以访问或设置、访问或修改关联 JSON 列（在本例中为 column info、正在访问info['json']['field']['name']）的属性来注释类。

功能log_level(*da, **dkw)

函数的装饰器，它在上下文管理器中包装对函数的调用，可选择将上下文作为被调用函数的第一个参数提供。

班级ORM(cs.resources.MultiOpenMixin, cs.context.ContextManagerMixin)

ORM 类的便利基类。

这定义了.Base一个新属性，DeclarativeBase 并提供了各种与 Session 相关的便利方法。它也是一个MultiOpenMixin支持嵌套打开/关闭序列并用作上下文管理器的子类。

方法ORM.__init__(self, *a, **kw)：初始化 ORM。

如果serial_sessions为真（默认False），则分配一个锁来序列化会话分配。这可能与不支持并发会话（如 SQLite）的 SQL 后端一起选择。

在 SQLite 的情况下，在尝试序列化事务时有一个小的内置超时，但很容易超过它并且恢复通常是不可行的。相反，我们使用该serial_sessions选项在分配会话之前获取互斥锁。

功能orm_auto_session(method)

如果未预先提供会话，则装饰器在派生的会话中运行方法self.orm 。旨在帮助具有.orm属性的类。

详情请参阅with_session。

功能proxy_on_demand_field(*da, **dkw)

通过函数按需提供字段值的装饰器field_func(self,db_row,session=session)。

例子：

@property
@proxy_on_demand_field
def formats(self,db_row,*,session):
    """ A mapping of Calibre format keys to format paths
        computed on demand.
    """
    return {
        fmt.format:
        joinpath(db_row.path, f'{fmt.name}.{fmt.format.lower()}')
        for fmt in db_row.formats
    }

功能RelationProxy(relation, columns: Union[str, Tuple[str], List[str]], *, id_column: Optional[str] = None, orm=None)

为关系中的行构造一个代理。

参数：

• relation: 一个 ORM 关系，这将是一个代理
• columns：要缓存的列名列表，或以空格分隔的列名字符串
• id_column：选项主键列名，默认来自BasicTableMixin.DEFAULT_ID_COLUMN：'id'
• orm：ORM，默认来自relation.orm

对于那些短暂进入数据库以获取信息而不是执行单个长时间运行的事务或会话的应用程序来说，这是一种解决方法。我们没有保留行实例，它可能希望在其源会话过期后按需加载相关数据，而是为具有缓存值的行保留一个代理，并在需要更多信息时重新获取需要的行。

典型的用途是将这个代理类构建__init__为一个较大类的一部分，该类访问数据库作为其操作的一部分。以下示例基于cs.ebooks.calibre.CalibreTree：

def __init__(self, calibrepath):
  super().__init__(calibrepath)
  # define the proxy classes
  class CalibreBook(RelationProxy(self.db.books, [
      'author',
      'title',
  ])):
    """ A reference to a book in a Calibre library.
    """
    @typechecked
    def __init__(self, tree: CalibreTree, dbid: int, db_book=None):
      self.tree = tree
      self.dbid = dbid
    ... various other CalibreBook methods ...
  self.CalibreBook = CalibreBook

def __getitem__(self, dbid):
  return self.CalibreBook(self, dbid, db_book=db_book)

功能set_json_field(column_value, field_name, value, *, infill=False)

为设置新value的field_name。column_value退回新的column_value.

参数：

• column_value: 列的原始值
• field_name：要定位的列中的字段
• value: 要存储的值field_name
• infill: 可选关键字参数，默认False。如果为真， column_value它的内部将被填充为dicts 以允许对field_name.

与 一样find_json_field，一个 trueinfill可以修改column_value为提供field_name ，这就是该函数返回新的column_value.

例子：

>>> set_json_field({'a': 2}, 'a', 3)
{'a': 3}
>>> set_json_field({'a': 2, 'b': {'c': 5}}, 'b.c', 4)
{'a': 2, 'b': {'c': 4}}
>>> set_json_field({'a': 2}, 'b.c', 4)
Traceback (most recent call last):
    ...
KeyError: 'b'
>>> set_json_field({'a': 2}, 'b.c', 4, infill=True)
{'a': 2, 'b': {'c': 4}}
>>> set_json_field(None, 'b.c', 4, infill=True)
{'b': {'c': 4}}

班级SQLAState(cs.threads.State, _thread._local)

SQLAlchemy ORM 和会话的线程本地状态。

功能using_session(orm=None, session=None)

用于准备 SQLAlchemy 会话以供套件使用的上下文管理器。

参数：

• orm: 可选引用 ORM，一个带有.session()创建新会话方法的对象。默认值：如果需要，从全局获取state.orm。
• session：可选的现有会话。state.session默认值：如果不是，则为全局None，否则由orm.session().

如果创建了新会话，则将新会话和引用 ORM 分别推送到全局变量state.session和state.orm 。

如果重用现有会话，则套件将在来自 的保存点内运行session.begin_nested()。

功能with_orm(function, *a, orm=None, **kw)

以共享状态function提供的调用。orm

功能with_session(function, *a, orm=None, session=None, **kw)

调用function(*a,session=session,**kw)，如果需要，创建一个会话。该函数function在事务中运行，如果会话已经存在则嵌套。如果创建了新会话，则将其设置为共享状态下的默认会话。

这是 和 的内部@auto_session机制 ORM.auto_session。

参数：

• function: 要调用的函数
• a: 位置参数
• orm：具有.session()上下文管理器方法的可选 ORM 类，例如ORM此模块提供的基类。
• session: 可选的现有 ORM 会话
• kw: 其他关键字参数，传递给function

其中之一orm或session必须不是None；如果session 是，则由上下文管理器None制成orm.session()并用作上下文管理器。

session也作为关键字参数传递给以function支持session嵌套调用。

发布日志

发布 20220606：

• BasicTableMixin：提供 DEFAULT_ID_COLUMN='id'，by_id() 有新的可选 id_column 参数。
• RelationProxy 工厂用于创建代理关系的基类，用于您希望最小化对数据库本身的访问的情况。
• ORM.engine_keywords：仅当 $DEBUG 中的“SQL”时才打开回显模式。

发布 20220311：许多更新和小修复。

发布 20210420：

• ORM：从文档字符串中删除 .Session，不再使用。
• 将 ORM.sessionmaker 重命名为 ORM._sessionmaker，不供公众使用。
• ORM：将session替换为arranged_session，按照ORM.serial_sessions分配一个会话（串行会话与SQLite一起使用）。
• 删除不再使用的 @ORM.auto_session 和 @ORM.orm_method 装饰器。
• SQLAState.new_session：使用 orm.arranged_session()，使用 begin_nested()；SQLAState.auto_session：使用 begin_nested()。

发布 20210322：删除发出 RuntimeError 的转义调试代码。

发布 20210321：

• 默认会话支持，特别是通过 ORM 的 .sqla_state 每个线程状态对象 - 这允许删除大量管道和 @auto_session 装饰。
• 支持序列化会话，用于一次可能只有一个会话处于活动状态的数据库后端；这带来了对多线程 SQLite 访问的轻松支持。

发布 20210306：

• 将 _state 重命名为 state，使其公开。
• 其他一些内部变化。

发布 20201025：

• 新的 BasicTableMixin 和 HasIdMixin 类分别具有有用的方法和典型的idColumn。
• 各种修复和改进。

发布 20190830.1：设置装饰器。模块。

发布 20190830：@json_column：小的文档字符串改进。

发布 20190829：

• 修正 @json_column setter：将列标记为 ORM 已修改。
• 新的 push_log_level 上下文管理器和 @log_level 装饰器临时更改 SQLAlchemy 日志记录处理程序级别。

发布 20190812：

• 使 ORM 成为 MultiOpenMixin。
• get_json_field：使用忘记default的参数。
• 其他小改动。

发布 20190526：

• 支持映射到 JSON 列内部值的虚拟列：
• 新功能 find_json_field、get_json_field、set_json_field。
• declaritive_base 表的新装饰器 @json_column。

发布 20190517：

• 使 ORM._Session 私有会话工厂成为公共 ORM.Session 工厂以供外部使用。
• with_session：预先存在的会话仍会触发 session.begin_nested，消除其他地方的刷新/提交紧张。

发布 20190403：

• 将@ORM.orm_auto_session 重命名为@ORM.auto_session。
• 具有 .orm 属性的对象方法的新 @orm_auto_session 装饰器。

版本 20190319.1：初始版本。ORM 基类，@auto_session 装饰器。