Refine dependencies approach

constraints

@@ -2,7 +2,7 @@
 #    uv --no-cache pip compile pyproject.toml -o constraints --all-extras
 bandit==1.7.10
     # via haiway (pyproject.toml)
-coverage==7.6.3
+coverage==7.6.4
     # via pytest-cov
 iniconfig==2.0.0
     # via pytest
@@ -20,7 +20,7 @@ pluggy==1.5.0
     # via pytest
 pygments==2.18.0
     # via rich
-pyright==1.1.384
+pyright==1.1.386
     # via haiway (pyproject.toml)
 pytest==7.4.4
     # via
@@ -33,7 +33,7 @@ pytest-cov==4.1.0
     # via haiway (pyproject.toml)
 pyyaml==6.0.2
     # via bandit
-rich==13.9.2
+rich==13.9.3
     # via bandit
 ruff==0.5.7
     # via haiway (pyproject.toml)

examples/fastAPI/src/features/todos/state.py

@@ -1,11 +1,11 @@
 from features.todos.types import TodoCompletion
 from features.todos.user_tasks import complete_todo_task
-from haiway import Structure
+from haiway import State
 
 __all__ = [
     "Todos",
 ]
 
 
-class Todos(Structure):
+class Todos(State):
     complete: TodoCompletion = complete_todo_task

examples/fastAPI/src/integrations/postgres/__init__.py

@@ -1,7 +1,10 @@
-from integrations.postgres.client import PostgresClient
-from integrations.postgres.types import PostgresClientException
+from integrations.postgres.asyncpg import PostgresSession
+from integrations.postgres.state import PostgresClient, PostgresConnection
+from integrations.postgres.types import PostgresException
 
 __all__ = [
     "PostgresClient",
-    "PostgresClientException",
+    "PostgresConnection",
+    "PostgresException",
+    "PostgresSession",
 ]

examples/fastAPI/src/integrations/postgres/asyncpg.py

@@ -0,0 +1,135 @@
+from types import TracebackType
+from typing import Any
+
+from asyncpg import (  # pyright: ignore[reportMissingTypeStubs]
+    Connection,
+    Pool,
+    create_pool,  # pyright: ignore [reportUnknownVariableType]
+)
+from asyncpg.pool import PoolAcquireContext  # pyright: ignore[reportMissingTypeStubs]
+from asyncpg.transaction import Transaction  # pyright: ignore[reportMissingTypeStubs]
+from haiway import ctx
+
+from integrations.postgres.state import (
+    PostgresConnection,
+    PostgresConnectionContext,
+    PostgresTransactionContext,
+)
+from integrations.postgres.types import PostgresException
+
+__all__ = [
+    "PostgresSession",
+]
+
+
+from integrations.postgres.config import (
+    POSTGRES_DATABASE,
+    POSTGRES_HOST,
+    POSTGRES_PASSWORD,
+    POSTGRES_PORT,
+    POSTGRES_SSLMODE,
+    POSTGRES_USER,
+)
+from integrations.postgres.state import PostgresClient
+
+__all__ = [
+    "PostgresSession",
+]
+
+
+class PostgresSession:
+    def __init__(  # noqa: PLR0913
+        self,
+        host: str = POSTGRES_HOST,
+        port: str = POSTGRES_PORT,
+        database: str = POSTGRES_DATABASE,
+        user: str = POSTGRES_USER,
+        password: str = POSTGRES_PASSWORD,
+        ssl: str = POSTGRES_SSLMODE,
+        connection_limit: int = 1,
+    ) -> None:
+        self._pool: Pool = create_pool(
+            min_size=1,
+            max_size=connection_limit,
+            database=database,
+            user=user,
+            password=password,
+            host=host,
+            port=port,
+            ssl=ssl,
+        )
+
+    def __del__(self) -> None:
+        if self._pool._initialized:  # pyright: ignore[reportPrivateUsage]
+            ctx.spawn(self._pool.close)
+
+    async def initialize(self) -> PostgresClient:
+        await self._pool  # initialize pool
+        return PostgresClient(connection=self.connection)
+
+    async def dispose(self) -> None:
+        if self._pool._initialized:  # pyright: ignore[reportPrivateUsage]
+            await self._pool.close()
+
+    def connection(self) -> PostgresConnectionContext:
+        acquire_context: PoolAcquireContext = self._pool.acquire()  # pyright: ignore[reportUnknownMemberType]
+
+        async def connection_acquire() -> PostgresConnection:
+            acquired_connection: Connection = await acquire_context.__aenter__()  # pyright: ignore[reportUnknownVariableType]
+
+            async def execute(
+                statement: str,
+                /,
+                *args: Any,
+            ) -> Any:
+                try:
+                    return await acquired_connection.execute(  # pyright: ignore[reportUnknownMemberType]
+                        statement,
+                        *args,
+                    )
+
+                except Exception as exc:
+                    raise PostgresException("Failed to execute SQL statement") from exc
+
+            def transaction() -> PostgresTransactionContext:
+                transaction_context: Transaction = acquired_connection.transaction()  # pyright: ignore[reportAssignmentType, reportUnknownMemberType]
+
+                async def transaction_enter() -> None:
+                    await transaction_context.__aenter__()
+
+                async def transaction_exit(
+                    exc_type: type[BaseException] | None,
+                    exc_val: BaseException | None,
+                    exc_tb: TracebackType | None,
+                ) -> None:
+                    await transaction_context.__aexit__(  # pyright: ignore[reportUnknownMemberType]
+                        exc_type,
+                        exc_val,
+                        exc_tb,
+                    )
+
+                return PostgresTransactionContext(
+                    enter_transaction=transaction_enter,
+                    exit_transaction=transaction_exit,
+                )
+
+            return PostgresConnection(
+                execute=execute,
+                transaction=transaction,
+            )
+
+        async def connection_release(
+            exc_type: type[BaseException] | None,
+            exc_val: BaseException | None,
+            exc_tb: TracebackType | None,
+        ) -> None:
+            await acquire_context.__aexit__(  # pyright: ignore[reportUnknownMemberType]
+                exc_type,
+                exc_val,
+                exc_tb,
+            )
+
+        return PostgresConnectionContext(
+            acquire_connection=connection_acquire,
+            release_connection=connection_release,
+        )