SqlAlchemy 2.0 中文文档（二十五）（2）https://developer.aliyun.com/article/1560576
Session API
Session 和 sessionmaker()
| 对象名称 | 描述 |
| ORMExecuteState | 表示对Session.execute()方法的调用，作为传递给SessionEvents.do_orm_execute()事件钩子的参数。 |
| Session | 管理 ORM 映射对象的持久化操作。 |
| sessionmaker | 可配置的Session工厂。 |
| SessionTransaction | 一个Session级别的事务。 |
| SessionTransactionOrigin | 表示SessionTransaction的来源。 |
class sqlalchemy.orm.sessionmaker
可配置的Session工厂。
sessionmaker工厂在调用时生成新的Session对象，在此处建立的配置参数的基础上创建它们。
例如：
from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker # an Engine, which the Session will use for connection # resources engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/') Session = sessionmaker(engine) with Session() as session: session.add(some_object) session.add(some_other_object) session.commit()
上下文管理器的使用是可选的；否则，通过Session.close()方法可以显式关闭返回的Session对象。使用try:/finally:块是可选的，但是会确保即使存在数据库错误，关闭也会发生：
session = Session() try: session.add(some_object) session.add(some_other_object) session.commit() finally: session.close()
sessionmaker充当Engine充当Connection对象的工厂的工厂。以这种方式，它还包括一个sessionmaker.begin()方法，提供一个上下文管理器，该管理器既开始又提交事务，完成后关闭Session，如果出现任何错误，则回滚事务：
Session = sessionmaker(engine) with Session.begin() as session: session.add(some_object) session.add(some_other_object) # commits transaction, closes session
新版本 1.4 中新增。
当调用sessionmaker来构造一个Session时，也可以传递关键字参数给方法；这些参数将覆盖全局配置的参数。下面我们使用一个绑定到某个Engine的sessionmaker来生成一个Session，而该Session则绑定到从该引擎获取的特定Connection上：
Session = sessionmaker(engine) # bind an individual session to a connection with engine.connect() as connection: with Session(bind=connection) as session: # work with session
该类还包括一个方法sessionmaker.configure()，用于指定工厂的其他关键字参数，这些参数将对生成的后续Session对象生效。通常用于在首次使用之前将一个或多个Engine对象与现有的sessionmaker工厂关联起来：
# application starts, sessionmaker does not have # an engine bound yet Session = sessionmaker() # ... later, when an engine URL is read from a configuration # file or other events allow the engine to be created engine = create_engine('sqlite:///foo.db') Session.configure(bind=engine) sess = Session() # work with session
另请参阅
打开和关闭会话 - 关于使用sessionmaker创建会话的介绍性文本。
成员
call(), init(), begin(), close_all(), configure(), identity_key(), object_session()
类签名
类sqlalchemy.orm.sessionmaker（sqlalchemy.orm.session._SessionClassMethods, typing.Generic）
method __call__(**local_kw: Any) → _S
使用在这个sessionmaker中建立的配置生成一个新的Session对象。
在 Python 中，当对象“被调用”时，会调用__call__方法，其方式与函数相同：
Session = sessionmaker(some_engine) session = Session() # invokes sessionmaker.__call__()
method __init__(bind: Optional[_SessionBind] = None, *, class_: Type[_S] = <class 'sqlalchemy.orm.session.Session'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)
构造一个新的sessionmaker。
这里的所有参数，除了class_之外，都与Session直接接受的参数相对应。有关参数的更多详细信息，请参阅Session.__init__()文档字符串。
参数：
bind– 一个Engine或其他Connectable，新创建的Session对象将与之关联。class_– 用于创建新的Session对象的类。默认为Session。autoflush–
用于新创建的Session对象的自动刷新设置。
另请参阅
刷新 - 关于自动刷新的额外背景信息expire_on_commit=True– 用于新创建的Session对象的Session.expire_on_commit设置。info– 可选信息字典，将通过Session.info可用。请注意，当指定info参数进行特定Session构造操作时，此字典将被更新，而不是替换。**kw– 所有其他关键字参数都传递给新创建的Session对象的构造函数。
method begin() → AbstractContextManager[_S]
生成一个上下文管理器，既提供一个新的Session，又提供一个提交的事务。
例如：
Session = sessionmaker(some_engine) with Session.begin() as session: session.add(some_object) # commits transaction, closes session
版本 1.4 中的新功能。
classmethod close_all() → None
继承自 sqlalchemy.orm.session._SessionClassMethods.close_all 方法的 sqlalchemy.orm.session._SessionClassMethods
关闭内存中的所有会话。
自版本 1.3 起已弃用：Session.close_all()方法已弃用，并将在将来的版本中删除。请参考close_all_sessions()。
method configure(**new_kw: Any) → None
(重新)配置此 sessionmaker 的参数。
例如：
Session = sessionmaker() Session.configure(bind=create_engine('sqlite://'))
classmethod identity_key(class_: Type[Any] | None = None, ident: Any | Tuple[Any, ...] = None, *, instance: Any | None = None, row: Row[Any] | RowMapping | None = None, identity_token: Any | None = None) → _IdentityKeyType[Any]
继承自 sqlalchemy.orm.session._SessionClassMethods.identity_key 方法的 sqlalchemy.orm.session._SessionClassMethods
返回一个标识键。
这是identity_key()的别名。
classmethod object_session(instance: object) → Session | None
继承自 sqlalchemy.orm.session._SessionClassMethods.object_session 方法的 sqlalchemy.orm.session._SessionClassMethods
返回一个对象所属的Session。
这是object_session()的别名。
class sqlalchemy.orm.ORMExecuteState
表示对Session.execute()方法的调用，作为传递给SessionEvents.do_orm_execute()事件钩子的参数。
版本 1.4 中的新功能。
另请参阅
执行事件 - 如何使用SessionEvents.do_orm_execute()的顶级文档。
成员
init(), all_mappers, bind_arguments, bind_mapper, execution_options, invoke_statement(), is_column_load, is_delete, is_executemany, is_from_statement, is_insert, is_orm_statement, is_relationship_load, is_select, is_update, lazy_loaded_from, load_options, loader_strategy_path, local_execution_options, parameters, session, statement, update_delete_options, update_execution_options(), user_defined_options
类签名
类sqlalchemy.orm.ORMExecuteState (sqlalchemy.util.langhelpers.MemoizedSlots)
method __init__(session: Session, statement: Executable, parameters: _CoreAnyExecuteParams | None, execution_options: _ExecuteOptions, bind_arguments: _BindArguments, compile_state_cls: Type[ORMCompileState] | None, events_todo: List[_InstanceLevelDispatch[Session]])
构造一个新的ORMExecuteState。
此对象是在内部构造的。
attribute all_mappers
返回此语句顶层涉及的所有Mapper对象的序列。
“顶级”指的是那些在select()查询的结果集行中表示的Mapper对象，或者在update()或delete()查询中，是 UPDATE 或 DELETE 的主体。
版本 1.4.0b2 中的新内容。
另见
ORMExecuteState.bind_mapper
attribute bind_arguments: _BindArguments
字典作为 Session.execute.bind_arguments 字典传递。
此字典可由扩展用于 Session 以传递将有助于确定一组数据库连接中的哪一个应该用于调用此语句的参数。
attribute bind_mapper
返回是主“绑定”映射器的 Mapper。
对于调用 ORM 语句的 ORMExecuteState 对象，即 ORMExecuteState.is_orm_statement 属性为 True 的情况，此属性将返回被视为语句的“主”映射器。术语“绑定映射器”指的是 Session 对象可能“绑定”到多个映射类键入的多个 Engine 对象，并且“绑定映射器”确定将选择哪个 Engine 对象。
对于针对单个映射类调用的语句，ORMExecuteState.bind_mapper 旨在是获取此映射器的可靠方法。
版本 1.4.0b2 中的新功能。
另请参阅
ORMExecuteState.all_mappers
attribute execution_options: _ExecuteOptions
当前执行选项的完整字典。
这是语句级选项与本地传递的执行选项的合并。
另请参阅
ORMExecuteState.local_execution_options
Executable.execution_options()
ORM 执行选项
method invoke_statement(statement: Executable | None = None, params: _CoreAnyExecuteParams | None = None, execution_options: OrmExecuteOptionsParameter | None = None, bind_arguments: _BindArguments | None = None) → Result[Any]
执行由此 ORMExecuteState 表示的语句，而不重新调用已经进行过的事件。
此方法本质上执行当前语句的可重入执行，即当前调用 SessionEvents.do_orm_execute() 事件。这样做的用例是为了事件处理程序想要重写如何返回最终 Result 对象，比如从离线缓存检索结果或者将结果从多次执行中连接起来的方案。
当实际处理程序函数在 SessionEvents.do_orm_execute() 中返回 Result 对象，并且传播到调用 Session.execute() 方法的地方时，Session.execute() 方法的其余部分将被抢占，并且 Result 对象将立即返回给 Session.execute() 的调用者。
参数：
statement– 可选的语句，用于代替当前由ORMExecuteState.statement表示的语句。params–
可选的参数字典或参数列表将合并到此ORMExecuteState的现有ORMExecuteState.parameters中。
2.0 版更改：接受参数字典列表进行 executemany 执行。execution_options– 可选的执行选项字典将合并到此ORMExecuteState的现有ORMExecuteState.execution_options中。bind_arguments– 可选的 bind_arguments 字典将在此ORMExecuteState的当前ORMExecuteState.bind_arguments中合并。
返回：
一个带有 ORM 级结果的 Result 对象。
另见
重新执行语句 - 关于 ORMExecuteState.invoke_statement() 的适当用法的背景和示例。
attribute is_column_load
如果操作是刷新现有 ORM 对象上的基于列的属性，则返回 True。
在诸如 Session.refresh() 的操作期间发生，以及当由 defer() 推迟的属性正在加载时，或者由 Session.expire() 直接或通过提交操作而过期的属性正在加载时。
处理程序在进行此类操作时很可能不希望向查询添加任何选项，因为查询应该是直接的主键获取，不应该有任何额外的 WHERE 条件，并且实例旅行的加载器选项已经添加到查询中。
版本 1.4.0b2 中的新功能。
另请参阅
ORMExecuteState.is_relationship_load
attribute is_delete
如果这是一个 DELETE 操作，则返回 True。
2.0.30 版本中的更改：- 该属性对 Select.from_statement() 构造也是真的，该构造本身针对 Delete 构造，例如 select(Entity).from_statement(delete(..))
attribute is_executemany
如果参数是一个包含多个字典且字典数量大于一个的列表，则返回 True。
版本 2.0 中的新功能。
attribute is_from_statement
如果此操作是 Select.from_statement() 操作，则返回 True。
这与 ORMExecuteState.is_select 独立，因为 select().from_statement() 构造也可以与 INSERT/UPDATE/DELETE RETURNING 类型的语句一起使用。ORMExecuteState.is_select 仅在 Select.from_statement() 本身针对 Select 构造时设置。
版本 2.0.30 中的新功能。
attribute is_insert
如果这是一个 INSERT 操作，则返回 True。
在 2.0.30 版本中更改： - 该属性对Select.from_statement()构造也为 True，该构造本身针对Insert构造，例如select(Entity).from_statement(insert(..))
attribute is_orm_statement
如果操作是 ORM 语句，则返回 True。
这表示所调用的 select()、insert()、update()或 delete()包含 ORM 实体作为主体。对于没有 ORM 实体，而只引用Table元数据的语句，它被调用为核心 SQL 语句，并且不发生 ORM 级别的自动化。
attribute is_relationship_load
如果此加载正在代表关系加载对象，则返回 True。
这意味着，加载程序实际上是一个 LazyLoader、SelectInLoader、SubqueryLoader 或类似的加载程序，并且整个发出的 SELECT 语句都是代表关系加载的。
处理程序很可能不希望在发生此类操作时向查询添加任何选项，因为加载程序选项已经能够传播到关系加载程序，并且应已存在。
另请参阅
ORMExecuteState.is_column_load
attribute is_select
如果这是一个 SELECT 操作，则返回 True。
在 2.0.30 版本中更改： - 该属性对Select.from_statement()构造也为 True，该构造本身针对Select构造，例如select(Entity).from_statement(select(..))
attribute is_update
如果这是一个 UPDATE 操作，则返回 True。
在 2.0.30 版本中更改： - 该属性对Select.from_statement()构造也为 True，该构造本身针对Update构造，例如select(Entity).from_statement(update(..))
attribute lazy_loaded_from
正在使用此语句执行进行延迟加载操作的InstanceState。
此属性的主要理由是支持水平分片扩展，在此扩展创建的特定查询执行时间钩子中可用。为此，该属性仅打算在查询执行时间具有意义，而且重要的是不是在此之前的任何时间，包括查询编译时间。
attribute load_options
返回将用于此执行的load_options。
attribute loader_strategy_path
返回当前加载路径的PathRegistry。
此对象表示查询中关系的“路径”，当加载特定对象或集合时。
attribute local_execution_options: _ExecuteOptions
Session.execute() 方法传递的执行选项的字典视图。
这不包括与被调用语句相关的选项。
另请参阅
ORMExecuteState.execution_options
attribute parameters: _CoreAnyExecuteParams | None
传递给 Session.execute() 方法的参数字典。
attribute session: Session
正在使用的 Session。
attribute statement: Executable
被调用的 SQL 语句。
对于像从 Query 检索到的 ORM 选择，这是从 ORM 查询生成的 select 的一个实例。
attribute update_delete_options
返回将用于此执行的 update_delete_options。
method update_execution_options(**opts: Any) → None
使用新值更新本地执行选项。
attribute user_defined_options
与被调用语句关联的 UserDefinedOptions 序列。
class sqlalchemy.orm.Session
管理 ORM 映射对象的持久化操作。
Session 不适用于并发线程。有关详情，请参阅会话是否线程安全？ AsyncSession 是否安全可在并发任务中共享？。
关于 Session 的使用范例请参见使用 Session。
成员
init(), add(), add_all(), begin(), begin_nested(), bind_mapper(), bind_table(), bulk_insert_mappings(), bulk_save_objects(), bulk_update_mappings(), close(), close_all(), commit(), connection(), delete(), deleted, dirty, enable_relationship_loading(), execute(), expire(), expire_all(), expunge(), expunge_all(), flush(), get(), get_bind(), get_nested_transaction(), get_one(), get_transaction(), identity_key(), identity_map, in_nested_transaction(), in_transaction(), info, invalidate(), is_active, is_modified(), merge(), new, no_autoflush, object_session(), prepare(), query(), refresh(), reset(), rollback(), scalar(), scalars()
类签名
类 sqlalchemy.orm.Session (sqlalchemy.orm.session._SessionClassMethods, sqlalchemy.event.registry.EventTarget)
method __init__(bind: _SessionBind | None = None, *, autoflush: bool = True, future: Literal[True] = True, expire_on_commit: bool = True, autobegin: bool = True, twophase: bool = False, binds: Dict[_SessionBindKey, _SessionBind] | None = None, enable_baked_queries: bool = True, info: _InfoType | None = None, query_cls: Type[Query[Any]] | None = None, autocommit: Literal[False] = False, join_transaction_mode: JoinTransactionMode = 'conditional_savepoint', close_resets_only: bool | _NoArg = _NoArg.NO_ARG)
构建一个新的 Session。
还请参阅 sessionmaker 函数，该函数用于生成具有给定参数集的产生 Session 的可调用对象。
参数：
autoflush–
当为True时，所有查询操作将在继续之前对此Session发出一个Session.flush()调用。这是一个方便的功能，使得不需要重复调用Session.flush()以便数据库查询检索结果。
另请参阅
刷新 - 自动刷新的额外背景autobegin–
当请求由操作请求数据库访问时，自动启动事务（即相当于调用Session.begin()）。默认为True。将其设置为False以防止Session在构造后隐式开始事务，以及在调用任何Session.rollback()、Session.commit()或Session.close()方法后隐式开始事务。
2.0 版中的新功能。
另请参阅
禁用自动启动以防止隐式事务bind– 此Session应绑定到的可选Engine或Connection。当指定时，此会话执行的所有 SQL 操作都将通过此连接执行。binds–
一个字典，可以指定任意数量的Engine或Connection对象作为每个实体连接的源。字典的键由任何一系列映射类、任意的用作映射类基础的 Python 类、Table对象和Mapper对象组成。然后字典的值是Engine或较少常见的Connection对象的实例。针对特定映射类进行的操作将查询此字典，以确定用于特定 SQL 操作的最接近匹配实体为何。解析的完整启发式方法在Session.get_bind()中描述。用法如下：
Session = sessionmaker(binds={ SomeMappedClass: create_engine('postgresql+psycopg2://engine1'), SomeDeclarativeBase: create_engine('postgresql+psycopg2://engine2'), some_mapper: create_engine('postgresql+psycopg2://engine3'), some_table: create_engine('postgresql+psycopg2://engine4'), })
- 另请参阅
分区策略（例如每个会话的多个数据库后端）Session.bind_mapper()Session.bind_table()Session.get_bind() class_– 指定除了sqlalchemy.orm.session.Session之外的另一个类，该类应该由返回的类使用。 这是唯一一个本地于sessionmaker函数的参数，并且不直接发送到Session的构造函数。enable_baked_queries–
经典； 默认为True。 由sqlalchemy.ext.baked扩展消耗的一个参数，用于确定是否应该缓存“烘焙查询”，正如该扩展的正常操作一样。 当设置为False时，该特定扩展所使用的缓存被禁用。
从版本 1.4 开始更改：sqlalchemy.ext.baked扩展是遗留的，不被 SQLAlchemy 的任何内部使用。 因此，该标志仅影响在其自己的代码中明确使用此扩展的应用程序。expire_on_commit–
默认为True。 当为True时，每次commit()后所有实例都将完全过期，以便在完成事务后的所有属性/对象访问从最新的数据库状态加载。
另请参阅
提交
future–
已弃用； 此标志始终为 True。
另请参阅
SQLAlchemy 2.0 - 主要迁移指南info– 可选的与此Session关联的任意数据的字典。 可通过Session.info属性访问。 请注意，该字典在构造时被复制，因此对每个Session字典的修改将局限于该Session。query_cls– 应该用于创建新的查询对象的类，由Session.query()方法返回。 默认为Query。twophase– 当为True时，所有事务都将作为“两阶段”事务启动，即使用正在使用的数据库的“两阶段”语义以及 XID。在每个附加数据库上发出了所有附加数据库的flush()之后，在commit()期间，将调用每个数据库的TwoPhaseTransaction的TwoPhaseTransaction.prepare()方法。这允许每个数据库在提交每个事务之前回滚整个事务。autocommit–autocommit关键字出现是为了向后兼容，但必须保持其默认值为False。join_transaction_mode–描述了在给定绑定是已经在此Session范围之外开始事务的Connection时要采取的事务行为；换句话说，Connection.in_transaction()方法返回 True。以下行为仅在Session实际使用给定的连接时才生效；也就是说，诸如Session.execute()、Session.connection()等方法实际上被调用：
"conditional_savepoint"- 这是默认值。如果给定的Connection在事务中开始但没有保存点，则使用"rollback_only"。如果Connection此外还在保存点中，换句话说，Connection.in_nested_transaction()方法返回 True，则使用"create_savepoint"。"conditional_savepoint"行为试图利用 SAVEPOINT 以保持现有事务的状态不变，但只有在已经存在 SAVEPOINT 的情况下才会这样做；否则，不假定正在使用的后端具有足够的 SAVEPOINT 支持，因为此功能的可用性会有所变化。"conditional_savepoint"还试图与之前的Session行为建立大致的向后兼容性，适用于未设置特定模式的应用程序。建议使用其中一种显式设置。"create_savepoint"-Session将在所有情况下使用Connection.begin_nested()来创建自己的事务。该事务本质上“在顶部”上使用给定Connection上已打开的任何现有事务；如果底层数据库和正在使用的驱动程序完全且不破损地支持 SAVEPOINT，则外部事务将在Session的生命周期内保持不受影响。"create_savepoint"模式对于将Session集成到测试套件中并使外部启动的事务保持不受影响是最有用的；但是，它依赖于底层驱动程序和数据库对 SAVEPOINT 的正确支持。
提示
当使用 SQLite 时，Python 3.11 中包含的 SQLite 驱动程序在某些情况下未正确处理 SAVEPOINTs，需要使用解决方法。详见 Serializable isolation / Savepoints / Transactional DDL 和 Serializable isolation / Savepoints / Transactional DDL (asyncio version) 部分。"control_fully"-Session将控制给定事务作为自己的事务；Session.commit()将在事务上调用.commit()，Session.rollback()将在事务上调用.rollback()，Session.close()将调用事务上的.rollback。
提示
此使用模式等同于 SQLAlchemy 1.4 处理具有现有 SAVEPOINT 的Connection的方式（即Connection.begin_nested()）;Session将完全控制现有的 SAVEPOINT。"rollback_only"-Session仅会接管给定事务的.rollback()调用；.commit()调用不会传播到给定事务。.close()调用不会对给定事务产生影响。
提示
此使用模式等同于 SQLAlchemy 1.4 处理具有现有常规数据库事务的Connection的方式（即Connection.begin()）；Session将传播Session.rollback()调用到底层事务，但不会传播Session.commit()或Session.close()调用。
- 自 2.0.0rc1 版本新增。
close_resets_only-
默认为True。确定会话在调用.close()后是否应该重置自身，还是应该处于不再可用的状态，禁用重用。
自 2.0.22 版本新增：添加标志close_resets_only。未来的 SQLAlchemy 版本可能会将此标志的默认值更改为False。
另请参阅
关闭 - 关于Session.close()和Session.reset()语义的详细信息。
method add(instance: object, _warn: bool = True) → None
将一个对象放入此Session中。
传递给Session.add()方法时处于瞬时状态的对象将移动到挂起状态，直到下一次刷新，然后它们将转移到持久化状态。
传递给Session.add()方法时处于分离状态的对象将直接转移到持久化状态。
如果由Session使用的事务被回滚，那些在传递给Session.add()时处于瞬态的对象将会被移回到瞬态状态，并且不再存在于这个Session中。
另请参见
Session.add_all()
添加新项目或现有项目 - 在使用会话的基础知识
method add_all(instances: Iterable[object]) → None
将给定的实例集合添加到此Session中。
请参阅Session.add()的文档以获取一般行为描述。
另请参见
Session.add()
添加新项目或现有项目 - 在使用会话的基础知识
method begin(nested: bool = False) → SessionTransaction
在此Session上开始事务或嵌套事务（如果尚未开始）。
Session对象具有autobegin行为，因此通常不需要显式调用Session.begin()方法。但是，它可以用来控制何时开始事务状态的范围。
当用于开始最外层事务时，如果此Session已经处于事务中，则会引发错误。
参数：
nested – 如果为 True，则开始一个 SAVEPOINT 事务，并等效于调用Session.begin_nested()。有关 SAVEPOINT 事务的文档，请参阅使用 SAVEPOINT。
返回：
SessionTransaction对象。注意SessionTransaction充当 Python 上下文管理器，允许在“with”块中使用Session.begin()。请参阅显式开始以获取示例。
另请参见
自动开始
管理事务
Session.begin_nested()
method begin_nested() → SessionTransaction
在此Session上开始“嵌套”事务，例如 SAVEPOINT。
目标数据库和相关驱动程序必须支持 SQL SAVEPOINT，以使此方法正常工作。
有关 SAVEPOINT 事务的文档，请参阅 使用 SAVEPOINT。
返回：
SessionTransaction 对象。请注意，SessionTransaction 作为上下文管理器，允许在“with”块中使用 Session.begin_nested()。请参阅 使用 SAVEPOINT 获取使用示例。
另请参阅
使用 SAVEPOINT
可串行化隔离 / Savepoints / 事务性 DDL - 使用 SQLite 驱动程序时，为使 SAVEPOINT 正常工作需要特殊的解决方法。对于 asyncio 案例，请参阅 可串行化隔离 / Savepoints / 事务性 DDL（asyncio 版本） 部分。
method bind_mapper(mapper: _EntityBindKey[_O], bind: _SessionBind) → None
将 Mapper 或任意 Python 类与“bind”关联，例如一个 Engine 或 Connection。
给定的实体被添加到 Session.get_bind() 方法使用的查找中。
参数：
mapper– 一个Mapper对象，或者一个映射类的实例，或者任何作为一组映射类基础的 Python 类。bind– 一个Engine或Connection对象。
另请参阅
分区策略（例如，每个 Session 多个数据库后端）
Session.binds
Session.bind_table()
method bind_table(table: TableClause, bind: Engine | Connection) → None
将 Table 与“bind”关联，例如一个 Engine 或 Connection。
给定的 Table 被添加到 Session.get_bind() 方法使用的查找中。
参数：
table– 一个Table对象，通常是 ORM 映射的目标，或者存在于可选择的映射中。bind- 一个Engine或Connection对象。
另请参阅
分区策略（例如每个 Session 的多个数据库后端）
Session.binds
Session.bind_mapper()
method bulk_insert_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False) → None
执行给定映射字典列表的批量插入。
传统特性
该方法是 SQLAlchemy 2.0 系列的一个传统特性。对于现代的批量插入和更新，请参见 ORM 批量插入语句和 ORM 按主键批量更新部分。2.0 API 共享了与该方法的实现细节，并添加了新的特性。
参数：
mapper- 一个映射类，或者实际的Mapper对象，表示映射列表中所代表的单一对象种类。mappings- 一系列字典，每个字典包含要插入的映射行的状态，以映射类上的属性名称表示。如果映射涉及多个表，例如连接继承映射，则每个字典必须包含要填充到所有表中的所有键。return_defaults-
当为 True 时，INSERT 过程将被修改以确保新生成的主键值将被获取。该参数的理由通常是为了使连接表继承映射能够批量插入。
注意
对于不支持 RETURNING 的后端，Session.bulk_insert_mappings.return_defaults参数可能会显著降低性能，因为 INSERT 语句无法再批量处理。有关受影响的后端的背景信息，请参阅 INSERT 语句的“插入多个值”行为。render_nulls-
当为 True 时，None值将导致在 INSERT 语句中包含一个 NULL 值，而不是将列从 INSERT 中省略。这允许所有被 INSERT 的行具有相同的列集，从而允许将完整的行集批量发送到 DBAPI。通常，每个包含与上一行不同的 NULL 值组合的列集必须从渲染的 INSERT 语句中省略不同的列系列，这意味着必须作为单独的语句发出。通过传递此标志，可以确保将完整的行集批量处理为一个批次；但成本是，通过省略列调用的服务器端默认值将被跳过，因此必须注意确保这些不是必需的。
警告
当设置此标志时，不会调用服务器端默认的 SQL 值，对于那些作为 NULL 插入的列；NULL 值将被显式发送。必须注意确保整个操作不需要调用服务器端默认函数。
另请参阅
启用 ORM 的 INSERT、UPDATE 和 DELETE 语句
Session.bulk_save_objects()
Session.bulk_update_mappings()
method bulk_save_objects(objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True) → None
对给定对象列表执行批量保存。
传统功能
该方法是 SQLAlchemy 2.0 系列的传统功能。对于现代的批量 INSERT 和 UPDATE，请参见 ORM 批量 INSERT 语句和 ORM 按主键批量 UPDATE 部分。
对于一般的 INSERT 和 UPDATE 现有 ORM 映射对象，建议使用标准的工作单元数据管理模式，介绍在 SQLAlchemy 统一教程中的 ORM 数据操作。SQLAlchemy 2.0 现在使用现代方言的“Insert Many Values”行为用于 INSERT 语句，解决了以前批量 INSERT 速度慢的问题。
参数：
objects–
映射对象实例的序列。映射对象按原样持久化，并且之后不与Session关联。
对于每个对象，无论对象是作为 INSERT 还是 UPDATE 发送的，都取决于传统操作中Session使用的相同规则；如果对象具有InstanceState.key属性设置，则假定对象为“分离”，将导致 UPDATE。否则，将使用 INSERT。
在 UPDATE 的情况下，语句根据哪些属性已更改而分组，并因此成为每个 SET 子句的主题。如果update_changed_only为 False，则每个对象中存在的所有属性都将应用于 UPDATE 语句，这有助于将语句组合成更大的 executemany()，并且还将减少检查属性历史的开销。return_defaults- 当为 True 时，缺少生成默认值的值的行，即整数主键默认值和序列，将逐个插入，以便主键值可用。特别是，这将允许加入继承和其他多表映射正确插入，而无需提前提供主键值；但是，Session.bulk_save_objects.return_defaults会大大降低该方法的性能增益。强烈建议使用标准的Session.add_all()方法。update_changed_only- 当为 True 时，根据每个状态中已记录更改的属性来渲染 UPDATE 语句。当为 False 时，所有存在的属性都将渲染到 SET 子句中，除了主键属性。preserve_order- 当为 True 时，插入和更新的顺序与给定对象的顺序完全匹配。当为 False 时，常见类型的对象被分组为插入和更新，以便提供更多的批处理机会。
另请参阅
ORM 启用的 INSERT、UPDATE 和 DELETE 语句
Session.bulk_insert_mappings()
Session.bulk_update_mappings()
method bulk_update_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]) → None
对给定的映射字典列表执行批量更新。
传统特性
该方法是 SQLAlchemy 2.0 系列的一个传统特性。对于现代的批量 INSERT 和 UPDATE，请参见 ORM 批量 INSERT 语句和 ORM 按主键批量 UPDATE 部分。2.0 API 与此方法共享实现细节，并添加了新功能。
参数：
mapper- 一个映射类，或者实际的Mapper对象，表示映射列表中表示的单一对象类型。mappings- 一个字典序列，每个字典包含要更新的映射行的状态，以映射类上的属性名称表示。如果映射涉及多个表，比如联接继承映射，每个字典可能包含与所有表对应的键。所有存在且不是主键的键将应用于 UPDATE 语句的 SET 子句；需要的主键值将应用于 WHERE 子句。
另请参见
ORM-Enabled INSERT、UPDATE 和 DELETE 语句
Session.bulk_insert_mappings()
Session.bulk_save_objects()
method close() → None
结束由此 Session 使用的事务资源和 ORM 对象。
这会清除与此 Session 关联的所有 ORM 对象，结束任何正在进行的事务，并释放此 Session 从相关 Engine 对象中检出的任何 Connection 对象。然后，该操作将 Session 置于可以再次使用的状态。
提示
在默认运行模式下，Session.close() 方法不会阻止该 Session 再次使用。 Session 本身实际上并没有一个独立的“关闭”状态；它只是意味着 Session 将释放所有数据库连接和 ORM 对象。
将参数 Session.close_resets_only 设置为 False 将使 close 最终化，这意味着会禁止对会话的任何进一步操作。
从 1.4 版本开始变更：Session.close() 方法不会立即创建一个新的 SessionTransaction 对象；相反，只有在再次使用 Session 进行数据库操作时才会创建新的 SessionTransaction。
另请参见
关闭 - 关于Session.close()和Session.reset()语义的详细信息。
Session.reset() - 一种类似的方法，其行为类似于close()，参数为Session.close_resets_only设置为True。
classmethod close_all() → None
继承自 sqlalchemy.orm.session._SessionClassMethods.close_all 方法的 sqlalchemy.orm.session._SessionClassMethods
关闭所有内存中的会话。
自版本 1.3 起已弃用：Session.close_all()方法已弃用，将在将来的版本中删除。请参考close_all_sessions()。
method commit() → None
刷新待处理的更改并提交当前事务。
当 COMMIT 操作完成时，所有对象都完全过期，擦除其内部内容，当下次访问这些对象时，将自动重新加载。在此期间，这些对象处于过期状态，并且如果从Session中分离出来，则不会起作用。此外，当使用基于 asyncio 的 API 时，不支持此重新加载操作。Session.expire_on_commit参数可用于禁用此行为。
当Session中没有事务时，表示自上次调用Session.commit()以来没有对此Session执行任何操作时，该方法将开始并提交一个仅内部的“逻辑”事务，通常不会影响数据库，除非检测到有待提交的刷新更改，但仍然会调用事件处理程序和对象过期规则。
最外层的数据库事务会无条件提交，自动释放任何生效的 SAVEPOINT。
另请参阅
提交
管理事务
在使用 AsyncSession 时避免隐式 IO
method connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → Connection
返回一个与该Session对象的事务状态对应的Connection对象。
返回当前事务对应的 Connection，或者如果没有进行中的事务，则开始新的事务并返回 Connection（请注意，在第一个 SQL 语句被发出之前，与 DBAPI 之间不会建立事务状态）。
多重绑定或未绑定的 Session 对象中的歧义可以通过任何可选关键字参数解决。最终将使用 get_bind() 方法进行解决。
参数：
bind_arguments– 绑定参数字典。可能包括“mapper”，“bind”，“clause”等其他传递给Session.get_bind()的自定义参数。execution_options–
一个执行选项字典，当首次获得连接时将传递给Connection.execution_options()。如果连接已经存在于Session中，将发出警告并忽略参数。
另请参阅
设置事务隔离级别 / DBAPI AUTOCOMMIT
method delete(instance: object) → None
将实例标记为已删除。
假设传入的对象在调用该方法后处于 持久化 或 分离 状态；在此方法被调用后，对象将保持 持久化 状态，直到下一次刷新操作进行。在此期间，该对象也将是 Session.deleted 集合的成员。
当下一次刷新操作进行时，对象将移动到 已删除 状态，表示在当前事务中为其行发出了 DELETE 语句。当事务成功提交时，已删除对象将移动到 分离 状态，并且不再存在于此 Session 中。
另请参阅
删除 - 在 使用会话的基础知识
attribute deleted
所有在此 Session 中标记为 ‘deleted’ 的实例集合。
attribute dirty
所有被认为是脏的持久化实例集合。
例如：
some_mapped_object in session.dirty
当实例被修改但未删除时被视为脏。
请注意，此“脏”计算是“乐观”的；大多数属性设置或集合修改操作都将将实例标记为“脏”，并将其放入此集合中，即使属性的值没有净变化。在刷新时，将每个属性的值与其先前保存的值进行比较，如果没有净变化，则不会执行任何 SQL 操作（这是一项更昂贵的操作，因此仅在刷新时执行）。
要检查实例是否有可操作的净变化来修改其属性，请使用Session.is_modified()方法。
method enable_relationship_loading(obj: object) → None
将对象与此Session关联以进行相关对象加载。
警告
enable_relationship_loading()存在以服务于特殊用例，并不建议用于一般用途。
使用relationship()映射的属性的访问将尝试使用此Session作为连接源从数据库加载值。值将根据此对象上存在的外键和主键值加载 - 如果不存在，则这些关系将不可用。
对象将附加到此会话，但不会参与任何持久性操作；它的状态对于几乎所有目的都将保持“瞬态”或“分离”，除了关系加载的情况。
还要注意，反向引用通常不会按预期工作。如果目标对象上的关系绑定属性发生更改，则可能不会触发反向引用事件，如果有效值已从保存外键值的值中加载，则不会触发事件。
Session.enable_relationship_loading()方法类似于relationship()上的load_on_pending标志。与该标志不同，Session.enable_relationship_loading()允许对象保持瞬态，同时仍然能够加载相关项目。
要使一个临时对象与Session相关联，可以通过Session.enable_relationship_loading()将其添加到Session中。如果该对象代表数据库中现有的标识，则应使用Session.merge()进行合并。
当 ORM 正常使用时，Session.enable_relationship_loading()不会改善行为 - 对象引用应该在对象级别而不是在外键级别构建，以便它们在 flush()继续之前以普通方式存在。此方法不适用于一般用途。
另请参见
relationship.load_on_pending - 此标志允许在待处理项目上对多对一进行每关系加载。
make_transient_to_detached() - 允许将对象添加到Session中而不发出 SQL，然后在访��时取消过期属性。
method execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, _parent_execute_state: Any | None = None, _add_event: Any | None = None) → Result[Any]
执行一个 SQL 表达式构造。
返回一个代表语句执行结果的Result对象。
例如：
from sqlalchemy import select result = session.execute( select(User).where(User.id == 5) )
Session.execute()的 API 契约类似于Connection.execute()的契约，是Connection的 2.0 风格版本。
从版本 1.4 开始更改：当使用 2.0 风格的 ORM 用法时，Session.execute()方法现在是 ORM 语句执行的主要点。
参数：
statement– 一个可执行的语句（即一个Executable表达式，如select()）。params– 可选字典，或包含绑定参数值的字典列表。如果是单个字典，则执行单行; 如果是字典列表，则将调用“executemany”。每个字典中的键必须与语句中存在的参数名称相对应。execution_options–
可选的执行选项字典，将与语句执行相关联。此字典可以提供Connection.execution_options()接受的选项的子集，并且还可以提供仅在 ORM 上下文中理解的其他选项。
另请参阅
ORM 执行选项 - ORM 特定的执行选项bind_arguments– 用于确定绑定的其他参数字典。可以包括“mapper”，“bind”或其他自定义参数。此字典的内容将传递给Session.get_bind()方法。
返回：
一个Result对象。
method expire(instance: object, attribute_names: Iterable[str] | None = None) → None
使实例上的属性过期。
标记实例的属性为过期。下次访问过期属性时，将向Session对象的当前事务上下文发出查询，以加载给定实例的所有过期属性。请注意，高度隔离的事务将返回与该事务中先前读取的相同值，而不管该事务外的数据库状态发生了什么变化。
要同时使Session中的所有对象过期，请使用Session.expire_all()。
当调用Session.rollback()或Session.commit()方法时，Session对象的默认行为是使所有状态过期，以便为新事务加载新状态。因此，仅在当前事务中发出非 ORM SQL 语句的特定情况下调用Session.expire()才有意义。
参数：
instance– 要刷新的实例。attribute_names– 可选的字符串属性名称列表，指示要过期的属性子集。
另请参阅
刷新/过期 - 入门材料
Session.expire()
Session.refresh()
Query.populate_existing()
method expire_all() → None
使此会话中的所有持久实例过期。
下次访问持久实例上的任何属性时，将使用Session对象的当前事务上下文发出查询，以加载给定实例的所有过期属性。请注意，高度隔离的事务将返回与之前在同一事务中读取的相同值，而不考虑该事务之外的数据库状态的更改。
要使个别对象和这些对象上的个别属性过期，请使用Session.expire()。
当调用Session.rollback()或Session.commit()方法时，默认情况下，Session对象会将所有状态过期，以便为新的事务加载新的状态。因此，通常不需要调用Session.expire_all()，假设事务是隔离的。
另请参阅
刷新 / 过期 - 入门材料
Session.expire()
Session.refresh()
Query.populate_existing()
method expunge(instance: object) → None
从这个Session中移除实例。
这将释放对该实例的所有内部引用。根据expunge级联规则将应用级联。
method expunge_all() → None
从这个Session中移除所有对象实例。
这相当于在这个Session中调用expunge(obj)来移除所有对象。
method flush(objects: Sequence[Any] | None = None) → None
刷新所有对象更改到数据库。
将所有待定的对象创建、删除和修改写入数据库，作为 INSERT、DELETE、UPDATE 等操作。操作会自动按照会话的工作单元依赖解决器进行排序。
数据库操作将在当前事务上下文中发出，并且不会影响事务的状态，除非发生错误，此时整个事务都会回滚。在事务中随时可以刷新（flush()）以将更改从 Python 移动到数据库的事务缓冲区。
SqlAlchemy 2.0 中文文档（二十五）（4）https://developer.aliyun.com/article/1560586
