sqlalchemy.orm.session.sessionmaker

class documentation

class sessionmaker(_SessionClassMethods):

A configurable .Session factory.

The .sessionmaker factory generates new .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://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 _orm.Session object may be closed explicitly via the _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()

.sessionmaker acts as a factory for _orm.Session objects in the same way as an _engine.Engine acts as a factory for _engine.Connection objects. In this way it also includes a _orm.sessionmaker.begin method, that provides a context manager which both begins and commits a transaction, as well as closes out the _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

New in version 1.4.

When calling upon _orm.sessionmaker to construct a _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 _orm.sessionmaker bound to a certain _engine.Engine to produce a _orm.Session that is instead bound to a specific _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 _orm.sessionmaker.configure, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent .Session objects generated. This is usually used to associate one or more _engine.Engine objects with an existing .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

See Also

:ref:`session_getting` - introductory text on creating sessions using .sessionmaker.

Method	`__call__`	Produce a new `.Session` object using the configuration established in this `.sessionmaker`.
Method	`__init__`	Construct a new `.sessionmaker`.
Method	`__repr__`	Undocumented
Method	`begin`	Produce a context manager that both provides a new `_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_all`	Close all sessions in memory.
Class Method	`identity_key`	Return an identity key.
Class Method	`object_session`	Return the `.Session` to which an object belongs.

def __call__(self, **local_kw):

Produce a new .Session object using the configuration established in this .sessionmaker.

In Python, the __call__ method is invoked on an object when it is "called" in the same way as a function:

Session = sessionmaker()
session = Session()  # invokes sessionmaker.__call__()

def __init__(self, bind=None, class_=Session, autoflush=True, autocommit=False, expire_on_commit=True, info=None, **kw):

Construct a new .sessionmaker.

All arguments here except for class_ correspond to arguments accepted by .Session directly. See the .Session.__init__ docstring for more details on parameters.

Parameters
bind	a `_engine.Engine` or other `.Connectable` with which newly created `.Session` objects will be associated.
class_	class to use in order to create new `.Session` objects. Defaults to `.Session`.
autoflush	The autoflush setting to use with newly created `.Session` objects.
autocommit	The autocommit setting to use with newly created `.Session` objects.
expire_on_commit	Undocumented
info	optional dictionary of information that will be available via `.Session.info`. Note this dictionary is updated, not replaced, when the `info` parameter is specified to the specific `.Session` construction operation.
**kw	all other keyword arguments are passed to the constructor of newly created `.Session` objects.
expire_on_commit=True	the :paramref:`_orm.Session.expire_on_commit` setting to use with newly created `.Session` objects.

def __repr__(self):

Undocumented

def begin(self):

Produce a context manager that both provides a new _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

New in version 1.4.

def configure(self, **new_kw):

(Re)configure the arguments for this sessionmaker.

e.g.:

Session = sessionmaker()

Session.configure(bind=create_engine('sqlite://'))

class_ =

Undocumented

kw =

Undocumented