What is Alchemical?

Alchemical is a wrapper for SQLAlchemy that simplifies some aspects of its configuration. It is inspired by the Flask-SQLAlchemy extension for Flask.

Alchemical uses the newer 2.0 style query API introduced in SQLAlchemy 1.4, and can be used with or without the Flask framework. It can also be used with asynchronous applications based on the asyncio package.

Examples

The following example creates a SQLite database with a user table, inserts a few users, and finally prints the users to the console.

from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from alchemical import Alchemical, Model

class User(Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(128))

    def __repr__(self):
        return f'<User {self.name}>'

db = Alchemical('sqlite:///users.sqlite')
db.drop_all()
db.create_all()

with db.begin() as session:
    for name in ['mary', 'joe', 'susan']:
        session.add(User(name=name))

with db.Session() as session:
    print(session.scalars(User.select()).all())

The next example implements the same application, but using asyncio:

import asyncio
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from alchemical.aio import Alchemical, Model

class User(Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(128))

    def __repr__(self):
        return f'<User {self.name}>'

async def main():
    db = Alchemical('sqlite:///users.sqlite')
    await db.drop_all()
    await db.create_all()

    async with db.begin() as session:
        for name in ['mary', 'joe', 'susan']:
            session.add(User(name=name))

    async with db.Session() as session:
        print((await session.scalars(User.select())).all())

asyncio.run(main())