hawkapi-sqlalchemy 0.1.0__tar.gz

hawkapi_sqlalchemy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: ruff check
+        run: uv run ruff check .
+      - name: ruff format check
+        run: uv run ruff format --check .
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: pyright
+        run: uv run pyright src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests
+        run: uv run pytest tests/ -q

hawkapi_sqlalchemy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

hawkapi_sqlalchemy-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.log
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+.nox/
+*.swp
+*.swo
+*~
+.DS_Store
+.idea/
+.vscode/
+.history/
+site/
+.remember/

hawkapi_sqlalchemy-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — 2026-05-16
+
+Initial release.
+
+- Async engine + sessionmaker factory; SQLite-aware pool kwargs.
+- `init_database(app, ...)` with three shapes: `url=`, `config=`, or `databases={...}`.
+- Multi-database registry — register any number of named engines (`primary`, `replica`, shards). Replica falls back to primary when absent.
+- DI: `Depends(get_session)`, `Depends(get_replica_session)`, `session_for(name)`. Auto-commit on success, rollback on exception.
+- `Base`, `DataclassBase`, `TimestampMixin`, `UUIDMixin`.
+- Healthchecks: `session_healthy`, `database_healthy`, `all_healthy`.
+- Alembic helper `hawkapi_sqlalchemy.alembic.run_migrations` — handles both online and offline modes.
+- Pytest helpers `temporary_database` / `temporary_session` (in-memory SQLite, schema lifecycle).
+- Extras: `[postgres]` (asyncpg), `[mysql]` (aiomysql).

hawkapi_sqlalchemy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HawkAPI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hawkapi_sqlalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: hawkapi-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy integration for HawkAPI — async sessions, multi-database routing, Alembic helpers, pytest fixtures
+Project-URL: Homepage, https://pypi.org/project/hawkapi-sqlalchemy/
+Project-URL: Repository, https://github.com/ashimov/hawkapi-sqlalchemy
+Project-URL: Issues, https://github.com/ashimov/hawkapi-sqlalchemy/issues
+Author-email: HawkAPI Contributors <hawkapi@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 HawkAPI Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: alembic,async,database,hawkapi,mysql,postgres,sqlalchemy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: alembic>=1.13
+Requires-Dist: hawkapi>=0.1.7
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# hawkapi-sqlalchemy
+
+SQLAlchemy integration for [HawkAPI](https://github.com/ashimov/HawkAPI). Async sessions, multi-database routing (primary/replica/shards), Alembic helpers, and pytest fixtures.
+
+## Install
+
+```bash
+pip install hawkapi-sqlalchemy                     # SQLite included
+pip install 'hawkapi-sqlalchemy[postgres]'         # + asyncpg
+pip install 'hawkapi-sqlalchemy[mysql]'            # + aiomysql
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hawkapi_sqlalchemy import Base, TimestampMixin, get_session, init_database
+
+
+class User(Base, TimestampMixin):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    email: Mapped[str] = mapped_column(unique=True)
+
+
+app = HawkAPI()
+init_database(app, url="postgresql+asyncpg://user:pw@localhost/app")
+
+
+@app.post("/users")
+async def create(email: str, sess: AsyncSession = Depends(get_session)):
+    sess.add(User(email=email))
+    await sess.flush()
+    return {"ok": True}
+```
+
+The `get_session` dependency opens a fresh session per request, **commits on success**, and **rolls back on exception** — no boilerplate.
+
+## Multiple databases
+
+```python
+from hawkapi_sqlalchemy import DatabaseConfig, init_database, session_for
+
+init_database(
+    app,
+    databases={
+        "primary": DatabaseConfig(url="postgresql+asyncpg://…/primary"),
+        "replica": DatabaseConfig(url="postgresql+asyncpg://…/replica"),
+        "analytics": DatabaseConfig(url="postgresql+asyncpg://…/analytics"),
+    },
+)
+
+# DI helpers:
+from hawkapi_sqlalchemy import get_session, get_replica_session
+
+get_analytics = session_for("analytics", commit=False)
+
+
+@app.get("/report")
+async def report(sess: AsyncSession = Depends(get_analytics)):
+    ...
+```
+
+`get_replica_session` falls back to `primary` if no replica is registered, so you can switch on without changing handlers.
+
+## Mixins
+
+```python
+from hawkapi_sqlalchemy import Base, TimestampMixin, UUIDMixin
+
+
+class Doc(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "docs"
+    title: Mapped[str] = mapped_column()
+```
+
+- `TimestampMixin` — `created_at` / `updated_at` with DB-side defaults + Python `onupdate`.
+- `UUIDMixin` — string `id` column with a `uuid4()` default.
+- Prefer `DataclassBase` over `Base` to get SQLAlchemy 2.0's dataclass-style declarative.
+
+## Alembic
+
+In your `alembic/env.py`:
+
+```python
+from hawkapi_sqlalchemy.alembic import run_migrations
+from myapp.db import Base, settings  # your Base + URL
+
+run_migrations(target_metadata=Base.metadata, url=settings.database_url)
+```
+
+That's it — handles both online (live connection) and offline (`--sql`) modes; uses `NullPool` for migrations; enables `render_as_batch=True` automatically for SQLite.
+
+## Healthchecks
+
+```python
+from hawkapi_sqlalchemy import all_healthy
+
+
+@app.get("/healthz")
+async def healthz():
+    return await all_healthy(app.state.db)
+```
+
+Returns `{"primary": True, "replica": True, ...}`.
+
+## Testing
+
+```python
+import pytest
+from hawkapi_sqlalchemy import Base, temporary_database
+
+
+@pytest.fixture
+async def db():
+    async with temporary_database(Base.metadata) as database:
+        yield database
+
+
+async def test_something(db):
+    async with db.session() as sess:
+        ...
+```
+
+`temporary_database` creates an in-memory SQLite engine, calls `Base.metadata.create_all`, yields, then drops the schema and disposes.
+
+## DatabaseConfig
+
+```python
+DatabaseConfig(
+    url="postgresql+asyncpg://…",
+    echo=False,
+    pool_size=5,
+    max_overflow=10,
+    pool_timeout=30.0,
+    pool_recycle=3600,
+    pool_pre_ping=True,
+    connect_args={"server_settings": {"jit": "off"}},
+    engine_kwargs={...},     # forwarded to create_async_engine
+    session_kwargs={...},    # forwarded to async_sessionmaker
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-sqlalchemy.git
+cd hawkapi-sqlalchemy
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_sqlalchemy-0.1.0/README.md

@@ -0,0 +1,160 @@
+# hawkapi-sqlalchemy
+
+SQLAlchemy integration for [HawkAPI](https://github.com/ashimov/HawkAPI). Async sessions, multi-database routing (primary/replica/shards), Alembic helpers, and pytest fixtures.
+
+## Install
+
+```bash
+pip install hawkapi-sqlalchemy                     # SQLite included
+pip install 'hawkapi-sqlalchemy[postgres]'         # + asyncpg
+pip install 'hawkapi-sqlalchemy[mysql]'            # + aiomysql
+```
+
+## Quickstart
+
+```python
+from hawkapi import Depends, HawkAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Mapped, mapped_column
+
+from hawkapi_sqlalchemy import Base, TimestampMixin, get_session, init_database
+
+
+class User(Base, TimestampMixin):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    email: Mapped[str] = mapped_column(unique=True)
+
+
+app = HawkAPI()
+init_database(app, url="postgresql+asyncpg://user:pw@localhost/app")
+
+
+@app.post("/users")
+async def create(email: str, sess: AsyncSession = Depends(get_session)):
+    sess.add(User(email=email))
+    await sess.flush()
+    return {"ok": True}
+```
+
+The `get_session` dependency opens a fresh session per request, **commits on success**, and **rolls back on exception** — no boilerplate.
+
+## Multiple databases
+
+```python
+from hawkapi_sqlalchemy import DatabaseConfig, init_database, session_for
+
+init_database(
+    app,
+    databases={
+        "primary": DatabaseConfig(url="postgresql+asyncpg://…/primary"),
+        "replica": DatabaseConfig(url="postgresql+asyncpg://…/replica"),
+        "analytics": DatabaseConfig(url="postgresql+asyncpg://…/analytics"),
+    },
+)
+
+# DI helpers:
+from hawkapi_sqlalchemy import get_session, get_replica_session
+
+get_analytics = session_for("analytics", commit=False)
+
+
+@app.get("/report")
+async def report(sess: AsyncSession = Depends(get_analytics)):
+    ...
+```
+
+`get_replica_session` falls back to `primary` if no replica is registered, so you can switch on without changing handlers.
+
+## Mixins
+
+```python
+from hawkapi_sqlalchemy import Base, TimestampMixin, UUIDMixin
+
+
+class Doc(Base, UUIDMixin, TimestampMixin):
+    __tablename__ = "docs"
+    title: Mapped[str] = mapped_column()
+```
+
+- `TimestampMixin` — `created_at` / `updated_at` with DB-side defaults + Python `onupdate`.
+- `UUIDMixin` — string `id` column with a `uuid4()` default.
+- Prefer `DataclassBase` over `Base` to get SQLAlchemy 2.0's dataclass-style declarative.
+
+## Alembic
+
+In your `alembic/env.py`:
+
+```python
+from hawkapi_sqlalchemy.alembic import run_migrations
+from myapp.db import Base, settings  # your Base + URL
+
+run_migrations(target_metadata=Base.metadata, url=settings.database_url)
+```
+
+That's it — handles both online (live connection) and offline (`--sql`) modes; uses `NullPool` for migrations; enables `render_as_batch=True` automatically for SQLite.
+
+## Healthchecks
+
+```python
+from hawkapi_sqlalchemy import all_healthy
+
+
+@app.get("/healthz")
+async def healthz():
+    return await all_healthy(app.state.db)
+```
+
+Returns `{"primary": True, "replica": True, ...}`.
+
+## Testing
+
+```python
+import pytest
+from hawkapi_sqlalchemy import Base, temporary_database
+
+
+@pytest.fixture
+async def db():
+    async with temporary_database(Base.metadata) as database:
+        yield database
+
+
+async def test_something(db):
+    async with db.session() as sess:
+        ...
+```
+
+`temporary_database` creates an in-memory SQLite engine, calls `Base.metadata.create_all`, yields, then drops the schema and disposes.
+
+## DatabaseConfig
+
+```python
+DatabaseConfig(
+    url="postgresql+asyncpg://…",
+    echo=False,
+    pool_size=5,
+    max_overflow=10,
+    pool_timeout=30.0,
+    pool_recycle=3600,
+    pool_pre_ping=True,
+    connect_args={"server_settings": {"jit": "off"}},
+    engine_kwargs={...},     # forwarded to create_async_engine
+    session_kwargs={...},    # forwarded to async_sessionmaker
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ashimov/hawkapi-sqlalchemy.git
+cd hawkapi-sqlalchemy
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright src/
+```
+
+## License
+
+MIT.

hawkapi_sqlalchemy-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hawkapi-sqlalchemy"
+version = "0.1.0"
+description = "SQLAlchemy integration for HawkAPI — async sessions, multi-database routing, Alembic helpers, pytest fixtures"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [
+    { name = "HawkAPI Contributors", email = "hawkapi@users.noreply.github.com" },
+]
+keywords = ["hawkapi", "sqlalchemy", "async", "database", "alembic", "postgres", "mysql"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Database :: Front-Ends",
+    "Typing :: Typed",
+]
+dependencies = [
+    "hawkapi>=0.1.7",
+    "sqlalchemy[asyncio]>=2.0",
+    "alembic>=1.13",
+    "aiosqlite>=0.20",
+]
+
+[project.optional-dependencies]
+postgres = ["asyncpg>=0.29"]
+mysql = ["aiomysql>=0.2"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "pyright>=1.1",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/hawkapi-sqlalchemy/"
+Repository = "https://github.com/ashimov/hawkapi-sqlalchemy"
+Issues = "https://github.com/ashimov/hawkapi-sqlalchemy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hawkapi_sqlalchemy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "S"]
+ignore = ["S101", "B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportMissingTypeStubs = false

hawkapi_sqlalchemy-0.1.0/src/hawkapi_sqlalchemy/__init__.py

@@ -0,0 +1,41 @@
+"""hawkapi-sqlalchemy — SQLAlchemy integration for HawkAPI.
+
+Async engines, multi-database routing (primary / replica / shards), per-request
+sessions with auto-commit/rollback, Alembic helpers, and pytest fixtures.
+"""
+
+from __future__ import annotations
+
+from ._alembic import run_migrations
+from ._database import Database, init_database, resolve_database
+from ._engine import DatabaseConfig, Engine, create_engine
+from ._health import all_healthy, database_healthy, session_healthy
+from ._models import Base, DataclassBase, TimestampMixin, UUIDMixin
+from ._session import get_replica_session, get_session, open_session, session_for
+from ._testing import temporary_database, temporary_session
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Base",
+    "DataclassBase",
+    "Database",
+    "DatabaseConfig",
+    "Engine",
+    "TimestampMixin",
+    "UUIDMixin",
+    "__version__",
+    "all_healthy",
+    "create_engine",
+    "database_healthy",
+    "get_replica_session",
+    "get_session",
+    "init_database",
+    "open_session",
+    "resolve_database",
+    "run_migrations",
+    "session_for",
+    "session_healthy",
+    "temporary_database",
+    "temporary_session",
+]