class sessionmaker(_SessionClassMethods, Generic[
A configurable :class:`.Session` factory. The :class:`.sessionmaker` factory generates new :class:`.Session` objects when called, creating them given the configurational arguments established here. e.g.:: 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() Context manager use is optional; otherwise, the returned :class:`_orm.Session` object may be closed explicitly via the :meth:`_orm.Session.close` method. Using a ``try:/finally:`` block is optional, however will ensure that the close takes place even if there are database errors:: session = Session() try: session.add(some_object) session.add(some_other_object) session.commit() finally: session.close() :class:`.sessionmaker` acts as a factory for :class:`_orm.Session` objects in the same way as an :class:`_engine.Engine` acts as a factory for :class:`_engine.Connection` objects. In this way it also includes a :meth:`_orm.sessionmaker.begin` method, that provides a context manager which both begins and commits a transaction, as well as closes out the :class:`_orm.Session` when complete, rolling back the transaction if any errors occur:: Session = sessionmaker(engine) with Session.begin() as session: session.add(some_object) session.add(some_other_object) # commits transaction, closes session .. versionadded:: 1.4 When calling upon :class:`_orm.sessionmaker` to construct a :class:`_orm.Session`, keyword arguments may also be passed to the method; these arguments will override that of the globally configured parameters. Below we use a :class:`_orm.sessionmaker` bound to a certain :class:`_engine.Engine` to produce a :class:`_orm.Session` that is instead bound to a specific :class:`_engine.Connection` procured from that engine:: Session = sessionmaker(engine) # bind an individual session to a connection with engine.connect() as connection: with Session(bind=connection) as session: # work with session The class also includes a method :meth:`_orm.sessionmaker.configure`, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent :class:`.Session` objects generated. This is usually used to associate one or more :class:`_engine.Engine` objects with an existing :class:`.sessionmaker` factory before it is first used:: # 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 .. seealso:: :ref:`session_getting` - introductory text on creating sessions using :class:`.sessionmaker`.
| Method | __call__ |
Produce a new :class:`.Session` object using the configuration established in this :class:`.sessionmaker`. |
| Method | __init__ |
Construct a new :class:`.sessionmaker`. |
| Method | __repr__ |
Undocumented |
| Method | begin |
Produce a context manager that both provides a new :class:`_orm.Session` as well as a transaction that commits. |
| Method | configure |
(Re)configure the arguments for this sessionmaker. |
| Instance Variable | class_ |
Undocumented |
| Instance Variable | kw |
Undocumented |
Inherited from _SessionClassMethods:
| Class Method | close |
Close *all* sessions in memory. |
| Class Method | identity |
Return an identity key. |
| Class Method | object |
Return the :class:`.Session` to which an object belongs. |
Produce a new :class:`.Session` object using the configuration established in this :class:`.sessionmaker`. In Python, the ``__call__`` method is invoked on an object when it is "called" in the same way as a function:: Session = sessionmaker(some_engine) session = Session() # invokes sessionmaker.__call__()
Optional[ = ..., *, class_: Type[, autoflush: bool = ..., expire_on_commit: bool = ..., info: Optional[ = ..., **kw: Any):sessionmaker[, bind: Optional[ = ..., *, autoflush: bool = ..., expire_on_commit: bool = ..., info: Optional[ = ..., **kw: Any):Construct a new :class:`.sessionmaker`. All arguments here except for ``class_`` correspond to arguments accepted by :class:`.Session` directly. See the :meth:`.Session.__init__` docstring for more details on parameters. :param bind: a :class:`_engine.Engine` or other :class:`.Connectable` with which newly created :class:`.Session` objects will be associated. :param class\_: class to use in order to create new :class:`.Session` objects. Defaults to :class:`.Session`. :param autoflush: The autoflush setting to use with newly created :class:`.Session` objects. .. seealso:: :ref:`session_flushing` - additional background on autoflush :param expire_on_commit=True: the :paramref:`_orm.Session.expire_on_commit` setting to use with newly created :class:`.Session` objects. :param info: optional dictionary of information that will be available via :attr:`.Session.info`. Note this dictionary is *updated*, not replaced, when the ``info`` parameter is specified to the specific :class:`.Session` construction operation. :param \**kw: all other keyword arguments are passed to the constructor of newly created :class:`.Session` objects.
Produce a context manager that both provides a new :class:`_orm.Session` as well as a transaction that commits. e.g.:: Session = sessionmaker(some_engine) with Session.begin() as session: session.add(some_object) # commits transaction, closes session .. versionadded:: 1.4