Metadata-Version: 2.1
Name: Products.SQLAlchemyDA
Version: 1.0.2
Summary: A generic database adapter for Zope
Home-page: https://github.com/zopefoundation/Products.SQLAlchemyDA
Author: Andreas Jung
Author-email: info@zopyx.com
Maintainer: Zope Foundation and Contributors
Maintainer-email: zope-dev@zope.org
License: ZPL 2.1
Project-URL: Issue Tracker, https://github.com/zopefoundation/Products.SQLAlchemyDA/issues
Project-URL: Sources, https://github.com/zopefoundation/Products.SQLAlchemyDA
Description: .. image:: https://github.com/zopefoundation/Products.SQLAlchemyDA/actions/workflows/tests.yml/badge.svg
                :target: https://github.com/zopefoundation/Products.SQLAlchemyDA/actions/workflows/tests.yml
        
        .. image:: https://coveralls.io/repos/github/zopefoundation/Products.SQLAlchemyDA/badge.svg
                :target: https://coveralls.io/github/zopefoundation/Products.SQLAlchemyDA
        
        .. image:: https://img.shields.io/pypi/v/Products.SQLAlchemyDA.svg
                :target: https://pypi.org/project/Products.SQLAlchemyDA/
                :alt: Current version on PyPI
        
        .. image:: https://img.shields.io/pypi/pyversions/Products.SQLAlchemyDA.svg
                :target: https://pypi.org/project/Products.SQLAlchemyDA/
                :alt: Supported Python versions
        
        
        Zope ZSQL-SQLAlchemy Integration Wrapper
        ========================================
        
        
        About SQLAlchemyDA
        ------------------
        
        SQLAlchemyDA is a generic database adapter for Zope ZSQL methods, which are
        an older/legacy SQL templating feature for executing relational database queries
        from with in a Zope to transaction context.
        
        SQLAlchemyDA provides an implementation in the form of a Zope "product" which
        wraps `z3c.sqlalchemy <https://pypi.org/project/z3c.sqlalchemy/>`_, so that
        database connections are installable as objects in the Zope ZMI. Such
        connection objects can be set up to connect to any kind of database backend
        supported by SQLAlchemy using a database URI, such as Postgres, MySQL, Oracle,
        SQLite, MS-SQL, Firebird, Informix. However, some of these database backends
        have not been tested with the SQLAlchemyDA, so your mileage may vary.
        
        In addition to ZSQL support, the SQLAlchemyDA makes it possible to use the
        standard SQLAlchemy API within a Zope context and participate in Zope
        transactions.
        
        However, if you do not require ZSQL support, and only wish to call 'normal'
        SQLAlchemy APIs within Zope transactions, this package adds no value. Instead,
        you would be better off trying out `zope.sqlalchemy`, as recommended in the
        `Zope book chapter on relational database
        connectivity <http://docs.zope.org/zope2/zope2book/RelationalDatabases.html>`_.
        
        
        Requirements:
        -------------
        
        - Zope 4+
        - SQLAlchemy >= 0.5.0 (+ database specific low-level Python drivers)
        - z3c.sqlalchemy >= 1.5.0
        
        Testing: testfixtures are needed to run tests.
        
        
        Installation:
        -------------
        
        - Download and install SQLAlchemy as egg or from the sources
          from PyPI (pip sqlalchemy). See
            
            http://www.sqlalchemy.org
        
            for details
        
        - Download and install z3c.sqlalchemy as egg or from the sources 
          from PyPI (pip z3c.sqlalchemy). See
        
            https://pypi.org/project/z3c.sqlalchemy/
        
          for details.
        
        - Unpack the archive containing SQLAlchemyDA inside the "Products"
          directory of your Zope instance home.
        
        - After restarting Zope you go to the ZMI and create an instance of
          "SQLAlchemyDA" (as you would create some DA instance)
        
        - Click on the new created SQLAlchemyDA instance within the ZMI
          and configure your database connection through the "Properties" tab.
          The connection parameter 'dsn' must be specified as a valid SQLAlchemy DSN 
          like
        
                 <dbschema>://<username>:<password>@<hostname>/<databasename>
        
            Example:
                
                postgres://admin:123@localhost:5432/TestDB
        
        - ZSQL methods should see the new DA through the selection widget of available
          database adapters
        
        - NOTE: you must have the low-level Python DB drivers installed in order to 
          access a particular database. See 
        
                http://www.sqlalchemy.org/docs/dbengine.html#dbengine_supported
        
          for details.
        
        
        Configuration of SQLAlchemyDA:
        ------------------------------
        
        - 'dsn' - SQLAlchemy compliant Database Set Name (see www.sqlalchemy.org/docs)
        
        - 'transactional' - uncheck this property if you are working with a non-transactional
           database like older versions of MySQL. Uncheck this property *only* if you see any
           commit() related error. Otherwise leave this property checked. Changing this
           property *requires* a Zope restart.
        
        - 'quoting_style' - affects how strings are quoted in SQL. By default 'standard' 
           quotes strings correctly. Setting the value to 'no-quote' might solve quoting issues
           with some databases.
        
        
        Using SQLAlchemyDA:
        -------------------
        
        SQLAlchemyDA works as a database adapter as documented within "The Zope Book"
        
        https://zope.readthedocs.io/en/latest/zopebook/RelationalDatabases.html
        
        and can be used like any other DA together with ZSQL methods.
        
        
        Tested with databases:
        ----------------------
        
        - Postgres 7.4, 8.0-8.2
        - SQLite 3.3.X
        - Oracle 10g
        - MySQL is *only* supported for MySQL databases with transaction support.
          (see also z3c/sqlalchemy/README.txt)
        - MSSQL 2008
         
        
        Known issues:
        -------------
        
        """ Database connection could not be opened ((ProgrammingError) (1064, You
        have an error in your SQL syntax near 'COMMIT .
        """
        
        This bug might appear with older MySQL versions when opening/closing
        the connections manually through the ZMI. It should not affect the
        functionality of SQLAlchemyDA.
            
        
        Author
        ------
        
        SQLAlchemyDA was written by Andreas Jung for Haufe Mediengruppe, Freiburg,
        Germany and ZOPYX Ltd. & Co. KG, Tuebingen, Germany.
        
        
        License
        -------
        
        SQLAlchemyDA is  licensed under the Zope Public License 2.1. 
        See LICENSE.txt.
        
        
        Credits
        -------
        
        Parts of the SQLAlchemyDA V 0.3.X development has been sponsored by Wayne
        Volkmuth (renovis.com).
        
        More recent SQLAlchemy support and maintenance sponsored by ZeOmega.com.
        
        CHANGES
        =======
        
        Change log
        ==========
        
        1.0.2 (2021-11-02)
        ------------------
        
        - fix unexpected NoneType return on sql-update
          (`#12 <https://github.com/zopefoundation/Products.SQLAlchemyDA/pull/12>`_)
        
        
        1.0.1 (2021-05-03)
        ------------------
        
        - fix test failures under Python 3.5 by pinning SQLAlchemy.
          Pin can be dropped when support for Zope 4 is dropped.
        
        - change package structure to move package code into a ``src`` subfolder
        
        
        1.0.0 (2020-11-13)
        ------------------
        
        - add linting configurations and apply results
        
        - Package cleanup
        
        - Add support for Python 3.5-3.9
          (`#8 <https://github.com/zopefoundation/Products.SQLAlchemyDA/pull/8>`_)
        
        
        0.6.2b3 (2017-04-03)
        --------------------
        URL fix in add form.
        
        
        0.6.2b2 (2015-06-24)
        --------------------
        
        Workarounds for edge case error conditions looking up or
        creating underlying z3c.sqlalchemy ZopeWrapper instances.
        
        
        0.6.2b1 (2015-06-23)
        --------------------
        
        Beta Release: If you try out this version, please provide feedback!
        
        Added public API for use within Zope acquisition context to access
        the underlying zc3.sqlalchemy `ZopeWrapper` instance, with added
        error handling and logging to deal with situations where Zope
        context may have been lost.
        
        Tests now assume a testrunner such as nose or py.test, and
        testfixtures has been added as a testing dependency.
        
        
        0.6.1b1 (2015-06-19)
        --------------------
        
        Improved safety of non-acquisition public API by making registry no longer
        contain Zope Persistent objects; instead storing and returning only the
        underlying zc3.sqlalchemy `ZopeWrapper` instances. These objects
        are plain Python objects in memory with no Persistent connection to ZODB.
        (Thanks to Tres Seaver for the suggestion!)
        
        
        0.6.0b7 (2015-04-27)
        --------------------
        
        This is a more stable beta, with several fixes. It has been tested
        with SQLAlchemy 0.9.8, Zope2.13, and Python 2.7.9.
        
        Fixes from beta 1-7 include:
        
        - Manifest now includes the .rst, .txt, and .zpt files required
          for installation via ZMI in Zope2.
        - The new `lookup_da` registry was failing to populate after
          Zope restarts; now the registry populates when the DA instance
          unpickles. (TODO: needs test coverage; this feature is not
          as robust as it could be, since the registry could be
          called before unpickling). UPDATE for beta 7: Still no
          test coverage, but after manual testing fixed bug with
          switched key and values in registry.
        - Added a new `clear_da_registry` to support test teardown.
        - NOTE: Beta6 release was taken from the wrong branch,
          and contained experimental untested code. DO not use beta6.
        
        Some non-public patches to support MSSQL have been tested; please inquire if
        interested in having them merged to public code.
        
        
        0.6.0b (2015-03-23)
        -------------------
        
        - Added alternative lookup API to get a handle on SAWrapper instances.  To use
          the new lookup mechanism, see Products.SQLAlchemyDA.da.py and look for the
          function `lookup_da`. This was created to allow avoiding Zope Acquisition as
          a lookup mechanism, and to work around the issue that the underlying
          z3c.sqlalchemy `getSAWrapper` function is non-usable when created by the
          SAWrapper DA. This is because API consumers have no access to the random 
          internally generated name ('util_id' attribute) under which the utility
          is registered...at least not without resorting to Acquisition calls.
        - Tested with SQLAlchemy 0.7.6, Zope 2.13, and Python 2.7.9, and SQLite.
          Your mileage may vary with other databases and versions, but most likely
          it will run with older versions of Zope and Python as old as 2.5 (running
          tests requires at least Python 2.5). Newer versions of SQLAlchemy will be
          tested for the next release.
        
        
        0.5.2 (unreleased)
        ------------------
        - Fixed LP #639597
        
        0.5.1 (2010-08-05)
        ------------------
        - fixed typo in type mapping
        
        0.5.0 (2010-05-07)
        ------------------
        
        - Fixed LP #570208
        - Added a method 'add_extra_engine_options' to set additional engine
          options for SQLAlchemy.create_engine.
        - Removed SOFTWARE_HOME dependency
        - Requires SQLAlchemy >= 0.5.0
        
        0.4.1 (2008-06-01)
        ------------------
        
        - fixed issue with version.txt file
        
        0.4.0 (2008-01-24)
        ------------------
        
        - requires z3c.sqlalchemy (2.0.0 or higher)
        - requires SQLAlchemy 0.4.4 or higer
        
        
        0.3.0 (2007-06-10)
        ------------------
        
        - fixed some security assertions
        - added "Test" tab for executing SQL queries directly
        - better error handling for ZMI screens
        - no longer depending on a pre-registered SQLAlchemy wrapper. SQLAlchemyDA
          now accepts (as any other DA) a DSN as property 'dsn'
        - DSN can be passed through the add form
        - redirect directly to "Info" tab after creating an instance through the ZMI
        - catching some low-level exceptions from the sqlite interface in order to
          make it work with SQLite
        - new properties 'transactional' and 'quoting_style'
        - improved support for Oracle and MySQL
        - SQLAlchemyDA no longer provides access to mapper related functionalities.
          It now acts as a DA for executing SQL statements *only*.
        - fixed unregistration code for a wrapper (hopefully works with Zope 2.8 or
          higher)
        
        - updated documentation
        
        0.2.1 (2007-05-06)
        ------------------
        
        - connections can be closed/opened through the ZMI
        - some code cleanup
        - fixed a *very* stupid typo causing ZODB conflict errors
        
        0.2.0 (2007-05-05)
        ------------------
        
        - first public release
        
        0.1.0 (2007-04-30)
        ------------------
        
        - initial coding
Keywords: Zope Database adapter SQLAlchemy
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 :: Zope
Classifier: Framework :: Zope :: 4
Classifier: Framework :: Zope :: 5
Classifier: Programming Language :: Python
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*
Provides-Extra: test
