findig.extras.sql — Tools for working with SQLAlchemy

Note

This module requires SQLAlchemy and will raise an ImportError if it is not installed.

You can install it by running: pip install sqlalchemy.

class findig.extras.sql.SQLA(engine, app=None, auto_create=True, auto_flush=True)

Bases: object

A helper clase for declaring SQLAlchemy ORM models for Findig apps.

This object will handle the creation and destruction of the SQLAlchemy session automatically, with the downside that a session is created on every request (regardless as to whether it is used).

After you create one of these, you can declare your ORM models by subclassing sqla.Base:

db = SQLA("sqlite:///mydbfile.db", app=app)

class User(db.Base):
    id = Column(Integer, primary_key=True)
    name = Column(String(150))

Parameters:

• app – A Findig application that the database helper should hook into. When provided, the helper will setup and teardown database sessions during requests to that app. It will also create database tables on the first request to the application, if auto_create=True.
• auto_create – If True, all of the tables declared will be created on the first request received. Take special note that this option can only add new tables and does not update a database schema; if changes to the database table structure are made for any model, then you will need to update the structure manually (or by using a tool like Alembic).
• autoflush – If True, all queries made through the session will flush the session first, before issuing the query. See sqlalchemy.orm.session.Session.

attach_to(app)

Hook the helper into an App.

configure_session_factory(**kwargs)

You can configure the helper’s internal session factory here.

Calling this will affect the way sessions are generated for future requests.

create_all(checkfirst=True)

Create all of the database tables

Parameters:checkfirst – If True, the tables are only created if don’t already exist. Otherwise, they are overwritten.

transaction(new_session=False, auto_rollback=True)

A with statement context manager for an SQLAlchemy session.

The generated session is committed as soon as the with statement exits.

Parameters:

• new_session – If True, a brand new SQLAlchemy session is created and returned. The default behavior uses the session that the helper created for the current request.
• auto_rollback – If True, any errors exceptions raised in the with statement will cause the session to rollback.

Usage:

with db.transaction() as session:
    session.add(User(name="Te-je"))

session

Return the SQL Alchemy session for the current request.

class findig.extras.sql.SQLASet(orm_cls)

Bases: findig.tools.dataset.MutableDataSet

An implementation of findig.tools.dataset.MutableDataSet

This class assumes that you’ve used SQLA helper to generate your database sessions. If you haven’t, then you must set the request context variable sqla_session on findig.context.ctx.

Parameters:orm_cls – A mapped SQLAlchemy orm class for the type of records this set should return. If you’ve used SQLA to declare your model, then the class you pass here should be a subclass of sqla.Base. If you haven’t then ensure that the mapped class takes field names as keyword arguments.

exception CommitError(e)

Bases: werkzeug.exceptions.BadRequest

Raised whenever the set cannot successfully add, update or delete items.

The wrapped SQLAlchemy error is available as e.inner.