Welcome to alchimia
¶
alchimia
lets you use most of the SQLAlchemy-core API with Twisted, it
does not allow you to use the ORM.
Getting started¶
from alchimia import wrap_engine
from sqlalchemy import (
create_engine, MetaData, Table, Column, Integer, String
)
from sqlalchemy.schema import CreateTable
from twisted.internet.defer import inlineCallbacks
from twisted.internet.task import react
@inlineCallbacks
def main(reactor):
engine = wrap_engine(reactor, create_engine("sqlite://"))
metadata = MetaData()
users = Table("users", metadata,
Column("id", Integer(), primary_key=True),
Column("name", String()),
)
# Create the table
yield engine.execute(CreateTable(users))
# Insert some users
yield engine.execute(users.insert().values(name="Jeremy Goodwin"))
yield engine.execute(users.insert().values(name="Natalie Hurley"))
yield engine.execute(users.insert().values(name="Dan Rydell"))
yield engine.execute(users.insert().values(name="Casey McCall"))
yield engine.execute(users.insert().values(name="Dana Whitaker"))
result = yield engine.execute(users.select(users.c.name.startswith("D")))
d_users = yield result.fetchall()
# Print out the users
for user in d_users:
print("Username: %s" % user[users.c.name])
# Queries that return results should be explicitly closed to
# release the connection
result.close()
if __name__ == "__main__":
react(main, [])
Contents¶
DDL¶
Because of some of the limitations in the SQLAlchemy API, it’s not possible to
create tables using sqlalchemy.schema.Table.create()
or
sqlalchemy.schema.MetaData.create_all()
. Luckily, SQLAlchemy provides an
API that still makes it possible to create tables and perform other DDL
operations.
Instead of:
users = Table("users", metadata,
Column("id", Integer(), primary_key=True),
Column("name", String()),
)
users.create(engine)
or
metadata.create_all()
You can use sqlalchemy.schema.CreateTable
:
from sqlalchemy.schema import CreateTable
d = engine.execute(CreateTable(users))
API Reference¶
Many of these classes are missing methods from the SQLALchemy API. We encourage you to file bugs in those cases.
-
alchimia.
wrap_engine
(reactor, engine, create_worker=...)¶ This returns a
alchimia.engine.TwistedEngine
.The main entry-point to alchimia. To be used like so:
from sqlalchemy import create_engine from alchimia import wrap_engine from twisted.internet import reactor underlying_engine = create_engine("sqlite://") twisted_engine = wrap_engine(reactor, engine)
reactor
- the Twisted reactor to use with the createdTwistedEngine
.engine
- the underlyingsqlalchemy.engine.Engine
create_worker
- The object that will coordinate concurrent blockingwork behind the scenes. The default implementation, if nothing is passed, is one which will use a threadpool where each Connection is tied to an individual thread.
More precisely, this is a callable that is expected to return an object with 2 methods,
do(work)
(expected to call the 0-argumentwork
callable in a thread), andquit()
, expected to stop any future work from occurring. It may be useful to stub out the default threaded implementation for testing purposes.
-
class
alchimia.engine.
TwistedEngine
¶ Mostly like
sqlalchemy.engine.Engine
except some of the methods returnDeferreds
.-
__init__
(pool, dialect, url, reactor=..., create_worker=...)¶ This constructor is invoked if
TwistedEngine
is created viacreate_engine(..., reactor=reactor, strategy=TWISTED_STRATEGY)
rather than called directly. New applications should preferalchimia.wrap_engine()
. However,create_engine
relays its keyword arguments, so thereactor
andcreate_worker
arguments have the same meaning as they do inalchimia.wrap_engine()
.
-
classmethod
from_sqlalchemy_engine
(reactor, engine, create_worker=...)¶ This is the implementation of
alchimia.wrap_engine
.
-
connect
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with aTwistedConnection
.
-
execute
(*args, **kwargs)¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with aTwistedResultProxy
.
-
has_table
(table_name, schema=None)¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with the result.
-
table_names
(schema=None, connection=None)¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with the result.
-
-
class
alchimia.engine.
TwistedConnection
¶ Mostly like
sqlalchemy.engine.Connection
except some of the methods returnDeferreds
.-
execute
(*args, **kwargs)¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with aTwistedResultProxy
.
-
close
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires when the connection has been closed.
-
closed
¶ Like the SQLAlchemy attribute of the same name.
-
begin
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with aTwistedTransaction
.
-
begin_nested
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with aTwistedTransaction
.
-
in_transaction
()¶ Like the SQLAlchemy method of the same name.
-
-
class
alchimia.engine.
TwistedTransaction
¶ Mostly like
sqlalchemy.engine.Transaction
except some of the methods returnDeferreds
.-
commit
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires when the transaction has been committed.
-
rollback
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires when the transaction has been rolled back.
-
closed
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires when the transaction has been closed.
-
-
class
alchimia.engine.
TwistedResultProxy
¶ Mostly like
sqlalchemy.engine.ResultProxy
except some of the methods returnDeferreds
.-
fetchone
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with a row.
-
fetchall
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with a list of rows.
-
scalar
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with the scalar value.
-
first
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with the scalar value.
-
keys
()¶ Like the SQLAlchemy method of the same name, except returns a
Deferred
which fires with the scalar value.
-
close
()¶ Like the SQLAlchemy method of the same name, it releases the resources used and releases the underlying DB connection.
-
returns_rows
¶ Like the SQLAlchemy attribute of the same name.
-
rowcount
¶ Like the SQLAlchemy attribute of the same name.
-
inserted_primary_key
¶ Like the SQLAlchemy attribute of the same name.
-
Limitations¶
There are two reasons stuff isn’t implemented in alchimia
.
First, because we haven’t gotten there yet. For these items you should file bugs or send pull requests.
Second, some items can’t be implemented because of limitations in SQLAlchemy, there’s almost always a workaround though.