Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

Download
ActivePython
INSTALL>
pypm install z3c.sqlalchemy

How to install z3c.sqlalchemy

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install z3c.sqlalchemy
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
1.4.0 Available View build log
Windows (64-bit)
1.4.0 Available View build log
Mac OS X (10.5+)
1.4.0 Available View build log
Linux (32-bit)
1.4.0 Available View build log
Linux (64-bit)
1.4.0 Available View build log
 
Author
License
ZPL (see LICENSE.txt)
Depended by
Lastest release
version 1.4.0 on Jan 5th, 2011

What is z3c.sqlalchemy?

z3c.sqlalchemy is yet another wrapper around SQLAlchemy. The functionality of the wrapper is basically focused on easy integration with Zope 2 and Zope 3. The wrapper cares about connection handling, optional transaction integration with Zope 2/3 and wrapper management (caching, introspection). z3c.sqlalchemy gives you flexible control over the mapper creation. Mapper classes can be

  • auto-generated (with or without autodetection of table relationships)
  • configured by the developer

What z3c.sqlalchemy does not do and won't do:

  • no support for Zope 3 schemas
  • no support for Archetypes schemas

z3c.sqlachemy just tries to provide you with the basic functionalities you need to write SQLAlchemy-based applications with Zope 2/3. Higher-level functionalities like integration with Archetypes/Zope 3 schemas are subject to higher-level frameworks. z3c.sqlalchemy does not address these frameworks.

Requirements:

  • Zope 2.8+, Zope 3.X
  • SQLAlchemy 0.4.6 or higher (no support for SQLAlchemy 0.3)
  • zope.sqlalchemy 0.1.0 or higher
  • Python 2.4+

Installation:

Either using easy_install:

System Message: WARNING/2 (<string>, line 45)

Literal block expected; none found.

easy_install z3c.sqlalchemy

or using Python directly:

System Message: WARNING/2 (<string>, line 49)

Literal block expected; none found.

python2.4 setup.py install

Note:

z3c.sqlalchemy depends on the modules zope.component, zope.schema and zope.interface. If you are using z3c.sqlalchemy in a Python-only environment, ensure the these components have to be installed either as eggs or by setting the PYTHONPATH to a corresponding Zope 2 or Zope 3 installation.

Usage

Basic usage:

from z3c.sqlalchemy import createSAWrapper wrapper = createSAWrapper('postgres://postgres:postgres@host/someDB') session = wrapper.session FormatMapper = wrapper.getMapper('format') # auto-generated mapper for table 'format' for row in session.query(FormatMapper).select(...): print row session.flush() # if necessary

The session will participate automatically in a Zope transaction. The wrapper will call automatically session.flush() upon a transaction commit. Please note that 'wrapper.session' will always return the same session instance within the same transaction and same thread.

For a real-world application you don't want to create a new wrapper for every new request. Instead you want to register a wrapper instance as named utility (ISQLAlchemyWrapper) and lookup up the wrapper (the utility!) by name from within your application. This approach is very similiar to looking up an databases adapter or a ZSQL method through acquisition.

By default "wrapper.getMapper(name)" will always auto-generate a new mapper class by using SQLAlchemy auto-load feature. The drawback of this approach is that the mapper class does not know about relationships to other tables. Assume we have a one-to-many relationship between table A and B and you want z3c.sqlalchemy to generate a mapper that is aware of this relationship. For this purpose you can create a wrapper with a "model" as optional parameter. A model is basically a configuration or a series of hints in order to tell z3c.sqlalchemy how mappers a generated.

Example:

System Message: WARNING/2 (<string>, line 94)

Literal block expected; none found.

from z3c.sqlalchemy import createSAWrapper, Model model = Model() model.add(name='A', relations=('B',)) wrapper = createSAWrapper('postgres://postgres:postgres@host/someDB', model=model) AMapper= wrapper.getMapper('A')

This will generate a mapper AMapper where all instances of AMapper have a property 'B' that relates to all corresponding rows in B (see the SQLAlchemy documentation on mappers, properties and relation()). In this example you define the relationship between A and B explictly through the 'relations' parameter (as a sequence of related table names).

z3c.sqlalchemy also supports the auto-detection of relationships between tables. Unfortunately SQLAlchemy does not support this feature out-of-the-box and in a portable way. Therefore this feature of z3c.sqlalchemy is highly experimental and currently only available for Postgres (tested with Postgres 8.X).:

System Message: WARNING/2 (<string>, line 111)

Literal block expected; none found.

from z3c.sqlalchemy import createSAWrapper, Model model = Model() model.add(name='A', autodetect_relations=True) wrapper = createSAWrapper('postgres://postgres:postgres@host/someDB', model=model) AMapper= wrapper.getMapper('A')

In this case z3c.sqlalchemy will scan all tables in order to detect relationships automatically and build the mapper class and its properties according to the found relationships. Warning: this feature is experimental and it might take some time to scan all tables before the first request. Currently only Postgres tables in the 'public' schema are supported).

In same cases you might be interested to use your own base classes for a generated mapper. Also this usecase is supported by passing the base class to the model using the 'mapper_class' parameter:

System Message: WARNING/2 (<string>, line 127)

Literal block expected; none found.

from z3c.sqlalchemy import createSAWrapper, Model from z3c.sqlalchemy.mapper import MappedClassBase class MyAMapper(MappedClassBase): pass model = Model() model.add(name='A', relations=('B',) mapper_class = MyAMapper) wrapper = createSAWrapper('postgres://postgres:postgres@host/someDB', model=model) AMapper= wrapper.getMapper('A') # AMapper will be an instance of MyAMapper

When you are working with wrapper in a Zope 2/3 environment you are usually interested to to register a wrapper instance as named utility implementing ISQLAlchemyWrapper. You can can perform the registration lazily by passing the name utility as 'name' parameter to the createSAWrapper(..., name='my.postgres.test.db') method.

A convenience method for obtaining a wrapper instance by name is available through getSAWrapper:

System Message: WARNING/2 (<string>, line 144)

Literal block expected; none found.

createSAWrapper(dsn,..., name='my.name') ... wrapper = getSAWrapper('my.name')

Supported systems

z3c.sqlalchemy was developed with Zope 2.8/Zope 3.0 and basically tested against Postgres 7.4.X and 8.X and SQLite 3.3.

Known issues

Running z3c.sqalchemy against MySQL databases without transaction support might cause trouble upon the implicit commit() operation. For this reason MySQL without transaction support isn't supported right now

Author

z3c.sqlalchemy was written by Andreas Jung for Haufe Mediengruppe, Freiburg, Germany and ZOPYX Ltd. & Co. KG, Tuebingen, Germany.

License

z3c.sqlalchemy is licensed under the Zope Public License 2.1.

See LICENSE.txt.

Contact

ZOPYX Ltd. & Co. KG
Andreas Jung
Charlottenstr. 37/1
D-72070 Tuebingen, Germany
E-mail: info at zopyx dot com

Credits

Parts of the code are influenced by z3c.zalchemy (Juergen Kartnaller, Michael Bernstein & others) and Alchemist/ore.alchemist (Kapil Thangavelu). Thanks to Martin Aspeli for giving valuable feedback.

Changes

1.4.0 (2009-12-02)
  • removed compatibility code with older Zope versions
  • fixed import issue with modern zope.component versions
  • fixed registering of custom mappers
1.3.11 (26.10.2009)
  • Don't create a new MetaData in LazyMapperCollection,

System Message: WARNING/2 (<string>, line 213)

Bullet list ends without a blank line; unexpected unindent.

but use the one created in the wrapper. In some cases, you could have some tables in the metadata created in the wrapper, and some tables in the metadata created in the LazyMapperCollection, which gave an error when trying to create relations.

  • When generating the mapper class, make sure table.name is a string.

System Message: WARNING/2 (<string>, line 219)

Bullet list ends without a blank line; unexpected unindent.

It can be unicode when use_unicode=1 with MySQL engine.

1.3.10 (04.08.2009)
  • removed SA deprecation warning
1.3.9 (06.01.2009)
  • made 'twophase' configurable
1.3.8 (06.01.2009)
  • replace asDict() with a dictish proxy implementation
1.3.7 (12.12.2008)
  • better support for SQLAlchemy declarative layer
1.3.6 (23.11.2008)
  • zip_safe=False
1.3.5 (05.09.2008)
  • restored compatibiltiy with SA 0.4.X
1.3.4 (04.09.2008)
  • added 'extension_options' parameter
1.3.2 (29.07.2008)
  • updated dependencies to latest zope.sqlalchemy release
1.3.1 (24.06.2008)
  • relaxed zope.* dependencies
1.3.0 (02.06.2008)
  • support for sqlalchemy.ext.declarative
1.2.0 (25.05.2008)
  • now using zope.sqlalchemy for ZODB transaction integration
  • internal class renaming
  • removed PythonBaseWrapper. Now there is only one ZopeWrappe class.
  • requires SQLAlchemy 0.4.6 or higher
  • requires zope.sqlalchemy 0.1 or higher
1.1.5 (08.05.2008)
  • better error handling in case of a rollback (patch by Dieter Maurer)
1.1.4 (15.03.2008)
  • reorganized .txt files
1.1.3 (20.02.2008)
  • another savepoint fix
  • fixed regression error introduced by previous change: commit the

System Message: WARNING/2 (<string>, line 300)

Bullet list ends without a blank line; unexpected unindent.

zope transaction when ready in tpc_finish [maurits]

  • fixed issue where session's transaction.nested was being called as

System Message: WARNING/2 (<string>, line 303)

Bullet list ends without a blank line; unexpected unindent.

a callable (it should be straight attribute access) [Rocky]

1.1.2 (16.02.2008)
  • fixed ZODB savepoint implementation. Now returning a proper dummy

System Message: WARNING/2 (<string>, line 310)

Bullet list ends without a blank line; unexpected unindent.

savepoint

1.1.1 (13.02.2008)
  • the SessionDataManager now supports ZODB savepoints
1.1.0 (17.01.2008)
  • WARNING: this version requires SA 0.4.X and higher
  • fixed import issues with the upcoming SA 0.4.X series
  • create_session() calls (for SA 0.4.X)
  • the unittests support an optional $TEST_DSN environment in order

System Message: WARNING/2 (<string>, line 327)

Bullet list ends without a blank line; unexpected unindent.

to run the test against an existing database (other than SQLite)

  • major overhoul of the Zope transaction integration: now using

System Message: WARNING/2 (<string>, line 330)

Bullet list ends without a blank line; unexpected unindent.

one DataManager for the session object and the connection. The connection as returned through the 'connection' property is also used for creating a new 'session'. Older z3c.sqlalchemy version used separate connections. This allows applications to use both a session and a connection within the same Zope request/thread without running into transaction problems. SQL actions and session related modifications should happen within the same transaction.

  • Wrapper constructor now accepts two new optional dicts

System Message: WARNING/2 (<string>, line 340)

Bullet list ends without a blank line; unexpected unindent.

'engine_options' and 'session_options' that will be passed down to the engine and the sessionmaker. Patch provided by Klaus Barthelmann.

  • mapped objects now provide a method asDict() to return the values

System Message: WARNING/2 (<string>, line 345)

Bullet list ends without a blank line; unexpected unindent.

of an objects as dict.

1.0.11 (30.07.2007)
  • replaced BoundMetaData() with MetaData() (requires SA 0.3.9+)
  • removed zope.* dependencies in order to avoid zope.* version

System Message: WARNING/2 (<string>, line 354)

Bullet list ends without a blank line; unexpected unindent.

mismatches for now

1.0.10 (16.07.2007)
  • using Zope 3.3.X as a fixed depenceny
1.0.9 (08.07.2007)
  • added namespace declarations
  • reST-ified documentation
1.0.8 (28.06.2007)
  • SessionDataManager: create a session transaction as late

System Message: WARNING/2 (<string>, line 375)

Bullet list ends without a blank line; unexpected unindent.

as possible and only if necessary in order to minimize deadlocks. So z3c.sqlalchemy won't create a transaction any more if there only SELECT operations within the current session.

1.0.7 (27.06.2007)
  • SessionDataManager: moved commit code from tpc_vote()

System Message: WARNING/2 (<string>, line 384)

Bullet list ends without a blank line; unexpected unindent.

to tpc_finish() (Thanks to Christian Theune for the hint)

1.0.6 (25.06.2007)
  • added 'namespace_packages' directive to setup.py
  • cache 'metadata' property
1.0.5 (13.06.2007)
  • It should be now safe to use sessions from multiple wrappers

System Message: WARNING/2 (<string>, line 397)

Bullet list ends without a blank line; unexpected unindent.

within one Zope transaction. In former versions of z3c.sqlalchemy calling wrapper1.session and wrapper2.session within the same transaction would return a session bound to wrapper1 in both cases.

1.0.4 (09.06.2007)
  • added new 'transactional' flag (used by SQLAlchemyDA only)
1.0.3 (26.05.2007)
  • new 'cascade' parameter for the Model.add()
  • tweaked the ZODB transaction integration a bit
1.0.2 (13.05.2007)
  • MappedClassBase has a new convinience method getMapper() that returns a

System Message: WARNING/2 (<string>, line 418)

Bullet list ends without a blank line; unexpected unindent.

mapper class associated through a relation with the current mapper

1.0.1 (unreleased)
  • MappedClassBase: new clone() method
  • more checks in Model.add()
1.0.0 (05.05.2007)
  • source code polishing
  • documentation update
0.1.13 (05.05.2007)
  • sessions were returned from the wrong cache
  • moved the rollback/commit handling inside the SessionDataManager

System Message: WARNING/2 (<string>, line 443)

Bullet list ends without a blank line; unexpected unindent.

in order to play more nicely with the TPC. See http://mail.zope.org/pipermail/zodb-dev/2007-May/010996.html

0.1.12 (03.05.2007)
  • createSAWrapper() got a new optional 'name' parameter in order

System Message: WARNING/2 (<string>, line 451)

Bullet list ends without a blank line; unexpected unindent.

to register the wrapper automatically instead of using a dedicated registerSAWrapper(wrapper, name) call

0.1.11 (02.05.2007)
  • added check for the 'mapper_class' attribute (classes from now

System Message: WARNING/2 (<string>, line 458)

Bullet list ends without a blank line; unexpected unindent.

on must be a subclass of MapperClassBase)

  • a Zope-aware SAWrapper now has a 'connection' property that can

System Message: WARNING/2 (<string>, line 461)

Bullet list ends without a blank line; unexpected unindent.

be used to execute SQL statements directly. 'connection' is an instance of sqlalchemy.Connection and directly tied to the current Zope transaction.

  • changed the caching of the connection and session object for Zope wrapper

System Message: WARNING/2 (<string>, line 466)

Bullet list ends without a blank line; unexpected unindent.

since the id of a transaction is not reliable (different transaction object can re-use the same memory address leading to cache errors)

0.1.10 (30.04.2007)
  • fixed a bug in mapper (unfortunately I forgot to commit a

System Message: WARNING/2 (<string>, line 474)

Bullet list ends without a blank line; unexpected unindent.

necessary change)

  • removed the 'primary_key' parameter introduced in 0.1.9 because

System Message: WARNING/2 (<string>, line 477)

Bullet list ends without a blank line; unexpected unindent.

we don't need. It can be defined within the model using a PrimaryKeyConstraint()

  • createSAWrapper: setting forZope=True for a non-postgres DSN

System Message: WARNING/2 (<string>, line 481)

Bullet list ends without a blank line; unexpected unindent.

now also returns a Zope-aware wrapper instance (instead of a BaseWrapper instance). (Reported by Martin Aspeli)

0.1.9 (26.04.2007)
  • base.py: the 'model' parameter can now also be a callable

System Message: WARNING/2 (<string>, line 489)

Bullet list ends without a blank line; unexpected unindent.

returning an instance of model.Model

  • base.py: calling a model provider or a method providing a

System Message: WARNING/2 (<string>, line 492)

Bullet list ends without a blank line; unexpected unindent.

model with a BoundMetaData instance in order to allow table auto-loading

  • Model.add() got a new parameter 'primary_key' in order to specify a

System Message: WARNING/2 (<string>, line 496)

Bullet list ends without a blank line; unexpected unindent.

primary_key hint. This is useful when you are trying to auto-load a view as Table() having no primary key information. The 'primary_key' parameter is either None or a sequence of column names.

0.1.8 (23.04.2007)
  • added shorter method names as aliases
  • don't generate a new mapper class if a custom mapper

System Message: WARNING/2 (<string>, line 507)

Bullet list ends without a blank line; unexpected unindent.

class is defined within the model

0.1.7 (21.04.2007)
  • replaced 'echo' parameter of the constructor with a generic keyword

System Message: WARNING/2 (<string>, line 514)

Bullet list ends without a blank line; unexpected unindent.

parameter in order to provide full parameter support for create_engine. Optional arguments passed to the constructur are passed directly to create_engine()

  • fixed the documentation a bit
  • added registerMapper() to BaseWrapper class
  • registerSQLAlchemyWrapper() now defers the registration until

System Message: WARNING/2 (<string>, line 523)

Bullet list ends without a blank line; unexpected unindent.

the Wrapper is used first when calling getSQLAlchemyWrapper()

  • the 'name' parameter of Model.add() now supports schemas (if

System Message: WARNING/2 (<string>, line 526)

Bullet list ends without a blank line; unexpected unindent.

available). E.g. when using Postgres you can reference as table within a different schema through '<schema>.<tablename>'.

  • Model.add() accepts a new optional parameter 'table_name' that

System Message: WARNING/2 (<string>, line 530)

Bullet list ends without a blank line; unexpected unindent.

can be used to specify the name of a table (including schema information) when you want to use the 'name' parameter as an alias for the related table/mapper.

0.1.6 (28.03.2007)
  • fixed a bug in registerSQLAlchemyWrapper
0.1.5 (28.03.2007)
  • registerSQLAlchemyWrapper() should now work with Zope 2.8-2.10
  • abort() was defined twice inside the DataManager class
0.1.4 (21.03.2007)
  • the Model class now behave (where needed) as a sorted

System Message: WARNING/2 (<string>, line 551)

Bullet list ends without a blank line; unexpected unindent.

dictionary. Its items() method must returned all items in insertion order.

0.1.3 (20.03.2007)
  • added getMappers() convenience method
  • the Zope wrapper uses SessionTransactions in order to be able

System Message: WARNING/2 (<string>, line 560)

Bullet list ends without a blank line; unexpected unindent.

to flush() as session with a transaction in order to read row previously inserted within the same transaction

0.1.2 (unreleased)
  • fixed class hierarchy issues with Postgres wrapper classes
0.1.1 (unreleased)
  • fixed setup.py
0.1 (18.03.2007)
  • initial version

Subscribe to package updates

Last updated Jan 5th, 2011

Download Stats

Last month:1

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.