***************
zope.sqlalchemy
***************
.. contents::
:local:
Introduction
============
The aim of this package is to unify the plethora of existing packages
integrating SQLAlchemy with Zope's transaction management. As such it seeks
only to provide a data manager and makes no attempt to define a `zopeish` way
to configure engines.
For WSGI applications, Zope style automatic transaction management is
available with `repoze.tm2`_ (used by `Turbogears 2`_ and other systems).
This package is also used by `pyramid_tm`_ (an add-on of the `Pyramid`_) web
framework.
You need to understand `SQLAlchemy`_ and the `Zope transaction manager`_ for
this package and this README to make any sense.
.. _repoze.tm2: https://repozetm2.readthedocs.io/en/latest/
.. _pyramid_tm: https://docs.pylonsproject.org/projects/pyramid_tm/en/latest/
.. _Pyramid: https://pylonsproject.org/
.. _Turbogears 2: https://turbogears.org/
.. _SQLAlchemy: https://sqlalchemy.org/docs/
.. _Zope transaction manager: https://www.zodb.org/en/latest/#transactions
Running the tests
=================
This package is distributed as a buildout. Using your desired python run:
$ python bootstrap.py
$ ./bin/buildout
This will download the dependent packages and setup the test script, which may
be run with:
$ ./bin/test
or with the standard setuptools test command:
$ ./bin/py setup.py test
To enable testing with your own database set the TEST_DSN environment variable
to your sqlalchemy database dsn. Two-phase commit behaviour may be tested by
setting the TEST_TWOPHASE variable to a non empty string. e.g:
$ TEST_DSN=postgres://test:test@localhost/test TEST_TWOPHASE=True bin/test
Usage in short
==============
The integration between Zope transactions and the SQLAlchemy event system is
done using the ``register()`` function on the session factory class.
.. code-block:: python
from zope.sqlalchemy import register
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, scoped_session
engine = sqlalchemy.create_engine("postgresql://scott:tiger@localhost/test")
DBSession = scoped_session(sessionmaker(bind=engine))
register(DBSession)
Instantiated sessions commits and rollbacks will now be integrated with Zope
transactions.
.. code-block:: python
import transaction
from sqlalchemy.sql import text
session = DBSession()
result = session.execute(text("DELETE FROM objects WHERE id=:id"), {"id": 2})
row = result.fetchone()
transaction.commit()
Full Example
============
This example is lifted directly from the SQLAlchemy declarative documentation.
First the necessary imports.
>>> from sqlalchemy import *
>>> from sqlalchemy.orm import declarative_base, scoped_session, sessionmaker, relationship
>>> from sqlalchemy.sql import text
>>> from zope.sqlalchemy import register
>>> import transaction
Now to define the mapper classes.
>>> Base = declarative_base()
>>> class User(Base):
... __tablename__ = 'test_users'
... id = Column('id', Integer, primary_key=True)
... name = Column('name', String(50))
... addresses = relationship("Address", backref="user")
>>> class Address(Base):
... __tablename__ = 'test_addresses'
... id = Column('id', Integer, primary_key=True)
... email = Column('email', String(50))
... user_id = Column('user_id', Integer, ForeignKey('test_users.id'))
Create an engine and setup the tables. Note that for this example to work a
recent version of sqlite/pysqlite is required. 3.4.0 seems to be sufficient.
>>> engine = create_engine(TEST_DSN)
>>> Base.metadata.create_all(engine)
Now to create the session itself. As zope is a threaded web server we must use
scoped sessions. Zope and SQLAlchemy sessions are tied together by using the
register
>>> Session = scoped_session(sessionmaker(bind=engine,
... twophase=TEST_TWOPHASE))
Call the scoped session factory to retrieve a session. You may call this as
many times as you like within a transaction and you will always retrieve the
same session. At present there are no users in the database.
>>> session = Session()
>>> register(session)
<zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>
>>> session.query(User).all()
[]
We can now create a new user and commit the changes using Zope's transaction
machinery, just as Zope's publisher would.
>>> session.add(User(id=1, name='bob'))
>>> transaction.commit()
Engine level connections are outside the scope of the transaction integration.
>>> engine.connect().execute(text('SELECT * FROM test_users')).fetchall()
[(1, ...'bob')]
A new transaction requires a new session. Let's add an address.
>>> session = Session()
>>> bob = session.query(User).all()[0]
>>> str(bob.name)
'bob'
>>> bob.addresses
[]
>>> bob.addresses.append(Address(id=1, email='bob@bob.bob'))
>>> transaction.commit()
>>> session = Session()
>>> bob = session.query(User).all()[0]
>>> bob.addresses
[<Address object at ...>]
>>> str(bob.addresses[0].email)
'bob@bob.bob'
>>> bob.addresses[0].email = 'wrong@wrong'
To rollback a transaction, use transaction.abort().
>>> transaction.abort()
>>> session = Session()
>>> bob = session.query(User).all()[0]
>>> str(bob.addresses[0].email)
'bob@bob.bob'
>>> transaction.abort()
By default, zope.sqlalchemy puts sessions in an 'active' state when they are
first used. ORM write operations automatically move the session into a
'changed' state. This avoids unnecessary database commits. Sometimes it
is necessary to interact with the database directly through SQL. It is not
possible to guess whether such an operation is a read or a write. Therefore we
must manually mark the session as changed when manual SQL statements write
to the DB.
>>> session = Session()
>>> conn = session.connection()
>>> users = Base.metadata.tables['test_users']
>>> conn.execute(users.update().where(users.c.name=='bob'), {'name': 'ben'})
<sqlalchemy.engine... object at ...>
>>> from zope.sqlalchemy import mark_changed
>>> mark_changed(session)
>>> transaction.commit()
>>> session = Session()
>>> str(session.query(User).all()[0].name)
'ben'
>>> transaction.abort()
If this is a problem you may register the events and tell them to place the
session in the 'changed' state initially.
>>> Session.remove()
>>> register(Session, 'changed')
<zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>
>>> session = Session()
>>> conn = session.connection()
>>> conn.execute(users.update().where(users.c.name=='ben'), {'name': 'bob'})
<sqlalchemy.engine... object at ...>
>>> transaction.commit()
>>> session = Session()
>>> str(session.query(User).all()[0].name)
'bob'
>>> transaction.abort()
The `mark_changed` function accepts a kwarg for `keep_session` which defaults
to `False` and is unaware of the registered extensions `keep_session`
configuration.
If you intend for `keep_session` to be True, you can specify it explicitly:
>>> from zope.sqlalchemy import mark_changed
>>> mark_changed(session, keep_session=True)
>>> transaction.commit()
You can also use a configured extension to preserve this argument:
>>> sessionExtension = register(session, keep_session=True)
>>> sessionExtension.mark_changed(session)
>>> transaction.commit()
Long-lasting session scopes
---------------------------
The default behaviour of the transaction integration is to close the session
after a commit. You can tell by trying to access an object after committing:
>>> bob = session.query(User).all()[0]
>>> transaction.commit()
>>> bob.name
Traceback (most recent call last):
sqlalchemy.orm.exc.DetachedInstanceError: Instance <User at ...> is not bound to a Session; attribute refresh operation cannot proceed...
To support cases where a session needs to last longer than a transaction (useful
in test suites) you can specify to keep a session when registering the events:
>>> Session = scoped_session(sessionmaker(bind=engine,
... twophase=TEST_TWOPHASE))
>>> register(Session, keep_session=True)
<zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>
>>> session = Session()
>>> bob = session.query(User).all()[0]
>>> bob.name = 'bobby'
>>> transaction.commit()
>>> bob.name
'bobby'
The session must then be closed manually:
>>> session.close()
Development version
===================
`GIT version <https://github.com/zopefoundation/zope.sqlalchemy>`_
Changes
=======
3.1 (2023-09-12)
----------------
- Fix ``psycopg.errors.OperationalError.sqlstate`` can be ``None``.
(`#81 <https://github.com/zopefoundation/zope.sqlalchemy/issues/81>`_)
3.0 (2023-06-01)
----------------
- Add support for SQLAlchemy 2.0 and for new psycopg v3 backend.
(`#79 <https://github.com/zopefoundation/zope.sqlalchemy/pull/79>`_)
**Breaking Changes**
- No longer allow calling ``session.commit()`` within a manual nested database
transaction (a savepoint). If you want to use savepoints directly in code that is
not aware of ``transaction.savepoint()`` with ``session.begin_nested()`` then
use the savepoint returned by the function to commit just the nested transaction
i.e. ``savepoint = session.begin_nested(); savepoint.commit()`` or use it as a
context manager i.e. ``with session.begin_nested():``.
(`for details see #79 <https://github.com/zopefoundation/zope.sqlalchemy/pull/79#issuecomment-1516069841>`_)
2.0 (2023-02-06)
----------------
- Drop support for Python 2.7, 3.5, 3.6.
- Drop support for ``SQLAlchemy < 1.1``
(`#65 <https://github.com/zopefoundation/zope.sqlalchemy/issues/65>`_)
- Add support for Python 3.10, 3.11.
1.6 (2021-09-06)
----------------
- Add support for Python 2.7 on SQLAlchemy 1.4.
(`#71 <https://github.com/zopefoundation/zope.sqlalchemy/issues/71>`_)
1.5 (2021-07-14)
----------------
- Call ``mark_changed`` also on the ``do_orm_execute`` event if the operation
is an insert, update or delete. This is SQLAlchemy >= 1.4 only, as it
introduced that event.
(`#67 <https://github.com/zopefoundation/zope.sqlalchemy/issues/67>`_)
- Fixup get transaction. There was regression introduced in 1.4.
(`#66 <https://github.com/zopefoundation/zope.sqlalchemy/issues/66>`_)
1.4 (2021-04-26)
----------------
- Add ``mark_changed`` and ``join_transaction`` methods to
``ZopeTransactionEvents``.
(`#46 <https://github.com/zopefoundation/zope.sqlalchemy/issues/46>`_)
- Reduce DeprecationWarnings with SQLAlchemy 1.4 and require at least
SQLAlchemy >= 0.9.
(`#54 <https://github.com/zopefoundation/zope.sqlalchemy/issues/54>`_)
- Add support for SQLAlchemy 1.4.
(`#58 <https://github.com/zopefoundation/zope.sqlalchemy/issues/58>`_)
- Prevent using an SQLAlchemy 1.4 version with broken flush support.
(`#57 <https://github.com/zopefoundation/zope.sqlalchemy/issues/57>`_)
1.3 (2020-02-17)
----------------
* ``.datamanager.register()`` now returns the ``ZopeTransactionEvents``
instance which was used to register the events. This allows to change its
parameters afterwards.
(`#40 <https://github.com/zopefoundation/zope.sqlalchemy/pull/40>`_)
* Add preliminary support for Python 3.9a3.
1.2 (2019-10-17)
----------------
**Breaking Changes**
* Drop support for Python 3.4.
* Add support for Python 3.7 and 3.8.
* Fix deprecation warnings for the event system. We already used it in general
but still leveraged the old extension mechanism in some places.
(`#31 <https://github.com/zopefoundation/zope.sqlalchemy/issues/31>`_)
To make things clearer we renamed the ``ZopeTransactionExtension`` class
to ``ZopeTransactionEvents``. Existing code using the 'register' version
stays compatible.
**Upgrade from 1.1**
Your old code like this:
.. code-block:: python
from zope.sqlalchemy import ZopeTransactionExtension
DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension(), **options))
becomes:
.. code-block:: python
from zope.sqlalchemy import register
DBSession = scoped_session(sessionmaker(**options))
register(DBSession)
1.1 (2019-01-03)
----------------
* Add support to MySQL using pymysql.
1.0 (2018-01-31)
----------------
* Add support for Python 3.4 up to 3.6.
* Support SQLAlchemy 1.2.
* Drop support for Python 2.6, 3.2 and 3.3.
* Drop support for transaction < 1.6.0.
* Fix hazard that could cause SQLAlchemy session not to be committed when
transaction is committed in rare situations.
(`#23 <https://github.com/zopefoundation/zope.sqlalchemy/pull/23>`_)
0.7.7 (2016-06-23)
------------------
* Support SQLAlchemy 1.1.
(`#15 <https://github.com/zopefoundation/zope.sqlalchemy/issues/15>`_)
0.7.6 (2015-03-20)
------------------
* Make version check in register compatible with prereleases.
0.7.5 (2014-06-17)
------------------
* Ensure mapped objects are expired following a ``transaction.commit()`` when
no database commit was required.
(`#8 <https://github.com/zopefoundation/zope.sqlalchemy/issues/8>`_)
0.7.4 (2014-01-06)
------------------
* Allow ``session.commit()`` on nested transactions to facilitate integration
of existing code that might not use ``transaction.savepoint()``.
(`#1 <https://github.com/zopefoundation/zope.sqlalchemy/issues/1>`_)
* Add a new function zope.sqlalchemy.register(), which replaces the
direct use of ZopeTransactionExtension to make use
of the newer SQLAlchemy event system to establish instrumentation on
the given Session instance/class/factory. Requires at least
SQLAlchemy 0.7.
(`#4 <https://github.com/zopefoundation/zope.sqlalchemy/issues/4>`_)
* Fix `keep_session=True` doesn't work when a transaction is joined by flush
and other manngers bug.
(`#5 <https://github.com/zopefoundation/zope.sqlalchemy/issues/5>`_)
0.7.3 (2013-09-25)
------------------
* Prevent the ``Session`` object from getting into a "wedged" state if joining
a transaction fails. With thread scoped sessions that are reused this can cause
persistent errors requiring a server restart.
(`#2 <https://github.com/zopefoundation/zope.sqlalchemy/issues/2>`_)
0.7.2 (2013-02-19)
------------------
* Make life-time of sessions configurable. Specify `keep_session=True` when
setting up the SA extension.
* Python 3.3 compatibility.
0.7.1 (2012-05-19)
------------------
* Use ``@implementer`` as a class decorator instead of ``implements()`` at
class scope for compatibility with ``zope.interface`` 4.0. This requires
``zope.interface`` >= 3.6.0.
0.7 (2011-12-06)
----------------
* Python 3.2 compatibility.
0.6.1 (2011-01-08)
------------------
* Update datamanager.mark_changed to handle sessions which have not yet logged
a (ORM) query.
0.6 (2010-07-24)
----------------
* Implement should_retry for sqlalchemy.orm.exc.ConcurrentModificationError
and serialization errors from PostgreSQL and Oracle.
(Specify transaction>=1.1 to use this functionality.)
* Include license files.
* Add ``transaction_manager`` attribute to data managers for compliance with
IDataManager interface.
0.5 (2010-06-07)
----------------
* Remove redundant session.flush() / session.clear() on savepoint operations.
These were only needed with SQLAlchemy 0.4.x.
* SQLAlchemy 0.6.x support. Require SQLAlchemy >= 0.5.1.
* Add support for running ``python setup.py test``.
* Pull in pysqlite explicitly as a test dependency.
* Setup sqlalchemy mappers in test setup and clear them in tear down. This
makes the tests more robust and clears up the global state after. It
caused the tests to fail when other tests in the same run called
clear_mappers.
0.4 (2009-01-20)
----------------
Bugs fixed:
* Only raise errors in tpc_abort if we have committed.
* Remove the session id from the SESSION_STATE just before we de-reference the
session (i.e. all work is already successfuly completed). This fixes cases
where the transaction commit failed but SESSION_STATE was already cleared. In
those cases, the transaction was wedeged as abort would always error. This
happened on PostgreSQL where invalid SQL was used and the error caught.
* Call session.flush() unconditionally in tpc_begin.
* Change error message on session.commit() to be friendlier to non zope users.
Feature changes:
* Support for bulk update and delete with SQLAlchemy 0.5.1
0.3 (2008-07-29)
----------------
Bugs fixed:
* New objects added to a session did not cause a transaction join, so were not
committed at the end of the transaction unless the database was accessed.
SQLAlchemy 0.4.7 or 0.5beta3 now required.
Feature changes:
* For correctness and consistency with ZODB, renamed the function 'invalidate'
to 'mark_changed' and the status 'invalidated' to 'changed'.
0.2 (2008-06-28)
----------------
Feature changes:
* Updated to support SQLAlchemy 0.5. (0.4.6 is still supported).
0.1 (2008-05-15)
----------------
* Initial public release.
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/zope.sqlalchemy",
"name": "zope.sqlalchemy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "zope zope3 sqlalchemy",
"author": "Laurence Rowe",
"author_email": "laurence@lrowe.co.uk",
"download_url": "https://files.pythonhosted.org/packages/98/6f/f76bfaba0cab7362dad44c9af94913a8bee938a49d7e664a7195c822b916/zope.sqlalchemy-3.1.tar.gz",
"platform": null,
"description": "***************\nzope.sqlalchemy\n***************\n\n.. contents::\n :local:\n\nIntroduction\n============\n\nThe aim of this package is to unify the plethora of existing packages\nintegrating SQLAlchemy with Zope's transaction management. As such it seeks\nonly to provide a data manager and makes no attempt to define a `zopeish` way\nto configure engines.\n\nFor WSGI applications, Zope style automatic transaction management is\navailable with `repoze.tm2`_ (used by `Turbogears 2`_ and other systems).\n\nThis package is also used by `pyramid_tm`_ (an add-on of the `Pyramid`_) web\nframework.\n\nYou need to understand `SQLAlchemy`_ and the `Zope transaction manager`_ for\nthis package and this README to make any sense.\n\n.. _repoze.tm2: https://repozetm2.readthedocs.io/en/latest/\n\n.. _pyramid_tm: https://docs.pylonsproject.org/projects/pyramid_tm/en/latest/\n\n.. _Pyramid: https://pylonsproject.org/\n\n.. _Turbogears 2: https://turbogears.org/\n\n.. _SQLAlchemy: https://sqlalchemy.org/docs/\n\n.. _Zope transaction manager: https://www.zodb.org/en/latest/#transactions\n\nRunning the tests\n=================\n\nThis package is distributed as a buildout. Using your desired python run:\n\n$ python bootstrap.py\n$ ./bin/buildout\n\nThis will download the dependent packages and setup the test script, which may\nbe run with:\n\n$ ./bin/test\n\nor with the standard setuptools test command:\n\n$ ./bin/py setup.py test\n\nTo enable testing with your own database set the TEST_DSN environment variable\nto your sqlalchemy database dsn. Two-phase commit behaviour may be tested by\nsetting the TEST_TWOPHASE variable to a non empty string. e.g:\n\n$ TEST_DSN=postgres://test:test@localhost/test TEST_TWOPHASE=True bin/test\n\nUsage in short\n==============\n\nThe integration between Zope transactions and the SQLAlchemy event system is\ndone using the ``register()`` function on the session factory class.\n\n.. code-block:: python\n\n from zope.sqlalchemy import register\n from sqlalchemy import create_engine\n from sqlalchemy.orm import sessionmaker, scoped_session\n\n engine = sqlalchemy.create_engine(\"postgresql://scott:tiger@localhost/test\")\n\n DBSession = scoped_session(sessionmaker(bind=engine))\n register(DBSession)\n\nInstantiated sessions commits and rollbacks will now be integrated with Zope\ntransactions.\n\n.. code-block:: python\n\n import transaction\n from sqlalchemy.sql import text\n\n session = DBSession()\n\n result = session.execute(text(\"DELETE FROM objects WHERE id=:id\"), {\"id\": 2})\n row = result.fetchone()\n\n transaction.commit()\n\n\nFull Example\n============\n\nThis example is lifted directly from the SQLAlchemy declarative documentation.\nFirst the necessary imports.\n\n >>> from sqlalchemy import *\n >>> from sqlalchemy.orm import declarative_base, scoped_session, sessionmaker, relationship\n >>> from sqlalchemy.sql import text\n >>> from zope.sqlalchemy import register\n >>> import transaction\n\nNow to define the mapper classes.\n\n >>> Base = declarative_base()\n >>> class User(Base):\n ... __tablename__ = 'test_users'\n ... id = Column('id', Integer, primary_key=True)\n ... name = Column('name', String(50))\n ... addresses = relationship(\"Address\", backref=\"user\")\n >>> class Address(Base):\n ... __tablename__ = 'test_addresses'\n ... id = Column('id', Integer, primary_key=True)\n ... email = Column('email', String(50))\n ... user_id = Column('user_id', Integer, ForeignKey('test_users.id'))\n\nCreate an engine and setup the tables. Note that for this example to work a\nrecent version of sqlite/pysqlite is required. 3.4.0 seems to be sufficient.\n\n >>> engine = create_engine(TEST_DSN)\n >>> Base.metadata.create_all(engine)\n\nNow to create the session itself. As zope is a threaded web server we must use\nscoped sessions. Zope and SQLAlchemy sessions are tied together by using the\nregister\n\n >>> Session = scoped_session(sessionmaker(bind=engine,\n ... twophase=TEST_TWOPHASE))\n\nCall the scoped session factory to retrieve a session. You may call this as\nmany times as you like within a transaction and you will always retrieve the\nsame session. At present there are no users in the database.\n\n >>> session = Session()\n >>> register(session)\n <zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>\n >>> session.query(User).all()\n []\n\nWe can now create a new user and commit the changes using Zope's transaction\nmachinery, just as Zope's publisher would.\n\n >>> session.add(User(id=1, name='bob'))\n >>> transaction.commit()\n\nEngine level connections are outside the scope of the transaction integration.\n\n >>> engine.connect().execute(text('SELECT * FROM test_users')).fetchall()\n [(1, ...'bob')]\n\nA new transaction requires a new session. Let's add an address.\n\n >>> session = Session()\n >>> bob = session.query(User).all()[0]\n >>> str(bob.name)\n 'bob'\n >>> bob.addresses\n []\n >>> bob.addresses.append(Address(id=1, email='bob@bob.bob'))\n >>> transaction.commit()\n >>> session = Session()\n >>> bob = session.query(User).all()[0]\n >>> bob.addresses\n [<Address object at ...>]\n >>> str(bob.addresses[0].email)\n 'bob@bob.bob'\n >>> bob.addresses[0].email = 'wrong@wrong'\n\nTo rollback a transaction, use transaction.abort().\n\n >>> transaction.abort()\n >>> session = Session()\n >>> bob = session.query(User).all()[0]\n >>> str(bob.addresses[0].email)\n 'bob@bob.bob'\n >>> transaction.abort()\n\nBy default, zope.sqlalchemy puts sessions in an 'active' state when they are\nfirst used. ORM write operations automatically move the session into a\n'changed' state. This avoids unnecessary database commits. Sometimes it\nis necessary to interact with the database directly through SQL. It is not\npossible to guess whether such an operation is a read or a write. Therefore we\nmust manually mark the session as changed when manual SQL statements write\nto the DB.\n\n >>> session = Session()\n >>> conn = session.connection()\n >>> users = Base.metadata.tables['test_users']\n >>> conn.execute(users.update().where(users.c.name=='bob'), {'name': 'ben'})\n <sqlalchemy.engine... object at ...>\n >>> from zope.sqlalchemy import mark_changed\n >>> mark_changed(session)\n >>> transaction.commit()\n >>> session = Session()\n >>> str(session.query(User).all()[0].name)\n 'ben'\n >>> transaction.abort()\n\nIf this is a problem you may register the events and tell them to place the\nsession in the 'changed' state initially.\n\n >>> Session.remove()\n >>> register(Session, 'changed')\n <zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>\n >>> session = Session()\n >>> conn = session.connection()\n >>> conn.execute(users.update().where(users.c.name=='ben'), {'name': 'bob'})\n <sqlalchemy.engine... object at ...>\n >>> transaction.commit()\n >>> session = Session()\n >>> str(session.query(User).all()[0].name)\n 'bob'\n >>> transaction.abort()\n\nThe `mark_changed` function accepts a kwarg for `keep_session` which defaults\nto `False` and is unaware of the registered extensions `keep_session`\nconfiguration.\n\nIf you intend for `keep_session` to be True, you can specify it explicitly:\n\n >>> from zope.sqlalchemy import mark_changed\n >>> mark_changed(session, keep_session=True)\n >>> transaction.commit()\n\nYou can also use a configured extension to preserve this argument:\n\n >>> sessionExtension = register(session, keep_session=True)\n >>> sessionExtension.mark_changed(session)\n >>> transaction.commit()\n\n\nLong-lasting session scopes\n---------------------------\n\nThe default behaviour of the transaction integration is to close the session\nafter a commit. You can tell by trying to access an object after committing:\n\n >>> bob = session.query(User).all()[0]\n >>> transaction.commit()\n >>> bob.name\n Traceback (most recent call last):\n sqlalchemy.orm.exc.DetachedInstanceError: Instance <User at ...> is not bound to a Session; attribute refresh operation cannot proceed...\n\nTo support cases where a session needs to last longer than a transaction (useful\nin test suites) you can specify to keep a session when registering the events:\n\n >>> Session = scoped_session(sessionmaker(bind=engine,\n ... twophase=TEST_TWOPHASE))\n >>> register(Session, keep_session=True)\n <zope.sqlalchemy.datamanager.ZopeTransactionEvents object at ...>\n >>> session = Session()\n >>> bob = session.query(User).all()[0]\n >>> bob.name = 'bobby'\n >>> transaction.commit()\n >>> bob.name\n 'bobby'\n\nThe session must then be closed manually:\n\n >>> session.close()\n\n\nDevelopment version\n===================\n\n`GIT version <https://github.com/zopefoundation/zope.sqlalchemy>`_\n\n\nChanges\n=======\n\n3.1 (2023-09-12)\n----------------\n\n- Fix ``psycopg.errors.OperationalError.sqlstate`` can be ``None``.\n (`#81 <https://github.com/zopefoundation/zope.sqlalchemy/issues/81>`_)\n\n\n3.0 (2023-06-01)\n----------------\n\n- Add support for SQLAlchemy 2.0 and for new psycopg v3 backend.\n (`#79 <https://github.com/zopefoundation/zope.sqlalchemy/pull/79>`_)\n\n**Breaking Changes**\n\n- No longer allow calling ``session.commit()`` within a manual nested database\n transaction (a savepoint). If you want to use savepoints directly in code that is\n not aware of ``transaction.savepoint()`` with ``session.begin_nested()`` then\n use the savepoint returned by the function to commit just the nested transaction\n i.e. ``savepoint = session.begin_nested(); savepoint.commit()`` or use it as a\n context manager i.e. ``with session.begin_nested():``.\n (`for details see #79 <https://github.com/zopefoundation/zope.sqlalchemy/pull/79#issuecomment-1516069841>`_)\n\n\n2.0 (2023-02-06)\n----------------\n\n- Drop support for Python 2.7, 3.5, 3.6.\n\n- Drop support for ``SQLAlchemy < 1.1``\n (`#65 <https://github.com/zopefoundation/zope.sqlalchemy/issues/65>`_)\n\n- Add support for Python 3.10, 3.11.\n\n\n1.6 (2021-09-06)\n----------------\n\n- Add support for Python 2.7 on SQLAlchemy 1.4.\n (`#71 <https://github.com/zopefoundation/zope.sqlalchemy/issues/71>`_)\n\n\n1.5 (2021-07-14)\n----------------\n\n- Call ``mark_changed`` also on the ``do_orm_execute`` event if the operation\n is an insert, update or delete. This is SQLAlchemy >= 1.4 only, as it\n introduced that event.\n (`#67 <https://github.com/zopefoundation/zope.sqlalchemy/issues/67>`_)\n\n- Fixup get transaction. There was regression introduced in 1.4.\n (`#66 <https://github.com/zopefoundation/zope.sqlalchemy/issues/66>`_)\n\n\n1.4 (2021-04-26)\n----------------\n\n- Add ``mark_changed`` and ``join_transaction`` methods to\n ``ZopeTransactionEvents``.\n (`#46 <https://github.com/zopefoundation/zope.sqlalchemy/issues/46>`_)\n\n- Reduce DeprecationWarnings with SQLAlchemy 1.4 and require at least\n SQLAlchemy >= 0.9.\n (`#54 <https://github.com/zopefoundation/zope.sqlalchemy/issues/54>`_)\n\n- Add support for SQLAlchemy 1.4.\n (`#58 <https://github.com/zopefoundation/zope.sqlalchemy/issues/58>`_)\n\n- Prevent using an SQLAlchemy 1.4 version with broken flush support.\n (`#57 <https://github.com/zopefoundation/zope.sqlalchemy/issues/57>`_)\n\n\n1.3 (2020-02-17)\n----------------\n\n* ``.datamanager.register()`` now returns the ``ZopeTransactionEvents``\n instance which was used to register the events. This allows to change its\n parameters afterwards.\n (`#40 <https://github.com/zopefoundation/zope.sqlalchemy/pull/40>`_)\n\n* Add preliminary support for Python 3.9a3.\n\n\n1.2 (2019-10-17)\n----------------\n\n**Breaking Changes**\n\n* Drop support for Python 3.4.\n\n* Add support for Python 3.7 and 3.8.\n\n* Fix deprecation warnings for the event system. We already used it in general\n but still leveraged the old extension mechanism in some places.\n (`#31 <https://github.com/zopefoundation/zope.sqlalchemy/issues/31>`_)\n\n To make things clearer we renamed the ``ZopeTransactionExtension`` class\n to ``ZopeTransactionEvents``. Existing code using the 'register' version\n stays compatible.\n\n**Upgrade from 1.1**\n\nYour old code like this:\n\n.. code-block:: python\n\n from zope.sqlalchemy import ZopeTransactionExtension\n\n DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension(), **options))\n\nbecomes:\n\n.. code-block:: python\n\n from zope.sqlalchemy import register\n\n DBSession = scoped_session(sessionmaker(**options))\n register(DBSession)\n\n\n\n1.1 (2019-01-03)\n----------------\n\n* Add support to MySQL using pymysql.\n\n\n1.0 (2018-01-31)\n----------------\n\n* Add support for Python 3.4 up to 3.6.\n\n* Support SQLAlchemy 1.2.\n\n* Drop support for Python 2.6, 3.2 and 3.3.\n\n* Drop support for transaction < 1.6.0.\n\n* Fix hazard that could cause SQLAlchemy session not to be committed when\n transaction is committed in rare situations.\n (`#23 <https://github.com/zopefoundation/zope.sqlalchemy/pull/23>`_)\n\n\n0.7.7 (2016-06-23)\n------------------\n\n* Support SQLAlchemy 1.1.\n (`#15 <https://github.com/zopefoundation/zope.sqlalchemy/issues/15>`_)\n\n\n0.7.6 (2015-03-20)\n------------------\n\n* Make version check in register compatible with prereleases.\n\n0.7.5 (2014-06-17)\n------------------\n\n* Ensure mapped objects are expired following a ``transaction.commit()`` when\n no database commit was required.\n (`#8 <https://github.com/zopefoundation/zope.sqlalchemy/issues/8>`_)\n\n\n0.7.4 (2014-01-06)\n------------------\n\n* Allow ``session.commit()`` on nested transactions to facilitate integration\n of existing code that might not use ``transaction.savepoint()``.\n (`#1 <https://github.com/zopefoundation/zope.sqlalchemy/issues/1>`_)\n\n* Add a new function zope.sqlalchemy.register(), which replaces the\n direct use of ZopeTransactionExtension to make use\n of the newer SQLAlchemy event system to establish instrumentation on\n the given Session instance/class/factory. Requires at least\n SQLAlchemy 0.7.\n (`#4 <https://github.com/zopefoundation/zope.sqlalchemy/issues/4>`_)\n\n* Fix `keep_session=True` doesn't work when a transaction is joined by flush\n and other manngers bug.\n (`#5 <https://github.com/zopefoundation/zope.sqlalchemy/issues/5>`_)\n\n\n0.7.3 (2013-09-25)\n------------------\n\n* Prevent the ``Session`` object from getting into a \"wedged\" state if joining\n a transaction fails. With thread scoped sessions that are reused this can cause\n persistent errors requiring a server restart.\n (`#2 <https://github.com/zopefoundation/zope.sqlalchemy/issues/2>`_)\n\n0.7.2 (2013-02-19)\n------------------\n\n* Make life-time of sessions configurable. Specify `keep_session=True` when\n setting up the SA extension.\n\n* Python 3.3 compatibility.\n\n0.7.1 (2012-05-19)\n------------------\n\n* Use ``@implementer`` as a class decorator instead of ``implements()`` at\n class scope for compatibility with ``zope.interface`` 4.0. This requires\n ``zope.interface`` >= 3.6.0.\n\n0.7 (2011-12-06)\n----------------\n\n* Python 3.2 compatibility.\n\n0.6.1 (2011-01-08)\n------------------\n\n* Update datamanager.mark_changed to handle sessions which have not yet logged\n a (ORM) query.\n\n\n0.6 (2010-07-24)\n----------------\n\n* Implement should_retry for sqlalchemy.orm.exc.ConcurrentModificationError\n and serialization errors from PostgreSQL and Oracle.\n (Specify transaction>=1.1 to use this functionality.)\n\n* Include license files.\n\n* Add ``transaction_manager`` attribute to data managers for compliance with\n IDataManager interface.\n\n0.5 (2010-06-07)\n----------------\n\n* Remove redundant session.flush() / session.clear() on savepoint operations.\n These were only needed with SQLAlchemy 0.4.x.\n\n* SQLAlchemy 0.6.x support. Require SQLAlchemy >= 0.5.1.\n\n* Add support for running ``python setup.py test``.\n\n* Pull in pysqlite explicitly as a test dependency.\n\n* Setup sqlalchemy mappers in test setup and clear them in tear down. This\n makes the tests more robust and clears up the global state after. It\n caused the tests to fail when other tests in the same run called\n clear_mappers.\n\n0.4 (2009-01-20)\n----------------\n\nBugs fixed:\n\n* Only raise errors in tpc_abort if we have committed.\n\n* Remove the session id from the SESSION_STATE just before we de-reference the\n session (i.e. all work is already successfuly completed). This fixes cases\n where the transaction commit failed but SESSION_STATE was already cleared. In\n those cases, the transaction was wedeged as abort would always error. This\n happened on PostgreSQL where invalid SQL was used and the error caught.\n\n* Call session.flush() unconditionally in tpc_begin.\n\n* Change error message on session.commit() to be friendlier to non zope users.\n\nFeature changes:\n\n* Support for bulk update and delete with SQLAlchemy 0.5.1\n\n0.3 (2008-07-29)\n----------------\n\nBugs fixed:\n\n* New objects added to a session did not cause a transaction join, so were not\n committed at the end of the transaction unless the database was accessed.\n SQLAlchemy 0.4.7 or 0.5beta3 now required.\n\nFeature changes:\n\n* For correctness and consistency with ZODB, renamed the function 'invalidate'\n to 'mark_changed' and the status 'invalidated' to 'changed'.\n\n0.2 (2008-06-28)\n----------------\n\nFeature changes:\n\n* Updated to support SQLAlchemy 0.5. (0.4.6 is still supported).\n\n0.1 (2008-05-15)\n----------------\n\n* Initial public release.\n",
"bugtrack_url": null,
"license": "ZPL 2.1",
"summary": "Minimal Zope/SQLAlchemy transaction integration",
"version": "3.1",
"project_urls": {
"Homepage": "https://github.com/zopefoundation/zope.sqlalchemy"
},
"split_keywords": [
"zope",
"zope3",
"sqlalchemy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8636875db361ce975a226456388f3bc0f060db95191b7b011025c8c97d3888c5",
"md5": "b1d69670dd86d71fcf4662043aa4fdfd",
"sha256": "fdc7d65d8da335a34b90fb993e8217ef12808bad3025d2e3a6720db4138e4985"
},
"downloads": -1,
"filename": "zope.sqlalchemy-3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b1d69670dd86d71fcf4662043aa4fdfd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23373,
"upload_time": "2023-09-12T06:24:41",
"upload_time_iso_8601": "2023-09-12T06:24:41.416472Z",
"url": "https://files.pythonhosted.org/packages/86/36/875db361ce975a226456388f3bc0f060db95191b7b011025c8c97d3888c5/zope.sqlalchemy-3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "986ff76bfaba0cab7362dad44c9af94913a8bee938a49d7e664a7195c822b916",
"md5": "4e67e8a24ecc9fe468e4df144d4ab4e6",
"sha256": "d9c2c3be695c213c5e22b7f7c6a4a214fa8eb5940b033465ba1c10a9d8b346db"
},
"downloads": -1,
"filename": "zope.sqlalchemy-3.1.tar.gz",
"has_sig": false,
"md5_digest": "4e67e8a24ecc9fe468e4df144d4ab4e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32407,
"upload_time": "2023-09-12T06:24:43",
"upload_time_iso_8601": "2023-09-12T06:24:43.749903Z",
"url": "https://files.pythonhosted.org/packages/98/6f/f76bfaba0cab7362dad44c9af94913a8bee938a49d7e664a7195c822b916/zope.sqlalchemy-3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-12 06:24:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "zope.sqlalchemy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "zope.sqlalchemy"
}
JSON
