hajimi-sqlalchemy 0.0.1__tar.gz

hajimi_sqlalchemy-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huruhi
+
+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.

hajimi_sqlalchemy-0.0.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: hajimi-sqlalchemy
+Version: 0.0.1
+Requires-Python: >=3.14
+License-File: LICENSE
+Requires-Dist: hajimi-core>=0.1.0
+Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49
+Dynamic: license-file

hajimi_sqlalchemy-0.0.1/README.md

@@ -0,0 +1,7 @@
+# hajimi-core
+
+## Install
+
+```bash
+pip install hajimi-sqlalchemy
+```

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseModel
+from .config import HajimiSQLAlchemyConfig
+from .dependencies import SessionDep
+from .plugin import HajimiSQLAlchemyPlugin

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy/base.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class BaseModel(DeclarativeBase):
+    __abstract__ = True

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy/config.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+from sqlalchemy import URL
+
+
+@dataclass(frozen=True, kw_only=True)
+class HajimiSQLAlchemyConfig:
+    username: str
+    password: str
+    host: str
+    port: int = 5432
+    database: str
+
+    echo: bool = False
+    pool_size: int = 3
+    max_overflow: int = 2
+    pool_timeout: int = 30
+    pool_recycle: int = 1800
+
+    @property
+    def url(self) -> URL:
+        return URL.create(
+            drivername='postgresql+psycopg',
+            username=self.username,
+            password=self.password,
+            host=self.host,
+            port=self.port,
+            database=self.database,
+        )

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy/dependencies.py

@@ -0,0 +1,20 @@
+"""FastAPI dependencies exposing the SQLAlchemy async session."""
+
+from typing import Annotated, AsyncGenerator
+
+from fastapi import Depends, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .plugin import HajimiSQLAlchemyPlugin
+
+
+async def get_session(request: Request) -> AsyncGenerator[AsyncSession, None]:
+    """Yield an ``AsyncSession`` scoped to the request, opened from the registered plugin."""
+    app_state = request.app.state._state['__app_state__']
+    plugin: HajimiSQLAlchemyPlugin = getattr(app_state, HajimiSQLAlchemyPlugin.__name__)
+
+    async with plugin.session_maker.begin() as session:
+        yield session
+
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy/plugin.py

@@ -0,0 +1,44 @@
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from .config import HajimiSQLAlchemyConfig
+
+
+class HajimiSQLAlchemyPlugin:
+    def __init__(self, config: HajimiSQLAlchemyConfig) -> None:
+        self._config = config
+        self._engine: AsyncEngine | None = None
+        self._session_maker: async_sessionmaker[AsyncSession] | None = None
+
+    @property
+    def session_maker(self) -> async_sessionmaker[AsyncSession]:
+        if not isinstance(self._session_maker, async_sessionmaker):
+            raise RuntimeError(
+                'HajimiSQLAlchemyPlugin.session_maker is unavailable: '
+                'startup() has not been called or shutdown() has already run.'
+            )
+    
+        return self._session_maker
+
+    async def startup(self, app: FastAPI) -> None:
+        self._engine = create_async_engine(
+            url=self._config.url,
+            echo=self._config.echo,
+            pool_size=self._config.pool_size,
+            max_overflow=self._config.max_overflow,
+            pool_timeout=self._config.pool_timeout,
+            pool_recycle=self._config.pool_recycle,
+            pool_pre_ping=True,
+            connect_args={'connect_timeout': 6},
+        )
+        self._session_maker = async_sessionmaker(engine=self._engine)
+        app.state.__app__state[self.__name__] = self
+
+    async def shutdown(self, app: FastAPI) -> None:
+        if self._session_maker is not None:
+            self._session_maker = None
+        if self._engine is not None:
+            await self._engine.dispose()
+            self._engine = None
+
+        app.state.__app__state.pop(self.__name__, None)

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: hajimi-sqlalchemy
+Version: 0.0.1
+Requires-Python: >=3.14
+License-File: LICENSE
+Requires-Dist: hajimi-core>=0.1.0
+Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49
+Dynamic: license-file

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+hajimi_sqlalchemy/__init__.py
+hajimi_sqlalchemy/base.py
+hajimi_sqlalchemy/config.py
+hajimi_sqlalchemy/dependencies.py
+hajimi_sqlalchemy/plugin.py
+hajimi_sqlalchemy.egg-info/PKG-INFO
+hajimi_sqlalchemy.egg-info/SOURCES.txt
+hajimi_sqlalchemy.egg-info/dependency_links.txt
+hajimi_sqlalchemy.egg-info/requires.txt
+hajimi_sqlalchemy.egg-info/top_level.txt
+tests/test_base.py
+tests/test_config.py
+tests/test_dependencies.py
+tests/test_init.py
+tests/test_plugin.py

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy.egg-info/requires.txt

@@ -0,0 +1,2 @@
+hajimi-core>=0.1.0
+sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49

hajimi_sqlalchemy-0.0.1/hajimi_sqlalchemy.egg-info/top_level.txt

@@ -0,0 +1 @@
+hajimi_sqlalchemy

hajimi_sqlalchemy-0.0.1/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hajimi-sqlalchemy"
+version = "0.0.1"
+requires-python = ">=3.14"
+dependencies = [
+    "hajimi-core>=0.1.0",
+    "sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.1.0",
+    "pytest-asyncio>=0.25.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["."]
+testpaths = ["tests"]

hajimi_sqlalchemy-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hajimi_sqlalchemy-0.0.1/tests/test_base.py

@@ -0,0 +1,40 @@
+"""Tests for hajimi_sqlalchemy.base.BaseModel."""
+
+from sqlalchemy import Column, Integer, String
+from sqlalchemy.orm import DeclarativeBase
+
+from hajimi_sqlalchemy.base import BaseModel
+
+
+def test_base_model_is_subclass_of_declarative_base():
+    """BaseModel must inherit from SQLAlchemy's DeclarativeBase."""
+
+    assert isinstance(BaseModel, type)
+    assert issubclass(BaseModel, DeclarativeBase)
+
+
+def test_base_model_is_marked_abstract():
+    """``__abstract__ = True`` so BaseModel never produces a table of its own."""
+
+    assert BaseModel.__abstract__ is True
+
+
+def test_base_model_carries_metadata():
+    """BaseModel exposes a SQLAlchemy ``MetaData`` instance for subclasses to share."""
+
+    # DeclarativeBase always carries a MetaData attribute.
+    assert hasattr(BaseModel, 'metadata')
+
+
+def test_concrete_subclass_uses_base_model_metadata():
+    """A concrete subclass should be wired through BaseModel.metadata."""
+
+    class Item(BaseModel):
+        __tablename__ = 'items_for_base_model_test'
+        id = Column(Integer, primary_key=True)
+        name = Column(String)
+
+    # The subclass must share BaseModel's MetaData.
+    assert Item.metadata is BaseModel.metadata
+    # And SQLAlchemy's declarative machinery has registered the table.
+    assert 'items_for_base_model_test' in BaseModel.metadata.tables

hajimi_sqlalchemy-0.0.1/tests/test_config.py

@@ -0,0 +1,121 @@
+"""Tests for hajimi_sqlalchemy.config.HajimiSQLAlchemyConfig."""
+
+import dataclasses
+
+import pytest
+from sqlalchemy import URL
+
+from hajimi_sqlalchemy.config import HajimiSQLAlchemyConfig
+
+
+def _base(**overrides):
+    """Build a config with sensible defaults, applying caller overrides."""
+
+    defaults = dict(
+        username='u',
+        password='p',
+        host='localhost',
+        port=5432,
+        database='d',
+        echo=False,
+        pool_size=3,
+        max_overflow=2,
+        pool_timeout=30,
+        pool_recycle=1800,
+    )
+    defaults.update(overrides)
+    return HajimiSQLAlchemyConfig(**defaults)
+
+
+def test_defaults_when_only_required_fields_given():
+    """Defaults are applied for every optional connection / pool field."""
+
+    cfg = HajimiSQLAlchemyConfig(username='u', password='p', host='h', database='d')
+
+    assert cfg.username == 'u'
+    assert cfg.password == 'p'
+    assert cfg.host == 'h'
+    assert cfg.port == 5432
+    assert cfg.database == 'd'
+
+    assert cfg.echo is False
+    assert cfg.pool_size == 3
+    assert cfg.max_overflow == 2
+    assert cfg.pool_timeout == 30
+    assert cfg.pool_recycle == 1800
+
+
+def test_custom_values_override_defaults():
+    """Every optional field can be supplied explicitly."""
+
+    cfg = _base(port=6543, echo=True, pool_size=11, max_overflow=4, pool_timeout=12, pool_recycle=900)
+
+    assert cfg.port == 6543
+    assert cfg.echo is True
+    assert cfg.pool_size == 11
+    assert cfg.max_overflow == 4
+    assert cfg.pool_timeout == 12
+    assert cfg.pool_recycle == 900
+
+
+def test_url_property_uses_custom_port():
+    """The SQLAlchemy URL reflects every connection parameter including a custom port."""
+
+    cfg = _base(
+        username='alice',
+        password='s3cret',
+        host='db.example.com',
+        port=6543,
+        database='appdb',
+    )
+
+    url = cfg.url
+
+    assert isinstance(url, URL)
+    assert url.drivername == 'postgresql+psycopg'
+    assert url.username == 'alice'
+    assert url.password == 's3cret'
+    assert url.host == 'db.example.com'
+    assert url.port == 6543
+    assert url.database == 'appdb'
+
+
+def test_url_property_uses_default_port():
+    """When port is left at the default, the URL still carries it through."""
+
+    cfg = HajimiSQLAlchemyConfig(username='u', password='p', host='db', database='d')
+
+    url = cfg.url
+
+    assert url.port == 5432
+    assert url.drivername == 'postgresql+psycopg'
+
+
+def test_url_property_is_recomputed_each_call():
+    """Each access returns a fresh URL object reflecting the current field values."""
+
+    cfg = _base(host='first')
+    first = cfg.url
+
+    cfg2 = dataclasses.replace(cfg, host='second')
+    second = cfg2.url
+
+    assert first.host == 'first'
+    assert second.host == 'second'
+
+
+def test_instance_is_frozen():
+    """The dataclass is frozen: assignments raise FrozenInstanceError."""
+
+    cfg = HajimiSQLAlchemyConfig(username='u', password='p', host='h', database='d')
+
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        cfg.username = 'new'
+
+
+def test_config_is_kw_only():
+    """Positional arguments are rejected because the dataclass is kw_only."""
+
+    with pytest.raises(TypeError):
+        # Intentionally pass positional args; should raise because of kw_only=True.
+        HajimiSQLAlchemyConfig('u', 'p', 'h', 5432, 'd')

hajimi_sqlalchemy-0.0.1/tests/test_dependencies.py

@@ -0,0 +1,65 @@
+"""Tests for hajimi_sqlalchemy.dependencies."""
+
+import typing
+
+import pytest
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from hajimi_sqlalchemy.config import HajimiSQLAlchemyConfig
+from hajimi_sqlalchemy.dependencies import SessionDep, get_session
+from hajimi_sqlalchemy.plugin import HajimiSQLAlchemyPlugin
+
+
+class _Namespace:
+    """Container that holds the plugin attribute under ``HajimiSQLAlchemyPlugin.__name__``."""
+
+
+def _make_request(app):
+    """Minimal ``Request``-shaped object exposing ``app``."""
+
+    class _Request:
+        def __init__(self, app):
+            self.app = app
+
+    return _Request(app)
+
+
+async def test_get_session_yields_session_and_finishes(fake_session, fake_session_factory):
+    """``get_session`` must yield the session from ``session_maker.begin()`` then exit cleanly."""
+
+    cfg = HajimiSQLAlchemyConfig(username='u', password='p', host='localhost', database='d')
+    plugin = HajimiSQLAlchemyPlugin(cfg)
+    # Bypass real startup() — this test focuses on dependencies.get_session itself.
+    plugin._session_maker = fake_session_factory
+
+    namespace = _Namespace()
+    setattr(namespace, HajimiSQLAlchemyPlugin.__name__, plugin)
+
+    app = FastAPI()
+    # Seed starlette's underlying state dict with the exact key dependencies.py looks up.
+    app.state._state['__app_state__'] = namespace
+
+    request = _make_request(app)
+
+    gen = get_session(request)
+
+    # First __anext__ enters the ``async with`` and yields the session.
+    session = await gen.__anext__()
+    assert session is fake_session
+
+    # Second __anext__ runs the cleanup path (yield -> line 13) and the generator returns.
+    with pytest.raises(StopAsyncIteration):
+        await gen.__anext__()
+
+
+def test_session_dep_is_annotated_async_session():
+    """``SessionDep`` is an ``Annotated`` alias whose first type-arg is ``AsyncSession``."""
+
+    origin = typing.get_origin(SessionDep)
+    args = typing.get_args(SessionDep)
+
+    # Annotated[...] has a non-None typing origin.
+    assert origin is not None
+    # The first type-arg of Annotated[..., Depends(...)] should be AsyncSession.
+    assert args[0] is AsyncSession

hajimi_sqlalchemy-0.0.1/tests/test_init.py

@@ -0,0 +1,28 @@
+"""Tests for the top-level ``hajimi_sqlalchemy`` package."""
+
+import hajimi_sqlalchemy
+from hajimi_sqlalchemy import BaseModel, HajimiSQLAlchemyConfig, HajimiSQLAlchemyPlugin
+
+
+def test_package_imports():
+    """The package must import without side effects and expose ``__name__``."""
+
+    assert hajimi_sqlalchemy.__name__ == 'hajimi_sqlalchemy'
+
+
+def test_package_reexports_base_model():
+    """``BaseModel`` is part of the public surface."""
+
+    assert BaseModel is hajimi_sqlalchemy.base.BaseModel
+
+
+def test_package_reexports_config():
+    """``HajimiSQLAlchemyConfig`` is part of the public surface."""
+
+    assert HajimiSQLAlchemyConfig is hajimi_sqlalchemy.config.HajimiSQLAlchemyConfig
+
+
+def test_package_reexports_plugin():
+    """``HajimiSQLAlchemyPlugin`` is part of the public surface."""
+
+    assert HajimiSQLAlchemyPlugin is hajimi_sqlalchemy.plugin.HajimiSQLAlchemyPlugin

hajimi_sqlalchemy-0.0.1/tests/test_plugin.py

@@ -0,0 +1,94 @@
+"""Tests for hajimi_sqlalchemy.plugin.HajimiSQLAlchemyPlugin."""
+
+import pytest
+
+from hajimi_sqlalchemy.plugin import HajimiSQLAlchemyPlugin
+
+from .stubs import FakeAsyncSessionMaker
+
+
+def test_init_leaves_engine_and_session_maker_uninitialised(primed_plugin):
+    """Constructing a plugin must not eagerly create a database engine."""
+
+    assert primed_plugin._engine is None
+    assert primed_plugin._session_maker is None
+
+
+def test_session_maker_raises_before_startup(primed_plugin):
+    """Accessing session_maker before startup() raises a descriptive RuntimeError."""
+
+    with pytest.raises(RuntimeError, match='session_maker is unavailable'):
+        _ = primed_plugin.session_maker
+
+
+async def test_startup_creates_engine_and_registers_plugin(
+    fake_engine, primed_plugin, app_for_plugin, plugin_state_key,
+):
+    """startup() must drive the patched factories and stash the plugin on app.state."""
+
+    await primed_plugin.startup(app_for_plugin)
+
+    assert primed_plugin._engine is fake_engine
+    # The session_maker is an instance of the stand-in sessionmaker type, built inside startup().
+    assert isinstance(primed_plugin._session_maker, FakeAsyncSessionMaker)
+    stored = app_for_plugin.state._state[plugin_state_key][HajimiSQLAlchemyPlugin.__name__]
+    assert stored is primed_plugin
+
+
+async def test_session_maker_property_succeeds_after_startup(primed_plugin, app_for_plugin):
+    """Once startup() has run, the session_maker property returns the cached factory."""
+
+    await primed_plugin.startup(app_for_plugin)
+
+    assert isinstance(primed_plugin.session_maker, FakeAsyncSessionMaker)
+
+
+async def test_shutdown_disposes_engine_and_clears_state(
+    fake_engine, primed_plugin, app_for_plugin, plugin_state_key,
+):
+    """shutdown() must dispose the engine, clear internal refs and remove the store entry."""
+
+    await primed_plugin.startup(app_for_plugin)
+    # Sanity check: startup registered the plugin.
+    assert app_for_plugin.state._state[plugin_state_key][HajimiSQLAlchemyPlugin.__name__] is primed_plugin
+
+    await primed_plugin.shutdown(app_for_plugin)
+
+    assert fake_engine.dispose_calls == 1
+    assert primed_plugin._engine is None
+    assert primed_plugin._session_maker is None
+    assert HajimiSQLAlchemyPlugin.__name__ not in app_for_plugin.state._state[plugin_state_key]
+
+
+async def test_shutdown_without_startup_is_safe(primed_plugin, app_for_plugin):
+    """Calling shutdown() without a prior startup() must be a safe no-op."""
+
+    await primed_plugin.shutdown(app_for_plugin)
+
+    assert primed_plugin._engine is None
+    assert primed_plugin._session_maker is None
+
+
+async def test_shutdown_is_idempotent(fake_engine, primed_plugin, app_for_plugin):
+    """A second shutdown() after the first must remain a no-op."""
+
+    await primed_plugin.startup(app_for_plugin)
+    await primed_plugin.shutdown(app_for_plugin)
+    initial_dispose_calls = fake_engine.dispose_calls
+
+    await primed_plugin.shutdown(app_for_plugin)
+
+    # The second call must not re-dispose the already-None engine.
+    assert fake_engine.dispose_calls == initial_dispose_calls
+    assert primed_plugin._engine is None
+    assert primed_plugin._session_maker is None
+
+
+async def test_session_maker_unavailable_after_shutdown(primed_plugin, app_for_plugin):
+    """After shutdown(), the session_maker getter falls back to the error branch."""
+
+    await primed_plugin.startup(app_for_plugin)
+    await primed_plugin.shutdown(app_for_plugin)
+
+    with pytest.raises(RuntimeError, match='session_maker is unavailable'):
+        _ = primed_plugin.session_maker