Metadata-Version: 1.0
Name: z3c.sqlalchemy
Version: 1.3.0
Summary: A SQLAlchemy wrapper for Zope 2 and Zope 3
Home-page: http://svn.zope.org/z3c.sqlalchemy/tags/1.3.0
Author: Andreas Jung
Author-email: info@zopyx.com
License: ZPL (see LICENSE.txt)
Description: =====================================================
        z3c.sqlalchemy - A SQLAlchemy wrapper for Python/Zope
        =====================================================
        
        
        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::
        
        easy_install z3c.sqlalchemy
        
        or using Python directly::
        
        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::
        
        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).::
        
        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::
        
        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::
        
        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
        | Web: http://www.zopyx.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.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
        zope transaction when ready in tpc_finish [maurits]
        
        - fixed issue where session's transaction.nested was being called as
        a callable (it should be straight attribute access) [Rocky]
        
        
        1.1.2 (16.02.2008)
        -------------------
        
        - fixed ZODB savepoint implementation. Now returning a proper dummy
        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
        to run the test against an existing database (other than SQLite)
        
        - major overhoul of the Zope transaction integration: now using
        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
        '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
        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
        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
        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()
        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
        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
        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
        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
        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
        on must be a subclass of MapperClassBase)
        
        - a Zope-aware SAWrapper now has a 'connection' property that can
        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
        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
        necessary change)
        
        - removed the 'primary_key' parameter introduced in 0.1.9 because
        we don't need. It can be defined within the model using a
        PrimaryKeyConstraint()
        
        - createSAWrapper: setting forZope=True for a non-postgres DSN
        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
        returning an instance of model.Model
        
        - base.py: calling a model provider or a method providing a
        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
        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
        class is defined within the model
        
        
        0.1.7 (21.04.2007)
        ------------------
        
        - replaced 'echo' parameter of the constructor with a generic keyword
        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
        the Wrapper is used first when calling getSQLAlchemyWrapper()
        
        - the 'name' parameter of Model.add() now supports schemas (if
        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
        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
        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
        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
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Zope2
Classifier: Framework :: Zope3
Classifier: Programming Language :: Python
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
