databasic 0.1.0__tar.gz

databasic-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: databasic
+Version: 0.1.0
+Summary: Database connection helper
+Author: ansipunk
+Author-email: ansipunk <ansipunk@proton.me>
+License-Expression: MIT
+Requires-Dist: psycopg[binary,pool]>=3,<4
+Requires-Dist: sqlalchemy>=2,<2.2
+Requires-Python: >=3.11, <3.16
+Description-Content-Type: text/markdown
+
+# Databasic
+
+A small async database interface built on SQLAlchemy Core and psycopg.
+
+SQLAlchemy Core handles query construction and compilation. Databasic handles
+connection and transaction lifetimes and executes the resulting queries directly
+through psycopg.
+
+## Usage
+
+```python
+import sqlalchemy as sa
+
+from databasic import Databasic
+
+
+users = sa.Table(
+    "users",
+    sa.MetaData(),
+    sa.Column("id", sa.Integer, primary_key=True),
+    sa.Column("name", sa.Text, nullable=False),
+)
+
+db = Databasic("postgresql://user:password@localhost/database")
+
+async with db:
+    async with db.session() as session:
+        rows = await session.fetch_all(
+            users.select().where(users.c.name == "Alice")
+        )
+```
+
+`Databasic` can also be connected and disconnected explicitly. Both forms have
+the same semantics; explicit lifecycle management is useful when the lifetime is
+controlled by an application or framework.
+
+```python
+db = Databasic("postgresql://user:password@localhost/database")
+
+await db.connect()
+
+try:
+    async with db.session() as session:
+        rows = await session.fetch_all(users.select())
+finally:
+    await db.disconnect()
+```
+
+A session is a transaction. It commits when the context exits successfully and
+rolls back when it exits with an exception.
+
+## API
+
+### `Databasic`
+
+```python
+db = Databasic(conninfo, force_rollback=False)
+```
+
+#### `connect()`
+
+Open the connection pool.
+
+```python
+await db.connect()
+```
+
+#### `disconnect()`
+
+Close the connection pool.
+
+```python
+await db.disconnect()
+```
+
+#### `session()`
+
+Create a transactional session.
+
+```python
+async with db.session() as session:
+    ...
+```
+
+Successful exit commits the transaction. An exception rolls it back.
+
+### `Session`
+
+#### `execute()`
+
+Execute a statement without returning rows.
+
+```python
+await session.execute(
+    users.insert().values(name="Alice")
+)
+```
+
+#### `execute_many()`
+
+Execute the same statement multiple times with different parameters.
+
+```python
+query = users.insert().values(
+    name=sa.bindparam("name"),
+)
+
+await session.execute_many(
+    query,
+    [
+        {"name": "Alice"},
+        {"name": "Bob"},
+    ],
+)
+```
+
+The statement must define its values using explicit bind parameters. Values are
+supplied exclusively through the parameter mappings.
+
+#### `fetch_one()`
+
+Execute a statement and return one row, or `None` if there is no row.
+
+```python
+user = await session.fetch_one(
+    users.select().where(users.c.id == 1)
+)
+```
+
+A row is simply a `dict[str, Any]`:
+
+```python
+{"id": 1, "name": "Alice"}
+```
+
+There is no result or row wrapper.
+
+#### `fetch_all()`
+
+Execute a statement and return all rows as a list of dictionaries.
+
+```python
+users = await session.fetch_all(
+    users.select()
+)
+```
+
+The result has the shape:
+
+```python
+[
+    {"id": 1, "name": "Alice"},
+    {"id": 2, "name": "Bob"},
+]
+```
+
+#### `transaction()`
+
+Create a nested transaction within the current session.
+
+```python
+async with db.session() as session:
+    await session.execute(
+        users.insert().values(name="Alice")
+    )
+
+    async with session.transaction():
+        await session.execute(
+            users.insert().values(name="Bob")
+        )
+```
+
+Nested transactions use database savepoints. An exception rolls back the nested
+transaction without rolling back earlier work in the session.
+
+## Testing
+
+`force_rollback=True` runs all sessions within an outer transaction that is
+rolled back when Databasic is disconnected.
+
+```python
+async with Databasic(
+    "postgresql://user:password@localhost/test_database",
+    force_rollback=True,
+) as db:
+    ...
+```
+
+This allows integration tests to use normal sessions and transactions without
+leaving persistent database state.

databasic-0.1.0/README.md

@@ -0,0 +1,190 @@
+# Databasic
+
+A small async database interface built on SQLAlchemy Core and psycopg.
+
+SQLAlchemy Core handles query construction and compilation. Databasic handles
+connection and transaction lifetimes and executes the resulting queries directly
+through psycopg.
+
+## Usage
+
+```python
+import sqlalchemy as sa
+
+from databasic import Databasic
+
+
+users = sa.Table(
+    "users",
+    sa.MetaData(),
+    sa.Column("id", sa.Integer, primary_key=True),
+    sa.Column("name", sa.Text, nullable=False),
+)
+
+db = Databasic("postgresql://user:password@localhost/database")
+
+async with db:
+    async with db.session() as session:
+        rows = await session.fetch_all(
+            users.select().where(users.c.name == "Alice")
+        )
+```
+
+`Databasic` can also be connected and disconnected explicitly. Both forms have
+the same semantics; explicit lifecycle management is useful when the lifetime is
+controlled by an application or framework.
+
+```python
+db = Databasic("postgresql://user:password@localhost/database")
+
+await db.connect()
+
+try:
+    async with db.session() as session:
+        rows = await session.fetch_all(users.select())
+finally:
+    await db.disconnect()
+```
+
+A session is a transaction. It commits when the context exits successfully and
+rolls back when it exits with an exception.
+
+## API
+
+### `Databasic`
+
+```python
+db = Databasic(conninfo, force_rollback=False)
+```
+
+#### `connect()`
+
+Open the connection pool.
+
+```python
+await db.connect()
+```
+
+#### `disconnect()`
+
+Close the connection pool.
+
+```python
+await db.disconnect()
+```
+
+#### `session()`
+
+Create a transactional session.
+
+```python
+async with db.session() as session:
+    ...
+```
+
+Successful exit commits the transaction. An exception rolls it back.
+
+### `Session`
+
+#### `execute()`
+
+Execute a statement without returning rows.
+
+```python
+await session.execute(
+    users.insert().values(name="Alice")
+)
+```
+
+#### `execute_many()`
+
+Execute the same statement multiple times with different parameters.
+
+```python
+query = users.insert().values(
+    name=sa.bindparam("name"),
+)
+
+await session.execute_many(
+    query,
+    [
+        {"name": "Alice"},
+        {"name": "Bob"},
+    ],
+)
+```
+
+The statement must define its values using explicit bind parameters. Values are
+supplied exclusively through the parameter mappings.
+
+#### `fetch_one()`
+
+Execute a statement and return one row, or `None` if there is no row.
+
+```python
+user = await session.fetch_one(
+    users.select().where(users.c.id == 1)
+)
+```
+
+A row is simply a `dict[str, Any]`:
+
+```python
+{"id": 1, "name": "Alice"}
+```
+
+There is no result or row wrapper.
+
+#### `fetch_all()`
+
+Execute a statement and return all rows as a list of dictionaries.
+
+```python
+users = await session.fetch_all(
+    users.select()
+)
+```
+
+The result has the shape:
+
+```python
+[
+    {"id": 1, "name": "Alice"},
+    {"id": 2, "name": "Bob"},
+]
+```
+
+#### `transaction()`
+
+Create a nested transaction within the current session.
+
+```python
+async with db.session() as session:
+    await session.execute(
+        users.insert().values(name="Alice")
+    )
+
+    async with session.transaction():
+        await session.execute(
+            users.insert().values(name="Bob")
+        )
+```
+
+Nested transactions use database savepoints. An exception rolls back the nested
+transaction without rolling back earlier work in the session.
+
+## Testing
+
+`force_rollback=True` runs all sessions within an outer transaction that is
+rolled back when Databasic is disconnected.
+
+```python
+async with Databasic(
+    "postgresql://user:password@localhost/test_database",
+    force_rollback=True,
+) as db:
+    ...
+```
+
+This allows integration tests to use normal sessions and transactions without
+leaving persistent database state.

databasic-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "databasic"
+version = "0.1.0"
+description = "Database connection helper"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11,<3.16"
+dependencies = [
+    "psycopg[binary,pool]>=3,<4",
+    "sqlalchemy>=2,<2.2",
+]
+
+[[project.authors]]
+name = "ansipunk"
+email = "ansipunk@proton.me"
+
+[build-system]
+requires = ["uv_build>=0.12.17,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9,<10",
+    "pytest-asyncio>=1,<2",
+    "pytest-cov>=7,<8",
+    "ruff>=0.16.10",
+    "ty>=0.0.84",
+]
+
+[tool.pytest]
+addopts = [
+    "--cov",
+    "databasic",
+    "--cov-report",
+    "term-missing",
+    "--cov-report",
+    "html",
+    "--cov-fail-under",
+    "100",
+]
+testpaths = ["tests"]

databasic-0.1.0/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "databasic"
+version = "0.1.0"
+description = "Database connection helper"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "ansipunk", email = "ansipunk@proton.me" }
+]
+requires-python = ">=3.11,<3.16"
+dependencies = [
+    "psycopg[binary,pool]>=3,<4",
+    "sqlalchemy>=2,<2.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.17,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9,<10",
+    "pytest-asyncio>=1,<2",
+    "pytest-cov>=7,<8",
+    "ruff>=0.16.10",
+    "ty>=0.0.84",
+]
+
+[tool.pytest]
+addopts = [
+    "--cov", "databasic",
+    "--cov-report", "term-missing",
+    "--cov-report", "html",
+    "--cov-fail-under", "100",
+]
+testpaths = [
+    "tests",
+]

databasic-0.1.0/src/databasic/__init__.py

@@ -0,0 +1,198 @@
+from collections.abc import AsyncIterator, Callable, Iterable, Mapping, Sequence
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any, LiteralString, Self, cast
+
+from psycopg import AsyncConnection as BaseAsyncConnection
+from psycopg import AsyncCursor as BaseAsyncCursor
+from psycopg import AsyncTransaction
+from psycopg_pool import AsyncConnectionPool as BaseAsyncConnectionPool
+from sqlalchemy.dialects import postgresql
+from sqlalchemy.sql.elements import ClauseElement
+
+__all__ = [
+    "DatabaseAlreadyConnectedError",
+    "DatabaseNotConnectedError",
+    "Databasic",
+    "DatabasicError",
+    "Row",
+    "Session",
+]
+
+Row = dict[str, Any]
+AsyncConnection = BaseAsyncConnection[Row]
+AsyncConnectionPool = BaseAsyncConnectionPool[AsyncConnection]
+AsyncCursor = BaseAsyncCursor[Row]
+
+
+class Databasic:
+    _pool: AsyncConnectionPool
+    _conn: AsyncConnection | None = None
+    _global_transaction: AsyncTransaction | None = None
+    _force_rollback: bool = False
+
+    def __init__(self, conninfo: str, *, force_rollback: bool = False):
+        self._pool = AsyncConnectionPool(
+            conninfo,
+            open=False,
+            kwargs={"row_factory": _dict_row_factory},
+        )
+        self._force_rollback = force_rollback
+
+    async def __aenter__(self) -> Self:
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        _ = exc_type, exc_value, traceback
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        if not self._pool.closed:
+            raise DatabaseAlreadyConnectedError
+
+        await self._pool.open(wait=True)
+
+        if self._force_rollback:
+            try:
+                self._conn = await self._pool.getconn()
+            except BaseException:  # pragma: no cover
+                await self.disconnect()
+                raise
+
+            self._global_transaction = AsyncTransaction(
+                self._conn,
+                force_rollback=True,
+            )
+
+            try:
+                await self._global_transaction.__aenter__()
+            except BaseException:  # pragma: no cover
+                await self.disconnect()
+                raise
+
+    async def disconnect(self) -> None:
+        if self._pool.closed:
+            raise DatabaseNotConnectedError
+
+        if self._conn is not None:
+            if self._global_transaction is not None:
+                await self._global_transaction.__aexit__(None, None, None)
+                self._global_transaction = None
+
+            await self._pool.putconn(self._conn)
+            self._conn = None
+
+        await self._pool.close()
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator["Session"]:
+        if self._pool.closed:
+            raise DatabaseNotConnectedError
+
+        if self._conn is not None:
+            async with self._conn.transaction():
+                yield Session(self._conn)
+        else:
+            async with self._pool.connection() as conn:  # noqa: SIM117
+                async with conn.transaction():
+                    yield Session(conn)
+
+
+class Session:
+    _conn: AsyncConnection
+
+    def __init__(self, conn: AsyncConnection):
+        self._conn = conn
+
+    async def fetch_one(self, query: ClauseElement) -> Row | None:
+        async with self._execute(query) as cursor:
+            return await cursor.fetchone()
+
+    async def fetch_all(self, query: ClauseElement) -> list[Row]:
+        async with self._execute(query) as cursor:
+            return await cursor.fetchall()
+
+    async def execute(self, query: ClauseElement) -> int:
+        async with self._execute(query) as cursor:
+            return cursor.rowcount
+
+    async def execute_many(
+        self,
+        query: ClauseElement,
+        params: Iterable[Mapping[str, Any]],
+    ) -> int:
+        """Execute a query multiple times with different parameters.
+
+        The query must define all values as explicit bind parameters. Values
+        must be provided exclusively through `params`, not embedded in the
+        SQLAlchemy query itself.
+
+        Usage would roughly be like:
+
+            query = sa.insert(table).values(
+                val_a=sa.bindparam("val_a"),
+                val_b=sa.bindparam("val_b"),
+            )
+
+            await session.execute_many(
+                query,
+                [
+                    {"val_a": 1, "val_b": 2},
+                    {"val_a": 3, "val_b": 4},
+                ],
+            )
+        """
+
+        compiled_query, _ = _compile_query(query)
+
+        async with self._conn.cursor() as cursor:
+            await cursor.executemany(compiled_query, params)
+            return cursor.rowcount
+
+    @asynccontextmanager
+    async def _execute(self, statement: ClauseElement) -> AsyncIterator[AsyncCursor]:
+        query, params = _compile_query(statement)
+
+        async with self._conn.cursor() as cursor:
+            await cursor.execute(query, params)
+            yield cursor
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[None]:
+        async with self._conn.transaction():
+            yield
+
+
+class DatabasicError(Exception):
+    pass
+
+
+class DatabaseAlreadyConnectedError(DatabasicError):
+    pass
+
+
+class DatabaseNotConnectedError(DatabasicError):
+    pass
+
+
+def _dict_row_factory(cursor: AsyncCursor) -> Callable[[Sequence[Any]], Row]:
+    fields = [c.name for c in cursor.description or ()]
+
+    def make_row(values: Sequence[Any]) -> Row:
+        return dict(zip(fields, values))
+
+    return make_row
+
+
+def _compile_query(statement: ClauseElement) -> tuple[LiteralString, dict[str, Any]]:
+    compiled = statement.compile(
+        dialect=postgresql.dialect(paramstyle="pyformat"),
+        compile_kwargs={"render_postcompile": True},
+    )
+    return cast(LiteralString, compiled.string), compiled.params