scaffold-framework 0.1.0__tar.gz

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

@@ -0,0 +1,64 @@
+name: CI/CD
+
+on:
+  push:
+    branches:
+      - "**"
+    tags:
+      - "v*.*.*"
+
+jobs:
+  qa:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Run mypy
+        run: uv run mypy .
+
+      - name: Run ruff
+        run: uv run ruff check
+
+      - name: Run tests
+        run: uv run pytest
+
+  publish:
+    needs: qa
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: 
+      name: pypi
+      url: https://pypi.org/p/scaffold-framework
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scaffold_framework-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

scaffold_framework-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.2
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [ --fix ]
+  # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.2.0
+    hooks:
+      - id: black
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy

scaffold_framework-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

scaffold_framework-0.1.0/.vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.debugpy",
+        "ms-python.vscode-pylance",
+        "ms-python.mypy-type-checker",
+        "ms-python.black-formatter",
+        "charliermarsh.ruff"
+    ]
+}

scaffold_framework-0.1.0/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    // "python.defaultInterpreterPath": "/venv/bin/python",
+    "editor.formatOnSave": true,
+    // "python.testing.pytestEnabled": true,
+    "mypy-type-checker.importStrategy": "fromEnvironment",
+    "mypy-type-checker.reportingScope": "workspace",
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter",
+        "editor.formatOnSave": true
+    }
+}

scaffold_framework-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: scaffold-framework
+Version: 0.1.0
+Summary: A web framework that make it easy to build apps according to SOLID & DDD principles and with layered/onion architecture.
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.13.3
+Requires-Dist: h11>=0.14.0
+Requires-Dist: psycopg[binary,pool]>=3.2.3
+Requires-Dist: pydantic>=2.9.2
+Requires-Dist: quart>=0.19.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0.35
+Requires-Dist: watchfiles>=0.24.0
+Requires-Dist: wsproto>=1.2.0
+Requires-Dist: wtforms>=3.1.2
+Description-Content-Type: text/markdown
+
+# Scaffold

scaffold_framework-0.1.0/README.md

@@ -0,0 +1 @@
+# Scaffold

scaffold_framework-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "scaffold-framework"
+description = "A web framework that make it easy to build apps according to SOLID & DDD principles and with layered/onion architecture."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "alembic>=1.13.3",
+    "h11>=0.14.0",
+    "psycopg[binary,pool]>=3.2.3",
+    "pydantic>=2.9.2",
+    "quart>=0.19.9",
+    "sqlalchemy[asyncio]>=2.0.35",
+    "watchfiles>=0.24.0",
+    "wsproto>=1.2.0",
+    "wtforms>=3.1.2",
+]
+dynamic = ["version"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs", "hatch-fancy-pypi-readme"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scaffold"]
+
+[dependency-groups]
+dev = ["mypy>=1.13.0", "pytest-asyncio>=0.24.0", "pytest>=8.3.3", "ruff>=0.8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib"]
+
+[tool.mypy]
+disable_error_code = "import-untyped"
+enable_error_code = "explicit-override"
+disallow_untyped_defs = true
+# disallow_any_generics = true
+warn_unreachable = true
+
+[tool.black]
+line-length = 120
+unstable = true
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "ANN",
+    "ASYNC",
+    "S",
+    "BLE",
+    "B",
+    "A",
+    "COM",
+    "C4",
+    "T10",
+    "EM",
+    "RET",
+    "SLF",
+    "I",
+    "UP",
+]
+extend-ignore = ["A002", "ANN101", "ANN102", "B010", "S101"]

scaffold_framework-0.1.0/src/scaffold/cli/__init__.py

@@ -0,0 +1,8 @@
+from .base_app import BaseCLIApp
+from .decorators import argument, command
+
+__all__ = [
+    "BaseCLIApp",
+    "argument",
+    "command",
+]

scaffold_framework-0.1.0/src/scaffold/cli/base_app.py

@@ -0,0 +1,37 @@
+import argparse
+import asyncio
+
+from .decorators import Command
+
+
+class BaseCLIApp:
+    def __init__(self) -> None:
+        self.parser = argparse.ArgumentParser()
+        self.subparsers = self.parser.add_subparsers()
+        self._register_commands()
+
+    def _register_commands(self) -> None:
+        for attr_name in dir(self):
+            attr = getattr(self, attr_name)
+            if isinstance(attr, Command):
+                subparser = self.subparsers.add_parser(
+                    attr.command_name,
+                    help=attr.command_help,
+                )
+                for args, kwargs in attr.arguments:
+                    subparser.add_argument(*args, **kwargs)
+                subparser.set_defaults(func=attr)
+
+    def run(self) -> None:
+        args = self.parser.parse_args()
+
+        if hasattr(args, "func"):
+            kwargs = dict(vars(args))
+            del kwargs["func"]
+            result = args.func(self, **kwargs)
+
+            if asyncio.iscoroutine(result):
+                asyncio.run(result)
+
+        else:
+            self.parser.print_help()

scaffold_framework-0.1.0/src/scaffold/cli/decorators.py

@@ -0,0 +1,47 @@
+from collections.abc import Callable
+from typing import Any
+
+
+class Command:
+    def __init__(
+        self,
+        func: Callable,
+        name: str = "",
+        description: str = "",
+    ) -> None:
+        self.func = func
+        self.command_name = name
+        self.command_help = description
+        self.arguments: list[tuple[tuple[str, ...], dict[str, Any]]] = []
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+        return self.func(*args, **kwargs)
+
+
+def command(
+    name: str,
+    description: str = "",
+) -> Callable[[Callable | Command], Command]:
+    def decorator(f: Callable | Command) -> Command:
+        if isinstance(f, Command):
+            f.command_name = name
+            f.command_help = description
+            return f
+
+        return Command(f, name, description)
+
+    return decorator
+
+
+def argument(
+    *args: Any,  # noqa: ANN401
+    **kwargs: Any,  # noqa: ANN401
+) -> Callable[[Callable | Command], Command]:
+    def decorator(f: Callable | Command) -> Command:
+        if not isinstance(f, Command):
+            f = Command(f)
+
+        f.arguments.append((args, kwargs))
+        return f
+
+    return decorator

scaffold_framework-0.1.0/src/scaffold/di.py

@@ -0,0 +1,81 @@
+"""
+An extremely simple DI container (in <100 lines of code) with auto-wiring based on type hints.
+"""
+
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import Self, cast
+
+# Since `type` does not accept abstract classes, we have to use `Callable` as well (although it's not ideal), see https://github.com/python/mypy/issues/4717
+type Dependency[T] = type[T] | Callable[..., T]
+type Provider[T] = type[T] | Callable[["Container"], T]
+
+
+class Container:
+    def __init__(self) -> None:
+        self.providers: dict[Dependency, Provider] = {}
+        self.singletons: dict[Dependency, object] = {}
+        self.init_functions: list[Callable] = []
+
+    def add_singleton[T](self, cls: Dependency[T], provider: Provider[T]) -> None:
+        self.providers[cls] = provider
+        self.singletons[cls] = None
+
+    def add_transient[T](self, cls: Dependency[T], provider: Provider[T]) -> None:
+        self.providers[cls] = provider
+
+    def add_init_function(
+        self,
+        init_function: Callable[[Self], Awaitable[None]],
+    ) -> None:
+        self.init_functions.append(init_function)
+
+    async def init(self) -> None:
+        for init_function in self.init_functions:
+            await init_function(self)
+
+    def resolve[T](self, cls: Dependency[T]) -> T:
+        instance: T
+
+        if cls in self.providers:
+            provider = self.providers[cls]
+
+            if cls in self.singletons and self.singletons[cls] is not None:
+                return cast(T, self.singletons[cls])
+
+            if isinstance(provider, type):
+                instance = self._instantiate(provider)
+
+            else:
+                instance = provider(self)
+
+            if cls in self.singletons:
+                self.singletons[cls] = instance
+
+            return instance
+
+        if isinstance(cls, type):
+            return self._instantiate(cls)
+
+        raise RuntimeError
+
+    def _instantiate[T](self, cls: type[T]) -> T:
+        constructor_signature = inspect.signature(cls.__init__)
+        dependencies = {}
+
+        for name, param in constructor_signature.parameters.items():
+            # TODO is there a better way to ignore the "self" param?
+            if name == "self" or param.annotation == inspect.Parameter.empty:
+                continue  # Skip parameters that are not type-annotated or are 'self'
+            dependencies[name] = self[param.annotation]
+
+        return cls(**dependencies)
+
+    def __getitem__[T](self, cls: Dependency[T]) -> T:
+        return self.resolve(cls)
+
+    def get_factory[C](self, cls: Dependency[C]) -> Callable[[], C]:
+        def factory() -> C:
+            return self[cls]
+
+        return factory

scaffold_framework-0.1.0/src/scaffold/persistence.py

@@ -0,0 +1,109 @@
+import abc
+from collections.abc import Sequence
+from types import TracebackType, get_original_bases
+from typing import Protocol, final, get_args, override
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class EntityId(Protocol):
+    @property
+    def value(self) -> object: ...
+
+
+class Entity(Protocol):
+    @property
+    def id(self) -> EntityId: ...
+
+
+class GenericSqlRepository[E: Entity, ID: EntityId, DTO](abc.ABC):
+    dto_class: type[DTO]
+
+    @override
+    def __init_subclass__(cls) -> None:
+        # TODO Check that the runtime type of the ID type param is the same as the type hint of E.id.
+        # Ideally, we would like to do something like `GenericSqlRepository[ID: EntityId, E: Entity[ID], DTO](abc.ABC)`
+        # to check it statically but that's currently not possible.
+
+        cls.dto_class = get_args(get_original_bases(cls)[0])[2]
+
+        return super().__init_subclass__()
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+        self._identity_map: dict[EntityId, E] = {}
+
+    async def get(self, entity_id: ID) -> E | None:
+        if entity_id in self._identity_map:
+            return self._identity_map[entity_id]
+
+        dto = await self._session.get(self.dto_class, entity_id.value)
+
+        if dto is not None:
+            return self.map_dto_to_entity_and_track(dto)
+
+        return None
+
+    def add(self, entity: E) -> None:
+        dto = self._map_entity_to_dto(entity)
+        self._session.add(dto)
+        self._track(entity)
+
+    async def remove(self, entity: E) -> None:
+        dto = self._map_entity_to_dto(entity)
+        await self._session.delete(dto)
+        self._identity_map.pop(entity.id, None)
+
+    @final
+    def map_dto_to_entity_and_track(self, dto: DTO) -> E:
+        entity = self._map_dto_to_entity(dto)
+        self._track(entity)
+        return entity
+
+    @abc.abstractmethod
+    def _map_entity_to_dto(self, entity: E) -> DTO:
+        """Convert a domain entity to a DTO."""
+        pass
+
+    @abc.abstractmethod
+    def _map_dto_to_entity(self, dto: DTO) -> E:
+        """Convert a DTO to a domain entity."""
+        pass
+
+    def _track(self, entity: E) -> None:
+        self._identity_map[entity.id] = entity
+
+    async def sync_state(self) -> None:
+        for entity in self._identity_map.values():
+            dto = self._map_entity_to_dto(entity)
+            await self._session.merge(dto)
+
+
+class GenericSqlUnitOfWork:
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    async def __aenter__(self) -> None:
+        return
+
+    async def __aexit__(
+        self,
+        exc_type: type,
+        exc: BaseException,
+        tb: TracebackType,
+    ) -> None:
+        await self.rollback()
+        await self._session.close()
+
+    async def commit(self) -> None:
+        for repo in self._repositories:
+            await repo.sync_state()
+
+        await self._session.commit()
+
+    async def rollback(self) -> None:
+        await self._session.rollback()
+
+    @property
+    def _repositories(self) -> Sequence[GenericSqlRepository]:
+        return [value for value in self.__dict__.values() if isinstance(value, GenericSqlRepository)]

scaffold_framework-0.1.0/src/scaffold/pub_sub.py

@@ -0,0 +1,88 @@
+import asyncio
+import json
+from collections.abc import AsyncGenerator
+
+from psycopg import sql
+from psycopg_pool import AsyncConnectionPool
+
+
+class PostgresPubSubService:
+    def __init__(
+        self,
+        connection_pool: AsyncConnectionPool,
+        database_channel: str = "pub_sub_messages",
+    ) -> None:
+        self._connection_pool = connection_pool
+        self._database_channel = database_channel
+        self._subscribers: dict[str, list[asyncio.Queue]] = {}
+        self._listener_task: asyncio.Task | None = None
+
+    async def init(self) -> None:
+        await self._connection_pool.open()
+
+    async def publish(self, channel_name: str, message: str) -> None:
+        async with self._connection_pool.connection() as conn:
+            payload = json.dumps({"channel_name": channel_name, "message": message})
+            await conn.execute(
+                sql.SQL("NOTIFY {database_channel}, {payload}").format(
+                    database_channel=sql.Identifier(self._database_channel),
+                    payload=sql.Literal(payload),
+                ),
+            )
+            await conn.commit()
+
+    async def subscribe(self, channel_name: str) -> AsyncGenerator[str, None]:
+        queue: asyncio.Queue = asyncio.Queue()
+        self._subscribers.setdefault(channel_name, []).append(queue)
+
+        # Start the listener task if it's not already running
+        if not self._listener_task or self._listener_task.done():
+            self._listener_task = asyncio.create_task(self._listen())
+
+        try:
+            while True:
+                message = await queue.get()
+                yield message
+
+        finally:
+            # Cleanup when the subscriber is done
+            self._subscribers[channel_name].remove(queue)
+            if not self._subscribers[channel_name]:
+                del self._subscribers[channel_name]
+
+            # Cancel the listener task if no subscribers remain
+            if not any(self._subscribers.values()) and self._listener_task:
+                self._listener_task.cancel()
+                try:
+                    await self._listener_task
+                except asyncio.CancelledError:
+                    pass  # Listener task has been cancelled
+                self._listener_task = None
+
+    async def _listen(self) -> None:
+        async with self._connection_pool.connection() as conn:
+            await conn.execute(
+                sql.SQL("LISTEN {database_channel}").format(
+                    database_channel=sql.Identifier(self._database_channel),
+                ),
+            )
+            await conn.commit()
+
+            async for notification in conn.notifies():
+                payload = notification.payload
+                try:
+                    # Parse the JSON payload
+                    data = json.loads(payload)
+                    channel_name = data.get("channel_name")
+                    message = data.get("message")
+
+                    if channel_name and message:
+                        # Dispatch the message to subscribers of the logical channel
+                        subscribers = self._subscribers.get(channel_name, [])
+                        for queue in subscribers:
+                            await queue.put(message)
+
+                except json.JSONDecodeError:
+                    # Handle invalid JSON payloads
+                    # TODO log this?
+                    continue