[[PageOutline(2-5,Contents,pullout)]]

= Trac SQLAlchemy Bridge

== Description

This is a bridge for a plugin developer to use [http://www.sqlalchemy.org/ SQLAlchemy] with Trac. SQLAlchemy is a Python SQL toolkit and Object Relational Mapper. SQLAlchemy itself is released under a MIT license.

See also: SqlAlchemyQueryMacro

== Bugs/Feature Requests

Existing bugs and feature requests for TracSqlAlchemyBridgeIntegration are 
[report:9?COMPONENT=TracSqlAlchemyBridgeIntegration here].

If you have any issues, create a 
[/newticket?component=TracSqlAlchemyBridgeIntegration new ticket].

[[TicketQuery(component=TracSqlAlchemyBridgeIntegration&group=type,format=progress)]]

== Download

Download the zipped source from [export:tracsqlalchemybridgeintegration here].

Download at PyPI from [pypi:TracSqlAlchemyBridge/ here].

== Source

You can check out TracSqlAlchemyBridgeIntegration from [/svn/tracsqlalchemybridgeintegration here] using Subversion, or [source:tracsqlalchemybridgeintegration browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Example

You define your tables as SQLAlchemy tells you to on its docs.

Making Trac upgrade its tables to include yours (from the plugin I was developing from which this package was born):
{{{#!python
from trac.core import *
from trac.env import IEnvironmentSetupParticipant
from tsab import engine

from tl10nm import model

class TracL10nManagerSetup(Component):
    implements(IEnvironmentSetupParticipant)

    # IEnvironmentSetupParticipant Methods
    def environment_created(self):
        self.found_db_version = 0
        self.upgrade_environment(self.env.get_db_cnx())

    def environment_needs_upgrade(self, db):
        cursor = db.cursor()
        cursor.execute("SELECT value FROM system WHERE name=%s";,
                       (model.name,))
        value = cursor.fetchone()
        if not value:
            self.found_db_version = 0
            return True
        else:
            self.found_db_version = int(value[0])
            self.log.debug("%s: Found db version %s, current is %s",
                           __package__, self.found_db_version, model.version)
            return self.found_db_version < model.version

    def upgrade_environment(self, db):
        # Currently we only create the tables, so far there's no migration done
        model.metadata.create_all(bind=engine(self.env))
        cursor = db.cursor()
        if not self.found_db_version:
            cursor.execute("INSERT INTO system (name, value) VALUES (%s, %s)",
                           (model.name, model.version))
        else:
            cursor.execute("UPDATE system SET value=%s WHERE name=%s",
                           (model.version, model.name))
}}}

Then to use it in your code (from the plugin I was developing from which this package was born):
{{{#!python

#--------8<------- code cut for readability --------8<-------
from tsab import session
#--------8<------- code cut for readability --------8<-------
class L10nModule(Component):
#--------8<------- code cut for readability --------8<-------
    def _list_messages(self, req, catalog_id, locale_name, page):
        Session = session(self.env)
        locale = Session.query(Locale).filter_by(locale=locale_name,
                                                 catalog_id=catalog_id).first()

        data = {'locale': locale, 'catalog_id': catalog_id}

        paginator = Paginator(list(locale.catalog.messages), page-1, 5)
        data['messages'] = paginator
        shown_pages = paginator.get_shown_pages(25)
        pagedata = []
        for show_page in shown_pages:
            page_href = req.href.translations(catalog_id, locale_name,
                                              show_page)
            pagedata.append([page_href, None, str(show_page),
                             'page %s' % show_page])
        fields = ['href', 'class', 'string', 'title']
        paginator.shown_pages = [dict(zip(fields, p)) for p in pagedata]
        paginator.current_page = {'href': None, 'class': 'current',
                                  'string': str(paginator.page + 1),
                                  'title': None}
        if paginator.has_next_page:
            add_link(req, 'next', req.href.translations(locale_id, page+1),
                     _('Next Page'))
        if paginator.has_previous_page:
            add_link(req, 'prev', req.href.translations(locale_id, page-1),
                     _('Previous Page'))
        return 'l10n_messages.html', data, None
#--------8<------- code cut for readability --------8<-------
}}}

== Recent Changes

[[ChangeLog(tracsqlalchemybridgeintegration, 3)]]

== Author/Contributors

'''Author:''' [wiki:mitsuhiko] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''