docs: change project name & write a better README

Author: hadrien

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     - name: 🔧 setup uv
       uses: ./.github/uv
     - name: 🧪 pytest
-      run: uv run pytest --cov fastapi_async_sqla --cov-report=term-missing --cov-report=xml
+      run: uv run pytest --cov fastsqla --cov-report=term-missing --cov-report=xml
     - name:  "🐔 codecov: upload test coverage"
       uses: codecov/[email protected]
       env:

README.md

@@ -1,27 +1,36 @@
-# FastAPI-Async-SQLA
+# FastSQLA
 
-[![PyPI - Version](https://img.shields.io/pypi/v/FastAPI-Async-SQLA?color=brightgreen)](https://pypi.org/project/FastAPI-Async-SQLA/)
+[![PyPI - Version](https://img.shields.io/pypi/v/FastSQLA?color=brightgreen)](https://pypi.org/project/FastSQLA/)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg)](https://conventionalcommits.org)
-[![codecov](https://codecov.io/gh/hadrien/fastapi-async-sqla/graph/badge.svg?token=XK3YT60MWK)](https://codecov.io/gh/hadrien/fastapi-async-sqla)
+[![codecov](https://codecov.io/gh/hadrien/fastsqla/graph/badge.svg?token=XK3YT60MWK)](https://codecov.io/gh/hadrien/fastsqla)
 
-FastAPI-Async-SQLA is an [SQLAlchemy] extension for [FastAPI]. It supports asynchronous
-SQLAlchemy sessions using SQLAlchemy >= 2.0 and provides pagination support.
+FastSQLA is an [SQLAlchemy] extension for [FastAPI]. It supports asynchronous
+SQLAlchemy sessions using SQLAlchemy >= 2.0 and include built-in pagination.
 
 # Installing
 
+Using [uv](https://docs.astral.sh/uv/):
+```bash
+uv add fastsqla
+```
+
 Using [pip](https://pip.pypa.io/):
 ```
-pip install fastapi-async-sqla
+pip install fastsqla
 ```
 
 # Quick Example
 
+>! Note
+>! Example uses an sqlite db, but FastSQLA is compatible with any async db supported by
+>! SQLAlchemy
+
 Assuming it runs against a DB with a table `user` with 2 columns `id` and `name`:
 
 ```python
 # main.py
 from fastapi import FastAPI, HTTPException
-from fastapi_async_sqla import Base, Item, Page, Paginate, Session, lifespan
+from fastsqla import Base, Item, Page, Paginate, Session, lifespan
 from pydantic import BaseModel
 from sqlalchemy import select
 
@@ -62,16 +71,35 @@ async def create_user(new_user: UserIn, session: Session):
     return {"data": user}
 ```
 
-Creating a db using `sqlite3`:
+
+Create an `sqlite3` db:
+
 ```bash
 sqlite3 db.sqlite <<EOF
-CREATE TABLE user (
-    id    INTEGER PRIMARY KEY AUTOINCREMENT,
-    name  TEXT NOT NULL
+sqlite3 db.sqlite <<EOF
+CREATE TABLE hero (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    name            TEXT NOT NULL UNIQUE, -- Hero name (e.g., Superman)
+    secret_identity TEXT NOT NULL         -- Secret identity (e.g., Clark Kent)
 );
+
+-- Insert heroes with hero name and secret identity
+INSERT INTO hero (name, secret_identity) VALUES ('Superman', 'Clark Kent');
+INSERT INTO hero (name, secret_identity) VALUES ('Batman', 'Bruce Wayne');
+INSERT INTO hero (name, secret_identity) VALUES ('Wonder Woman', 'Diana Prince');
+INSERT INTO hero (name, secret_identity) VALUES ('Iron Man', 'Tony Stark');
+INSERT INTO hero (name, secret_identity) VALUES ('Spider-Man', 'Peter Parker');
+INSERT INTO hero (name, secret_identity) VALUES ('Captain America', 'Steve Rogers');
+INSERT INTO hero (name, secret_identity) VALUES ('Black Widow', 'Natasha Romanoff');
+INSERT INTO hero (name, secret_identity) VALUES ('Thor', 'Thor Odinson');
+INSERT INTO hero (name, secret_identity) VALUES ('Scarlet Witch', 'Wanda Maximoff');
+INSERT INTO hero (name, secret_identity) VALUES ('Doctor Strange', 'Stephen Strange');
+INSERT INTO hero (name, secret_identity) VALUES ('The Flash', 'Barry Allen');
+INSERT INTO hero (name, secret_identity) VALUES ('Green Lantern', 'Hal Jordan');
 EOF
 ```
 
+
 Installing [aiosqlite] to connect to the sqlite db asynchronously:
 ```bash
 pip install aiosqlite

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
-name = "FastAPI-Async-SQLA"
+name = "FastSQLA"
 version = "0.2.3"
-description = "SQLAlchemy extension for FastAPI with support for asynchronous SQLAlchemy sessions and pagination."
+description = "SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination."
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "Hadrien David", email = "[email protected]" }]
@@ -33,18 +33,14 @@ classifiers = [
 ]
 keywords = ["FastAPI", "SQLAlchemy", "AsyncIO"]
 license = { text = "MIT License" }
-dependencies = [
-    "fastapi>=0.115.6",
-    "sqlalchemy[asyncio]>=2.0.34,<3",
-    "structlog>=24.4.0",
-]
+dependencies = ["fastapi>=0.115.6", "sqlalchemy[asyncio]>=2.0.37", "structlog>=24.4.0"]
 
 [project.urls]
-Homepage = "https://github.com/hadrien/fastapi-async-sqla"
-Documentation = "https://github.com/hadrien/fastapi-async-sqla"
-Repository = "https://github.com/hadrien/fastapi-async-sqla"
-Issues = "https://github.com/hadrien/fastapi-async-sqla/issues"
-Changelog = "https://github.com/hadrien/fastapi-async-sqla/releases"
+Homepage = "https://github.com/hadrien/fastsqla"
+Documentation = "https://github.com/hadrien/fastsqla"
+Repository = "https://github.com/hadrien/fastsqla"
+Issues = "https://github.com/hadrien/fastsqla/issues"
+Changelog = "https://github.com/hadrien/fastsqla/releases"
 
 [tool.uv]
 package = true

src/fastapi_async_sqla.py renamed to src/fastsqla.py

@@ -40,7 +40,7 @@ class Base(DeclarativeBase, DeferredReflection):
 
 
 class State(TypedDict):
-    fastapi_async_sqla_engine: AsyncEngine
+    fastsqla_engine: AsyncEngine
 
 
 @asynccontextmanager
@@ -60,7 +60,7 @@ async def lifespan(_) -> AsyncGenerator[State, None]:
 
     await logger.ainfo("Configured SQLAlchemy.")
 
-    yield {"fastapi_async_sqla_engine": engine}
+    yield {"fastsqla_engine": engine}
 
     SessionFactory.configure(bind=None)
     await engine.dispose()
@@ -120,7 +120,7 @@ class Collection(BaseModel, Generic[T]):
     data: list[T]
 
 
-class Page(Collection):
+class Page(Collection[T]):
     meta: Meta
 
 

tests/conftest.py

@@ -32,7 +32,7 @@ async def session(engine):
 def tear_down():
     from sqlalchemy.orm import clear_mappers
 
-    from fastapi_async_sqla import Base
+    from fastsqla import Base
 
     yield
 

tests/integration/conftest.py

@@ -6,7 +6,7 @@
 
 @fixture
 def app(environ):
-    from fastapi_async_sqla import lifespan
+    from fastsqla import lifespan
 
     app = FastAPI(lifespan=lifespan)
     return app

tests/integration/test_base.py

@@ -17,7 +17,7 @@ async def setup_tear_down(engine):
 
 
 async def test_lifespan_reflects_user_table(environ):
-    from fastapi_async_sqla import Base, lifespan
+    from fastsqla import Base, lifespan
 
     class User(Base):
         __tablename__ = "user"

tests/integration/test_pagination.py

@@ -56,7 +56,7 @@ async def setup_tear_down(engine, faker):
 
 @fixture
 def app(app):
-    from fastapi_async_sqla import (
+    from fastsqla import (
         Base,
         Page,
         Paginate,

tests/integration/test_session_dependency.py

@@ -24,7 +24,7 @@ async def setup_tear_down(engine):
 
 @fixture
 def app(setup_tear_down, app):
-    from fastapi_async_sqla import Base, Item, Session
+    from fastsqla import Base, Item, Session
 
     class User(Base):
         __tablename__ = "user"

tests/unit/test_lifespan.py

@@ -2,14 +2,14 @@
 
 
 async def test_it_returns_state(environ):
-    from fastapi_async_sqla import lifespan
+    from fastsqla import lifespan
 
     async with lifespan(None) as state:
-        assert "fastapi_async_sqla_engine" in state
+        assert "fastsqla_engine" in state
 
 
 async def test_it_binds_an_sqla_engine_to_sessionmaker(environ):
-    from fastapi_async_sqla import SessionFactory, lifespan
+    from fastsqla import SessionFactory, lifespan
 
     assert SessionFactory.kw["bind"] is None
 
@@ -22,7 +22,7 @@ async def test_it_binds_an_sqla_engine_to_sessionmaker(environ):
 
 
 async def test_it_fails_on_a_missing_sqlalchemy_url(monkeypatch):
-    from fastapi_async_sqla import lifespan
+    from fastsqla import lifespan
 
     monkeypatch.delenv("SQLALCHEMY_URL", raising=False)
     with raises(Exception) as raise_info:
@@ -33,7 +33,7 @@ async def test_it_fails_on_a_missing_sqlalchemy_url(monkeypatch):
 
 
 async def test_it_fails_on_not_async_engine(monkeypatch):
-    from fastapi_async_sqla import lifespan
+    from fastsqla import lifespan
 
     monkeypatch.setenv("SQLALCHEMY_URL", "sqlite:///:memory:")
     with raises(Exception) as raise_info: