Bug
Links
def __init__(self, bind: 'Optional[_SessionBind]' = None, *, autoflush: 'bool' = True, future: 'Literal[True]' = True, expire_on_commit: 'bool' = True, autobegin: 'bool' = True, twophase: 'bool' = False, binds: 'Optional[Dict[_SessionBindKey, _SessionBind]]' = None, enable_baked_queries: 'bool' = True, info: 'Optional[_InfoType]' = None, query_cls: 'Optional[Type[Query[Any]]]' = None, autocommit: 'Literal[False]' = False, join_transaction_mode: 'JoinTransactionMode' = 'conditional_savepoint', close_resets_only: 'Union[bool, _NoArg]' = _NoArg.NO_ARG)
Construct a new :class:`_orm.Session`.
See also the :class:`.sessionmaker` function which is used to
generate a :class:`.Session`-producing callable with a given
set of arguments.
:param autoflush: When ``True``, all query operations will issue a
:meth:`~.Session.flush` call to this ``Session`` before proceeding.
This is a convenience feature so that :meth:`~.Session.flush` need
not be called repeatedly in order for database queries to retrieve
results.
.. seealso::
:ref:`session_flushing` - additional background on autoflush
:param autobegin: Automatically start transactions (i.e. equivalent to
invoking :meth:`_orm.Session.begin`) when database access is
requested by an operation. Defaults to ``True``. Set to
``False`` to prevent a :class:`_orm.Session` from implicitly
beginning transactions after construction, as well as after any of
the :meth:`_orm.Session.rollback`, :meth:`_orm.Session.commit`,
or :meth:`_orm.Session.close` methods are called.
.. versionadded:: 2.0
.. seealso::
:ref:`session_autobegin_disable`
:param bind: An optional :class:`_engine.Engine` or
:class:`_engine.Connection` to
which this ``Session`` should be bound. When specified, all SQL
operations performed by this session will execute via this
connectable.
:param binds: A dictionary which may specify any number of
:class:`_engine.Engine` or :class:`_engine.Connection`
objects as the source of
connectivity for SQL operations on a per-entity basis. The keys
of the dictionary consist of any series of mapped classes,
arbitrary Python classes that are bases for mapped classes,
:class:`_schema.Table` objects and :class:`_orm.Mapper` objects.
The
values of the dictionary are then instances of
:class:`_engine.Engine`
or less commonly :class:`_engine.Connection` objects.
Operations which
proceed relative to a particular mapped class will consult this
dictionary for the closest matching entity in order to determine
which :class:`_engine.Engine` should be used for a particular SQL
operation. The complete heuristics for resolution are
described at :meth:`.Session.get_bind`. Usage looks like::
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"),
}
)
.. seealso::
:ref:`session_partitioning`
:meth:`.Session.bind_mapper`
:meth:`.Session.bind_table`
:meth:`.Session.get_bind`
:param \class_: Specify an alternate class other than
``sqlalchemy.orm.session.Session`` which should be used by the
returned class. This is the only argument that is local to the
:class:`.sessionmaker` function, and is not sent directly to the
constructor for ``Session``.
:param enable_baked_queries: legacy; defaults to ``True``.
A parameter consumed
by the :mod:`sqlalchemy.ext.baked` extension to determine if
"baked queries" should be cached, as is the normal operation
of this extension. When set to ``False``, caching as used by
this particular extension is disabled.
.. versionchanged:: 1.4 The ``sqlalchemy.ext.baked`` extension is
legacy and is not used by any of SQLAlchemy's internals. This
flag therefore only affects applications that are making explicit
use of this extension within their own code.
:param expire_on_commit: Defaults to ``True``. When ``True``, all
instances will be fully expired after each :meth:`~.commit`,
so that all attribute/object access subsequent to a completed
transaction will load from the most recent database state.
.. seealso::
:ref:`session_committing`
:param future: Deprecated; this flag is always True.
.. seealso::
:ref:`migration_20_toplevel`
:param info: optional dictionary of arbitrary data to be associated
with this :class:`.Session`. Is available via the
:attr:`.Session.info` attribute. Note the dictionary is copied at
construction time so that modifications to the per-
:class:`.Session` dictionary will be local to that
:class:`.Session`.
:param query_cls: Class which should be used to create new Query
objects, as returned by the :meth:`~.Session.query` method.
Defaults to :class:`_query.Query`.
:param twophase: When ``True``, all transactions will be started as
a "two phase" transaction, i.e. using the "two phase" semantics
of the database in use along with an XID. During a
:meth:`~.commit`, after :meth:`~.flush` has been issued for all
attached databases, the :meth:`~.TwoPhaseTransaction.prepare`
method on each database's :class:`.TwoPhaseTransaction` will be
called. This allows each database to roll back the entire
transaction, before each transaction is committed.
:param autocommit: the "autocommit" keyword is present for backwards
compatibility but must remain at its default value of ``False``.
:param join_transaction_mode: Describes the transactional behavior to
take when a given bind is a :class:`_engine.Connection` that
has already begun a transaction outside the scope of this
:class:`_orm.Session`; in other words the
:meth:`_engine.Connection.in_transaction()` method returns True.
The following behaviors only take effect when the :class:`_orm.Session`
**actually makes use of the connection given**; that is, a method
such as :meth:`_orm.Session.execute`, :meth:`_orm.Session.connection`,
etc. are actually invoked:
* ``"conditional_savepoint"`` - this is the default. if the given
:class:`_engine.Connection` is begun within a transaction but
does not have a SAVEPOINT, then ``"rollback_only"`` is used.
If the :class:`_engine.Connection` is additionally within
a SAVEPOINT, in other words
:meth:`_engine.Connection.in_nested_transaction()` method returns
True, then ``"create_savepoint"`` is used.
``"conditional_savepoint"`` behavior attempts to make use of
savepoints in order to keep the state of the existing transaction
unchanged, but only if there is already a savepoint in progress;
otherwise, it is not assumed that the backend in use has adequate
support for SAVEPOINT, as availability of this feature varies.
``"conditional_savepoint"`` also seeks to establish approximate
backwards compatibility with previous :class:`_orm.Session`
behavior, for applications that are not setting a specific mode. It
is recommended that one of the explicit settings be used.
* ``"create_savepoint"`` - the :class:`_orm.Session` will use
:meth:`_engine.Connection.begin_nested()` in all cases to create
its own transaction. This transaction by its nature rides
"on top" of any existing transaction that's opened on the given
:class:`_engine.Connection`; if the underlying database and
the driver in use has full, non-broken support for SAVEPOINT, the
external transaction will remain unaffected throughout the
lifespan of the :class:`_orm.Session`.
The ``"create_savepoint"`` mode is the most useful for integrating
a :class:`_orm.Session` into a test suite where an externally
initiated transaction should remain unaffected; however, it relies
on proper SAVEPOINT support from the underlying driver and
database.
.. tip:: When using SQLite, the SQLite driver included through
Python 3.11 does not handle SAVEPOINTs correctly in all cases
without workarounds. See the sections
:ref:`pysqlite_serializable` and :ref:`aiosqlite_serializable`
for details on current workarounds.
* ``"control_fully"`` - the :class:`_orm.Session` will take
control of the given transaction as its own;
:meth:`_orm.Session.commit` will call ``.commit()`` on the
transaction, :meth:`_orm.Session.rollback` will call
``.rollback()`` on the transaction, :meth:`_orm.Session.close` will
call ``.rollback`` on the transaction.
.. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would
handle a :class:`_engine.Connection` given with an existing
SAVEPOINT (i.e. :meth:`_engine.Connection.begin_nested`); the
:class:`_orm.Session` would take full control of the existing
SAVEPOINT.
* ``"rollback_only"`` - the :class:`_orm.Session` will take control
of the given transaction for ``.rollback()`` calls only;
``.commit()`` calls will not be propagated to the given
transaction. ``.close()`` calls will have no effect on the
given transaction.
.. tip:: This mode of use is equivalent to how SQLAlchemy 1.4 would
handle a :class:`_engine.Connection` given with an existing
regular database transaction (i.e.
:meth:`_engine.Connection.begin`); the :class:`_orm.Session`
would propagate :meth:`_orm.Session.rollback` calls to the
underlying transaction, but not :meth:`_orm.Session.commit` or
:meth:`_orm.Session.close` calls.
.. versionadded:: 2.0.0rc1
:param close_resets_only: Defaults to ``True``. Determines if
the session should reset itself after calling ``.close()``
or should pass in a no longer usable state, disabling re-use.
.. versionadded:: 2.0.22 added flag ``close_resets_only``.
A future SQLAlchemy version may change the default value of
this flag to ``False``.
.. seealso::
:ref:`session_closing` - Detail on the semantics of
:meth:`_orm.Session.close` and :meth:`_orm.Session.reset`.
Améliorations / Corrections
Vous avez des améliorations (ou des corrections) à proposer pour ce document : je vous remerçie par avance de m'en faire part, cela m'aide à améliorer le site.
Emplacement :
Description des améliorations :