haiway 0.12.1__tar.gz → 0.13.0__tar.gz

{haiway-0.12.1 → haiway-0.13.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Miquido
+Copyright (c) 2024-2025 Miquido
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

{haiway-0.12.1 → haiway-0.13.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.12.1
+Version: 0.13.0
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git
 Maintainer-email: Kacper Kaliński <kacper.kalinski@miquido.com>
 License: MIT License
         
-        Copyright (c) 2024 Miquido
+        Copyright (c) 2024-2025 Miquido
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -40,12 +40,12 @@ Requires-Dist: pyright~=1.1; extra == 'dev'
 Requires-Dist: pytest-asyncio~=0.23; extra == 'dev'
 Requires-Dist: pytest-cov~=4.1; extra == 'dev'
 Requires-Dist: pytest~=7.4; extra == 'dev'
-Requires-Dist: ruff~=0.9; extra == 'dev'
+Requires-Dist: ruff~=0.11; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # 🚗 haiway 🚕 🚚 🚙
 
-haiway is a framework helping to build better project codebase by leveraging concepts of structured concurrency and functional programming.
+haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
 ## 🖥️ Install
 
@@ -65,7 +65,7 @@ We welcome any feedback and suggestions! Feel free to open an issue or pull requ
 
 MIT License
 
-Copyright (c) 2024 Miquido
+Copyright (c) 2024-2025 Miquido
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{haiway-0.12.1 → haiway-0.13.0}/README.md

@@ -1,6 +1,6 @@
 # 🚗 haiway 🚕 🚚 🚙
 
-haiway is a framework helping to build better project codebase by leveraging concepts of structured concurrency and functional programming.
+haiway is a framework designed to facilitate the development of applications using the functional programming paradigm combined with structured concurrency concepts. Unlike traditional object-oriented frameworks, haiway emphasizes immutability, pure functions, and context-based state management, enabling developers to build scalable and maintainable applications. By leveraging context managers combined with context vars, haiway ensures safe state propagation in concurrent environments and simplifies dependency injection through function implementation propagation.
 
 ## 🖥️ Install
 
@@ -20,7 +20,7 @@ We welcome any feedback and suggestions! Feel free to open an issue or pull requ
 
 MIT License
 
-Copyright (c) 2024 Miquido
+Copyright (c) 2024-2025 Miquido
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/Dockerfile

@@ -12,7 +12,7 @@ COPY ./src/features ./src/features
 COPY ./src/server ./src/server
 
 # install dependencies and packages
-COPY --from=ghcr.io/astral-sh/uv:0.5.14 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.6.8 /uv /uvx /bin/
 
 ENV UV_PROJECT_ENVIRONMENT="/usr/local/"
 
@@ -35,3 +35,29 @@ COPY ./config/unit.json /docker-entrypoint.d/config.json
 CMD ["unitd", "--no-daemon", "--log", "/dev/stdout"]
 
 # port 80 is already exposed by nginx unit image, can't change it...
+
+# MIGRATIONS #
+
+FROM python:${PYTHON_TAG} AS migrations_builder
+
+# copy only the parts needed for production
+COPY ./src/integrations ./src/integrations
+COPY ./src/solutions ./src/solutions
+COPY ./src/features ./src/features
+COPY ./src/migrations ./src/migrations
+# install dependencies and packages
+COPY --from=ghcr.io/astral-sh/uv:0.6.8 /uv /uvx /bin/
+
+ENV UV_PROJECT_ENVIRONMENT="/usr/local/"
+
+RUN --mount=type=bind,source=./uv.lock,target=./uv.lock --mount=type=bind,source=./pyproject.toml,target=./pyproject.toml uv sync --python python${PYTHON_TAG} --locked --no-editable --no-python-downloads --link-mode copy --compile-bytecode --only-group server
+
+FROM migrations_builder AS migrations
+
+RUN apt-get update \
+  && apt-get upgrade -y \
+  && apt-get -y autoremove \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+CMD ["python", "-m", "migrations"]

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/Makefile

@@ -12,7 +12,7 @@ ifndef UV_VERSION
 	UV_VERSION := 0.5.14
 endif
 
-.PHONY: uv_check venv sync update format lint run docker_run
+.PHONY: uv_check venv sync update format lint run migrations docker_run
 
 # Check installed UV version and install if needed
 uv_check:
@@ -81,6 +81,10 @@ lint:
 run:
 	@python -m server
 
-	# Run all services locally using docker-compose.
+# Execute migrations
+migrations:
+	@python -m migrations
+
+# Run all services locally using docker-compose.
 docker_run:
 	@docker compose up --force-recreate --build server

haiway-0.13.0/examples/fastAPI/README.md

@@ -0,0 +1,3 @@
+## Haiway FastAPI Example
+
+Example of FastAPI HTTP server using haiway architecture.

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/config/unit.json

@@ -19,19 +19,19 @@
           "uri": "/*"
         },
         "action": {
-          "pass": "applications/server"
+          "pass": "applications/api"
         }
       }
     ]
   },
   "applications": {
-    "server": {
+    "api": {
       "type": "python",
       "protocol": "asgi",
       "path": "/",
       "module": "server",
       "callable": "app",
-      "processes": 1,
+      "processes": 2,
       "environment": {
         "PYTHONOPTIMIZE": "2",
         "HOME": "."

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/docker-compose.yml

@@ -3,6 +3,8 @@ services:
     depends_on:
       postgres:
         condition: service_healthy
+      migrations:
+        condition: service_completed_successfully
     links:
       - postgres
     build:
@@ -22,6 +24,27 @@ services:
       POSTGRES_SSLMODE: ${POSTGRES_SSLMODE:-prefer}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
 
+  migrations:
+    depends_on:
+      postgres:
+        condition: service_healthy
+    links:
+      - postgres
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: migrations
+    restart: "no"
+    environment:
+      PYTHONOPTIMIZE: ${PYTHONOPTIMIZE:-2}
+      DEBUG_LOGGING: ${DEBUG_LOGGING}
+      POSTGRES_DATABASE: ${POSTGRES_DATABASE}
+      POSTGRES_HOST: postgres
+      POSTGRES_PORT: 5432
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_SSLMODE: ${POSTGRES_SSLMODE:-prefer}
+
   postgres:
     image: postgres:16.3-alpine3.20
     restart: always
@@ -34,7 +57,8 @@ services:
     ports:
       - ${POSTGRES_PORT}:5432
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DATABASE}"]
+      test:
+        ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DATABASE}"]
       interval: 10s
       start_period: 10s
       timeout: 10s

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/pyproject.toml

@@ -28,7 +28,7 @@ server = [
 dev = [
   "haiway_fastapi",
   "uvicorn~=0.30",
-  "ruff~=0.8.0",
+  "ruff~=0.11",
   "pyright~=1.1",
   "bandit~=1.7",
 ]
@@ -53,13 +53,10 @@ exclude = ["**/node_modules", "**/__pycache__"]
 ignore = []
 stubPath = "./stubs"
 reportMissingImports = true
-reportMissingTypeStubs = true
-typeCheckingMode = "strict"
+reportMissingTypeStubs = false
 userFileIndexingLimit = -1
 useLibraryCodeForTypes = true
 
-[tool.setuptools]
-include-package-data = true
-
-[tool.setuptools.packages.find]
-where = ["src"]
+[tool.pyright.analysis]
+diagnosticMode = "workspace"
+typeCheckingMode = "strict"

haiway-0.13.0/examples/fastAPI/src/features/todos/__init__.py

@@ -0,0 +1,5 @@
+from features.todos.state import Todos
+
+__all__ = [
+    "Todos",
+]

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/src/features/todos/state.py

@@ -1,4 +1,7 @@
+from uuid import UUID
+
 from haiway import State
+from haiway.context import ctx
 
 from features.todos.types import TodoCompletion
 from features.todos.user_tasks import complete_todo_task
@@ -9,4 +12,12 @@ __all__ = [
 
 
 class Todos(State):
+    @classmethod
+    async def complete_todo(
+        cls,
+        *,
+        identifier: UUID,
+    ) -> None:
+        await ctx.state(cls).complete(identifier=identifier)
+
     complete: TodoCompletion = complete_todo_task

haiway-0.13.0/examples/fastAPI/src/features/todos/user_tasks.py

@@ -0,0 +1,19 @@
+from uuid import UUID
+
+from solutions.user_tasks import UserTasks
+
+__all__ = [
+    "complete_todo_task",
+]
+
+
+async def complete_todo_task(
+    *,
+    identifier: UUID,
+) -> None:
+    match await UserTasks.fetch(identifier=identifier):
+        case None:
+            pass
+
+        case task:
+            await UserTasks.update(task=task.updated(completed=True))

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/src/integrations/postgres/__init__.py

@@ -1,11 +1,11 @@
-from integrations.postgres.client import PostgresClient
+from integrations.postgres.client import PostgresConnectionPool
 from integrations.postgres.state import Postgres, PostgresConnection
 from integrations.postgres.types import PostgresException, PostgresRow, PostgresValue
 
 __all__ = [
     "Postgres",
-    "PostgresClient",
     "PostgresConnection",
+    "PostgresConnectionPool",
     "PostgresException",
     "PostgresRow",
     "PostgresValue",

{haiway-0.12.1 → haiway-0.13.0}/examples/fastAPI/src/integrations/postgres/client.py

@@ -1,3 +1,4 @@
+from collections.abc import Sequence
 from types import TracebackType
 from typing import final
 
@@ -9,18 +10,6 @@ from asyncpg import (  # pyright: ignore[reportMissingTypeStubs]
 from asyncpg.pool import PoolAcquireContext  # pyright: ignore[reportMissingTypeStubs]
 from asyncpg.transaction import Transaction  # pyright: ignore[reportMissingTypeStubs]
 
-from integrations.postgres.state import (
-    PostgresConnection,
-    PostgresConnectionContext,
-    PostgresTransactionContext,
-)
-from integrations.postgres.types import PostgresException, PostgresRow, PostgresValue
-
-__all__ = [
-    "PostgresClient",
-]
-
-
 from integrations.postgres.config import (
     POSTGRES_DATABASE,
     POSTGRES_HOST,
@@ -29,15 +18,36 @@ from integrations.postgres.config import (
     POSTGRES_SSLMODE,
     POSTGRES_USER,
 )
-from integrations.postgres.state import Postgres
+from integrations.postgres.state import (
+    Postgres,
+    PostgresConnection,
+    PostgresConnectionContext,
+    PostgresTransactionContext,
+)
+from integrations.postgres.types import (
+    PostgresException,
+    PostgresRow,
+    PostgresValue,
+)
 
 __all__ = [
-    "PostgresClient",
+    "PostgresConnectionPool",
 ]
 
 
 @final
-class PostgresClient:
+class PostgresConnectionPool:
+    __slots__ = (
+        "_connection_limit",
+        "_database",
+        "_host",
+        "_password",
+        "_pool",
+        "_port",
+        "_ssl",
+        "_user",
+    )
+
     def __init__(  # noqa: PLR0913
         self,
         host: str = POSTGRES_HOST,
@@ -48,20 +58,28 @@ class PostgresClient:
         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,
-        )
+        self._host: str = host
+        self._port: str = port
+        self._database: str = database
+        self._user: str = user
+        self._password: str = password
+        self._ssl: str = ssl
+        self._connection_limit: int = connection_limit
+        self._pool: Pool
 
     async def __aenter__(self) -> Postgres:
+        self._pool = create_pool(
+            min_size=1,
+            max_size=self._connection_limit,
+            database=self._database,
+            user=self._user,
+            password=self._password,
+            host=self._host,
+            port=self._port,
+            ssl=self._ssl,
+        )
         await self._pool  # initialize pool
-        return Postgres(connection=self.connection)
+        return Postgres(prepare_connection=self.prepare_connection)
 
     async def __aexit__(
         self,
@@ -72,12 +90,14 @@ class PostgresClient:
         if self._pool._initialized:  # pyright: ignore[reportPrivateUsage]
             await self._pool.close()
 
-    def connection(self) -> PostgresConnectionContext:
+    def prepare_connection(self) -> PostgresConnectionContext:
         return _ConnectionContext(pool_context=self._pool.acquire())  # pyright: ignore[reportUnknownMemberType]
 
 
 @final
 class _TransactionContext:
+    __slots__ = ("_transaction_context",)
+
     def __init__(
         self,
         transaction_context: Transaction,
@@ -102,6 +122,8 @@ class _TransactionContext:
 
 @final
 class _ConnectionContext:
+    __slots__ = ("_pool_context",)
+
     def __init__(
         self,
         pool_context: PoolAcquireContext,
@@ -115,12 +137,15 @@ class _ConnectionContext:
             statement: str,
             /,
             *args: PostgresValue,
-        ) -> list[PostgresRow]:
+        ) -> Sequence[PostgresRow]:
             try:
-                return await acquired_connection.fetch(  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-                    statement,
-                    *args,
-                )
+                return [
+                    dict(record)  # convert to dict to allow match patterns
+                    for record in await acquired_connection.fetch(  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+                        statement,
+                        *args,
+                    )
+                ]
 
             except Exception as exc:
                 raise PostgresException("Failed to execute SQL statement") from exc
@@ -129,8 +154,8 @@ class _ConnectionContext:
             return _TransactionContext(transaction_context=acquired_connection.transaction())  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
 
         return PostgresConnection(
-            execute=execute,
-            transaction=transaction,
+            execute_statement=execute,
+            prepare_transaction=transaction,
         )
 
     async def __aexit__(

haiway-0.13.0/examples/fastAPI/src/integrations/postgres/state.py

@@ -0,0 +1,77 @@
+from collections.abc import Sequence
+from typing import Any
+
+from haiway import State, ctx
+
+from integrations.postgres.types import (
+    PostgresConnectionContext,
+    PostgresConnectionPreparing,
+    PostgresRow,
+    PostgresStatementExecuting,
+    PostgresTransactionContext,
+    PostgresTransactionPreparing,
+)
+
+__all__ = [
+    "Postgres",
+    "PostgresConnection",
+]
+
+
+class PostgresConnection(State):
+    execute_statement: PostgresStatementExecuting
+    prepare_transaction: PostgresTransactionPreparing
+
+    @classmethod
+    async def fetch_one(
+        cls,
+        statement: str,
+        /,
+        *args: Any,
+    ) -> PostgresRow | None:
+        return next(
+            (
+                result
+                for result in await ctx.state(cls).execute_statement(
+                    statement,
+                    *args,
+                )
+            ),
+            None,
+        )
+
+    @classmethod
+    async def fetch(
+        cls,
+        statement: str,
+        /,
+        *args: Any,
+    ) -> Sequence[PostgresRow]:
+        return await ctx.state(cls).execute_statement(
+            statement,
+            *args,
+        )
+
+    @classmethod
+    async def execute(
+        cls,
+        statement: str,
+        /,
+        *args: Any,
+    ) -> None:
+        await ctx.state(cls).execute_statement(
+            statement,
+            *args,
+        )
+
+    @classmethod
+    def transaction(cls) -> PostgresTransactionContext:
+        return ctx.state(cls).prepare_transaction()
+
+
+class Postgres(State):
+    @classmethod
+    def connection(cls) -> PostgresConnectionContext:
+        return ctx.state(cls).prepare_connection()
+
+    prepare_connection: PostgresConnectionPreparing

haiway-0.13.0/examples/fastAPI/src/integrations/postgres/types.py

@@ -0,0 +1,69 @@
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime, time
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+from uuid import UUID
+
+if TYPE_CHECKING:
+    from integrations.postgres.state import PostgresConnection
+
+__all__ = [
+    "PostgresConnectionContext",
+    "PostgresConnectionPreparing",
+    "PostgresException",
+    "PostgresStatementExecuting",
+    "PostgresTransactionContext",
+    "PostgresTransactionPreparing",
+    "PostgresValue",
+]
+
+type PostgresValue = UUID | datetime | date | time | str | bytes | float | int | bool | None
+type PostgresRow = Mapping[str, Any]
+
+
+@runtime_checkable
+class PostgresStatementExecuting(Protocol):
+    async def __call__(
+        self,
+        statement: str,
+        /,
+        *args: PostgresValue,
+    ) -> Sequence[PostgresRow]: ...
+
+
+@runtime_checkable
+class PostgresTransactionContext(Protocol):
+    async def __aenter__(self) -> None: ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None: ...
+
+
+@runtime_checkable
+class PostgresTransactionPreparing(Protocol):
+    def __call__(self) -> PostgresTransactionContext: ...
+
+
+@runtime_checkable
+class PostgresConnectionContext(Protocol):
+    async def __aenter__(self) -> "PostgresConnection": ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None: ...
+
+
+@runtime_checkable
+class PostgresConnectionPreparing(Protocol):
+    def __call__(self) -> PostgresConnectionContext: ...
+
+
+class PostgresException(Exception):
+    pass

haiway-0.13.0/examples/fastAPI/src/migrations/__init__.py

@@ -0,0 +1,3 @@
+from haiway import load_env
+
+load_env()

haiway-0.13.0/examples/fastAPI/src/migrations/__main__.py

@@ -0,0 +1,26 @@
+from asyncio import run
+
+from haiway import ctx, setup_logging
+
+from integrations.postgres import PostgresConnectionPool
+from migrations.postgres import execute_postgres_migrations
+
+
+async def migrate_databases() -> None:
+    async with ctx.scope(
+        "migrations",
+        disposables=[
+            PostgresConnectionPool(),
+        ],
+    ):
+        ctx.log_warning("Running postgres migrations...")
+        await execute_postgres_migrations()
+        ctx.log_info("...postgres migrations completed")
+
+
+def main() -> None:
+    setup_logging("migrations")
+    run(migrate_databases())
+
+
+main()

haiway-0.13.0/examples/fastAPI/src/migrations/postgres/__init__.py

@@ -0,0 +1,5 @@
+from migrations.postgres.execution import execute_postgres_migrations
+
+__all__ = [
+    "execute_postgres_migrations",
+]