{ "info": { "author": "Laurence Rowe", "author_email": "laurence@lrowe.co.uk", "bugtrack_url": null, "classifiers": [ "Framework :: Pyramid", "Framework :: Zope :: 3", "License :: OSI Approved :: Zope Public License", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Topic :: Software Development :: Libraries :: Python Modules" ], "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: http://docs.repoze.org/tm2/\n\n.. _pyramid_tm: https://docs.pylonsproject.org/projects/pyramid_tm/dev/\n\n.. _Pyramid: http://pylonsproject.org/\n\n.. _Turbogears 2: http://turbogears.org/\n\n.. _SQLAlchemy: http://sqlalchemy.org/docs/\n\n.. _Zope transaction manager: http://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\nExample\n=======\n\nThis example is lifted directly from the SQLAlchemy declarative documentation.\nFirst the necessary imports.\n\n >>> from sqlalchemy import *\n >>> from sqlalchemy.ext.declarative import declarative_base\n >>> from sqlalchemy.orm import scoped_session, sessionmaker, relation\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 = relation(\"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, convert_unicode=True)\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 >>> 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('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 [
]\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(users.c.name=='bob'), name='ben')\n