From: Mike Bayer Date: Mon, 6 Sep 2010 15:48:22 +0000 (-0400) Subject: doc updates X-Git-Tag: rel_0_6_4~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=900fe9c9accecd68ed1c25b03013ee4972338712;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git doc updates --- diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 61fb2fb29e..7448392fe6 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -112,42 +112,14 @@ on each invocation:: session = Session(bind=engine) -...or directly with a :class:`.Connection`. This is useful in some situations, -such as within a test fixture that maintains an external transaction:: +...or directly with a :class:`.Connection`:: - from sqlalchemy.orm import sessionmaker - from sqlalchemy import create_engine - from unittest import TestCase - - # global application scope. create Session class, engine - Session = sessionmaker() - - engine = create_engine('postgresql://...') + conn = engine.connect() + session = Session(bind=conn) - class SomeTest(TestCase): - def setUp(self): - # connect to the database - self.connection = engine.connect() - - # begin a non-ORM transaction - self.trans = connection.begin() - - # bind an individual Session to the connection - self.session = Session(bind=self.connection) - - def test_something(self): - # use the session in tests. - - self.session.add(Foo()) - self.session.commit() - - def tearDown(self): - # rollback - everything that happened with the - # Session above (including calls to commit()) - # is rolled back. - self.trans.rollback() - self.session.close() - +While the rationale for the above example may not be apparent, the typical +usage is in a test fixture that maintains an external transaction - see +:ref:`session_external_transaction` below for a full example. Using the Session ================== @@ -984,59 +956,58 @@ proper context for the desired engine:: connection = session.connection(MyMappedClass) +.. _session_external_transaction: + Joining a Session into an External Transaction =============================================== -If a :class:`~sqlalchemy.engine.base.Connection` is being used which is -already in a transactional state (i.e. has a -:class:`~sqlalchemy.engine.base.Transaction`), a -:class:`~sqlalchemy.orm.session.Session` can be made to participate within -that transaction by just binding the :class:`~sqlalchemy.orm.session.Session` -to that :class:`~sqlalchemy.engine.base.Connection`:: +If a :class:`.Connection` is being used which is already in a transactional +state (i.e. has a :class:`.Transaction` established), a :class:`.Session` can +be made to participate within that transaction by just binding the +:class:`.Session` to that :class:`.Connection`. The usual rationale for this +is a test suite that allows ORM code to work freely with a :class:`.Session`, +including the ability to call :meth:`.Session.commit`, where afterwards the +entire database interaction is rolled back:: + from sqlalchemy.orm import sessionmaker + from sqlalchemy import create_engine + from unittest import TestCase + + # global application scope. create Session class, engine Session = sessionmaker() - # non-ORM connection + transaction - conn = engine.connect() - trans = conn.begin() - - # create a Session, bind to the connection - session = Session(bind=conn) - - # ... work with session - - session.commit() # commit the session - session.close() # close it out, prohibit further actions - - trans.commit() # commit the actual transaction - -Note that above, we issue a ``commit()`` both on the -:class:`~sqlalchemy.orm.session.Session` as well as the -:class:`~sqlalchemy.engine.base.Transaction`. This is an example of where we -take advantage of :class:`~sqlalchemy.engine.base.Connection`'s ability to -maintain *subtransactions*, or nested begin/commit pairs. The -:class:`~sqlalchemy.orm.session.Session` is used exactly as though it were -managing the transaction on its own; its -:func:`~sqlalchemy.orm.session.Session.commit` method issues its -:func:`~sqlalchemy.orm.session.Session.flush`, and commits the subtransaction. -The subsequent transaction the :class:`~sqlalchemy.orm.session.Session` starts -after commit will not begin until it's next used. Above we issue a -:func:`~sqlalchemy.orm.session.Session.close` to prevent this from occurring. -Finally, the actual transaction is committed using ``Transaction.commit()``. - -When using the ``threadlocal`` engine context, the process above is -simplified; the :class:`~sqlalchemy.orm.session.Session` uses the same -connection/transaction as everyone else in the current thread, whether or not -you explicitly bind it:: - - engine = create_engine('postgresql://mydb', strategy="threadlocal") - engine.begin() - - session = Session() # session takes place in the transaction like everyone else + engine = create_engine('postgresql://...') - # ... go nuts + class SomeTest(TestCase): + def setUp(self): + # connect to the database + self.connection = engine.connect() - engine.commit() # commit the transaction + # begin a non-ORM transaction + self.trans = connection.begin() + + # bind an individual Session to the connection + self.session = Session(bind=self.connection) + + def test_something(self): + # use the session in tests. + + self.session.add(Foo()) + self.session.commit() + + def tearDown(self): + # rollback - everything that happened with the + # Session above (including calls to commit()) + # is rolled back. + self.trans.rollback() + self.session.close() + +Above, we issue :meth:`.Session.commit` as well as +:meth:`.Transaction.rollback`. This is an example of where we take advantage +of the :class:`.Connection` object's ability to maintain *subtransactions*, or +nested begin/commit-or-rollback pairs where only the outermost begin/commit +pair actually commits the transaction, or if the outermost block rolls back, +everything is rolled back. The :class:`.Session` object and :func:`.sessionmaker` function ================================================================ @@ -1172,6 +1143,11 @@ Contextual Session API .. autoclass:: sqlalchemy.orm.scoping.ScopedSession :members: +.. autoclass:: sqlalchemy.util.ScopedRegistry + :members: + +.. autoclass:: sqlalchemy.util.ThreadLocalRegistry + .. _session_partitioning: Partitioning Strategies diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 7098e695df..63d76efa02 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -1480,6 +1480,12 @@ class Connection(Connectable): class Transaction(object): """Represent a Transaction in progress. + The object provides :meth:`.rollback` and :meth:`.commit` + methods in order to control transaction boundaries. It + also implements a context manager interface so that + the Python ``with`` statement can be used with the + :meth:`.Connection.begin` method. + The Transaction object is **not** threadsafe. .. index:: @@ -1487,12 +1493,17 @@ class Transaction(object): """ def __init__(self, connection, parent): + """The constructor for :class:`.Transaction` is private + and is called from within the :class:`.Connection.begin` + implementation. + + """ self.connection = connection self._parent = parent or self self.is_active = True def close(self): - """Close this transaction. + """Close this :class:`.Transaction`. If this transaction is the base transaction in a begin/commit nesting, the transaction will rollback(). Otherwise, the @@ -1500,6 +1511,7 @@ class Transaction(object): This is used to cancel a Transaction without affecting the scope of an enclosing transaction. + """ if not self._parent.is_active: return @@ -1507,6 +1519,9 @@ class Transaction(object): self.rollback() def rollback(self): + """Roll back this :class:`.Transaction`. + + """ if not self._parent.is_active: return self._do_rollback() @@ -1516,6 +1531,8 @@ class Transaction(object): self._parent.rollback() def commit(self): + """Commit this :class:`.Transaction`.""" + if not self._parent.is_active: raise exc.InvalidRequestError("This transaction is inactive") self._do_commit() diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index e59c5863b1..4eae375d8b 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -110,17 +110,19 @@ __all__ = ( def scoped_session(session_factory, scopefunc=None): - """Provides thread-local management of Sessions. + """Provides thread-local or scoped management of :class:`.Session` objects. This is a front-end function to - :class:`~sqlalchemy.orm.scoping.ScopedSession`. + :class:`.ScopedSession`. :param session_factory: a callable function that produces :class:`Session` instances, such as :func:`sessionmaker`. - :param scopefunc: optional, TODO + :param scopefunc: Optional "scope" function which would be + passed to the :class:`.ScopedRegistry`. If None, the + :class:`.ThreadLocalRegistry` is used by default. - :returns: an :class:`~sqlalchemy.orm.scoping.ScopedSession` instance + :returns: an :class:`.ScopedSession` instance Usage:: diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index af518e407a..c1a5fd5771 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -22,9 +22,13 @@ class ScopedSession(object): Usage:: - Session = scoped_session(sessionmaker(autoflush=True)) + Session = scoped_session(sessionmaker()) - ... use session normally. + ... use Session normally. + + The internal registry is accessible as well, + and by default is an instance of :class:`.ThreadLocalRegistry`. + """ @@ -89,6 +93,7 @@ class ScopedSession(object): class when called. e.g.:: + Session = scoped_session(sessionmaker()) class MyClass(object): diff --git a/lib/sqlalchemy/util.py b/lib/sqlalchemy/util.py index b41aed8bc5..10931be5e5 100644 --- a/lib/sqlalchemy/util.py +++ b/lib/sqlalchemy/util.py @@ -1268,16 +1268,30 @@ class UniqueAppender(object): class ScopedRegistry(object): """A Registry that can store one or multiple instances of a single - class on a per-thread scoped basis, or on a customized scope. + class on the basis of a "scope" function. + + The object implements ``__call__`` as the "getter", so by + calling ``myregistry()`` the contained object is returned + for the current scope. - createfunc + :param createfunc: a callable that returns a new object to be placed in the registry - scopefunc + :param scopefunc: a callable that will return a key to store/retrieve an object. """ def __init__(self, createfunc, scopefunc): + """Construct a new :class:`.ScopedRegistry`. + + :param createfunc: A creation function that will generate + a new value for the current scope, if none is present. + + :param scopefunc: A function that returns a hashable + token representing the current scope (such as, current + thread identifier). + + """ self.createfunc = createfunc self.scopefunc = scopefunc self.registry = {} @@ -1290,18 +1304,28 @@ class ScopedRegistry(object): return self.registry.setdefault(key, self.createfunc()) def has(self): + """Return True if an object is present in the current scope.""" + return self.scopefunc() in self.registry def set(self, obj): + """Set the value forthe current scope.""" + self.registry[self.scopefunc()] = obj def clear(self): + """Clear the current scope, if any.""" + try: del self.registry[self.scopefunc()] except KeyError: pass class ThreadLocalRegistry(ScopedRegistry): + """A :class:`.ScopedRegistry` that uses a ``threading.local()`` + variable for storage. + + """ def __init__(self, createfunc): self.createfunc = createfunc self.registry = threading.local()