fastapi-startkit 0.49.0__tar.gz → 0.51.0__tar.gz

{fastapi_startkit-0.49.0 → fastapi_startkit-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.49.0
+Version: 0.51.0
 Summary: A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console.
 Keywords: fastapi,framework,async,web,asgi,orm,sqlalchemy,pydantic,ioc-container,dependency-injection,service-provider,cli,console,configuration,microservices,starter-kit,boilerplate
 Author: Bedram Tamang
@@ -46,3 +46,63 @@ Provides-Extra: mysql
 Provides-Extra: postgres
 Provides-Extra: sqlite
 Provides-Extra: vite
+Description-Content-Type: text/markdown
+
+# FastAPI Startkit
+
+[![codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework/graph/badge.svg)](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+
+A modular, provider-driven framework for building Python applications with FastAPI. It bundles a
+service container, configuration system, an async-first ORM, facades, and a Cleo-powered console into
+a single cohesive foundation.
+
+## Installation
+
+```bash
+pip install fastapi-startkit
+```
+
+Optional extras enable additional capabilities:
+
+```bash
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+## Features
+
+- **Service container** — IoC container with `bind`/`make`/`resolve` auto-wiring and lifecycle hooks.
+- **Configuration** — dataclass-based config sourced from the environment with dotted-key access.
+- **Providers** — two-phase (`register` / `boot`) service registration.
+- **Routing** — a `Router` wrapper around FastAPI's `APIRouter` with a `resource()` CRUD shortcut.
+- **ORM** — async-first Masonite ORM fork on SQLAlchemy async, with relationships and migrations.
+- **Facades** — static-like access to container-resolved services (`Config`, `Auth`, ...).
+- **Console** — Cleo-based CLI (`artisan`) for migrations, seeders, and code generation.
+
+## Documentation
+
+Full documentation is available at
+[fastapi-startkit.github.io](https://fastapi-startkit.github.io).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --group dev --extra database --extra sqlite --extra fastapi --extra vite --extra postgres
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov --cov-report=term-missing
+```
+
+Coverage is collected in CI and reported to
+[Codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework).
+
+## License
+
+See the repository root for license details.

fastapi_startkit-0.51.0/README.md

@@ -0,0 +1,58 @@
+# FastAPI Startkit
+
+[![codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework/graph/badge.svg)](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+
+A modular, provider-driven framework for building Python applications with FastAPI. It bundles a
+service container, configuration system, an async-first ORM, facades, and a Cleo-powered console into
+a single cohesive foundation.
+
+## Installation
+
+```bash
+pip install fastapi-startkit
+```
+
+Optional extras enable additional capabilities:
+
+```bash
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+## Features
+
+- **Service container** — IoC container with `bind`/`make`/`resolve` auto-wiring and lifecycle hooks.
+- **Configuration** — dataclass-based config sourced from the environment with dotted-key access.
+- **Providers** — two-phase (`register` / `boot`) service registration.
+- **Routing** — a `Router` wrapper around FastAPI's `APIRouter` with a `resource()` CRUD shortcut.
+- **ORM** — async-first Masonite ORM fork on SQLAlchemy async, with relationships and migrations.
+- **Facades** — static-like access to container-resolved services (`Config`, `Auth`, ...).
+- **Console** — Cleo-based CLI (`artisan`) for migrations, seeders, and code generation.
+
+## Documentation
+
+Full documentation is available at
+[fastapi-startkit.github.io](https://fastapi-startkit.github.io).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --group dev --extra database --extra sqlite --extra fastapi --extra vite --extra postgres
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov --cov-report=term-missing
+```
+
+Coverage is collected in CI and reported to
+[Codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework).
+
+## License
+
+See the repository root for license details.

{fastapi_startkit-0.49.0 → fastapi_startkit-0.51.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "fastapi-startkit"
-version = "0.49.0"
+version = "0.51.0"
 description = "A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console."
+readme = "README.md"
 keywords = [
     "fastapi",
     "framework",
@@ -148,7 +149,7 @@ omit = [
 [tool.coverage.report]
 show_missing = true
 skip_covered = false
-fail_under = 68
+fail_under = 80
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",

{fastapi_startkit-0.49.0 → fastapi_startkit-0.51.0}/src/fastapi_startkit/application.py

@@ -8,6 +8,7 @@ from typing import Type, Callable, Any, List, TypeVar, Generic
 from .config import AppConfig
 from .configuration.providers import ConfigurationProvider
 from .container import Container
+from .events import EventServiceProvider
 from .environment.environment import Environment
 
 if TYPE_CHECKING:
@@ -27,6 +28,7 @@ TConfig = TypeVar("TConfig", bound=AppConfig)
 class Application(Container, Generic[TConfig]):
     DEFAULT_PROVIDERS = [
         ConfigurationProvider,
+        EventServiceProvider,
         AppProvider,
     ]
 

{fastapi_startkit-0.49.0 → fastapi_startkit-0.51.0}/src/fastapi_startkit/container/container.py

@@ -1,6 +1,7 @@
 """Core of the IOC Container."""
 
 import inspect
+from typing import Any
 
 from ..exceptions import (
     ContainerError,
@@ -42,15 +43,13 @@ class Container:
             self.swaps = {}
             self._remembered = {}
 
-    def bind(self, name, class_obj):
+    def bind(self, name: str | type, class_obj: Any) -> None:
         """Bind classes into the container with a key value pair.
 
         Arguments:
-            name {string} -- Name of the key you want to bind the object to
+            name {string | type} -- Key to bind the object to; a class object is
+                accepted for class-keyed bindings (mirrors make()'s class-key support)
             class_obj {object} -- The object you want to bind
-
-        Returns:
-            self
         """
         if inspect.ismodule(class_obj):
             raise StrictContainerException(
@@ -63,8 +62,6 @@ class Container:
             self.fire_hook("bind", name, class_obj)
             self.objects.update({name: class_obj})
 
-        return self
-
     def unbind(self, name):
         """Unbind classes from the container from a key.
 

fastapi_startkit-0.51.0/src/fastapi_startkit/events/__init__.py

@@ -0,0 +1,13 @@
+from .dispatcher import Dispatcher
+from .fake import EventFake
+from .helpers import event
+from .listener import Listener
+from .provider import EventServiceProvider
+
+__all__ = [
+    "Dispatcher",
+    "EventFake",
+    "EventServiceProvider",
+    "Listener",
+    "event",
+]

fastapi_startkit-0.51.0/src/fastapi_startkit/events/dispatcher.py

@@ -0,0 +1,141 @@
+"""Application event dispatcher.
+
+An async-aware, Laravel-style event dispatcher. Events are plain classes;
+listeners are callables or classes exposing a ``handle`` method. Both sync and
+coroutine listeners are supported — coroutine results are awaited transparently.
+"""
+
+import inspect
+from fnmatch import fnmatchcase
+from typing import TYPE_CHECKING, Any, Callable, cast, overload
+
+if TYPE_CHECKING:
+    from ..container import Container
+    from .fake import EventFake
+
+
+class Dispatcher:
+    def __init__(self, container: "Container | None" = None):
+        self._container = container
+        self._listeners: dict[str, list] = {}
+
+    @overload
+    def listen(self, events, listener: None = None) -> Callable: ...
+
+    @overload
+    def listen(self, events, listener: Callable) -> None: ...
+
+    def listen(self, events, listener: Callable | None = None):
+        """Register a listener for one or more events.
+
+        ``events`` may be an event class, a string name, or a list of either.
+        String names may contain ``*`` wildcards (e.g. ``"user.*"``) — the
+        listener then fires for any matching event name. Used as a decorator
+        when ``listener`` is omitted.
+        """
+        if listener is None:
+
+            def decorator(func: Callable) -> Callable:
+                self.listen(events, func)
+                return func
+
+            return decorator
+
+        for name in self._event_names(events):
+            self._listeners.setdefault(name, []).append(listener)
+        return None
+
+    def has_listeners(self, event) -> bool:
+        return bool(self._get_listeners(self._event_key(event)))
+
+    def forget(self, event) -> None:
+        """Remove all listeners registered for a given event."""
+        self._listeners.pop(self._event_key(event), None)
+
+    def flush(self) -> None:
+        """Remove every registered listener."""
+        self._listeners.clear()
+
+    async def dispatch(self, event, payload=None, halt: bool = False):
+        """Fire an event and call its listeners in registration order.
+
+        Returns the list of listener responses. When ``halt`` is true, the first
+        non-``None`` response is returned immediately. A listener returning
+        ``False`` stops propagation to later listeners.
+        """
+        name, args = self._parse_event_payload(event, payload)
+
+        responses: list[Any] = []
+        for listener in self._get_listeners(name):
+            response = await self._call_listener(listener, args)
+
+            if halt and response is not None:
+                return response
+
+            if response is False:
+                break
+
+            responses.append(response)
+
+        return None if halt else responses
+
+    async def until(self, event, payload=None):
+        """Dispatch an event, returning the first non-``None`` listener response."""
+        return await self.dispatch(event, payload, halt=True)
+
+    def fake(self, events_to_fake=None) -> "EventFake":
+        """Swap the container's dispatcher for a recording fake (testing helper)."""
+        from .fake import EventFake
+
+        fake = EventFake(cast("Dispatcher", self), events_to_fake)
+        if self._container is not None:
+            self._container.bind("events", fake)
+        return fake
+
+    def _event_names(self, events) -> list[str]:
+        items = events if isinstance(events, (list, tuple)) else [events]
+        return [self._event_key(event) for event in items]
+
+    def _get_listeners(self, name: str) -> list:
+        """All listeners for an event name: exact matches first, then any
+        wildcard-pattern listeners whose pattern matches the name."""
+        listeners = list(self._listeners.get(name, []))
+        for pattern, pattern_listeners in self._listeners.items():
+            if pattern != name and "*" in pattern and fnmatchcase(name, pattern):
+                listeners.extend(pattern_listeners)
+        return listeners
+
+    def _event_key(self, event) -> str:
+        if isinstance(event, str):
+            return event
+        cls = event if inspect.isclass(event) else type(event)
+        return f"{cls.__module__}.{cls.__qualname__}"
+
+    def _parse_event_payload(self, event, payload) -> tuple[str, list]:
+        if isinstance(event, str):
+            if payload is None:
+                args: list = []
+            elif isinstance(payload, (list, tuple)):
+                args = list(payload)
+            else:
+                args = [payload]
+            return event, args
+
+        return self._event_key(event), [event]
+
+    async def _call_listener(self, listener: Callable, args: list):
+        handler = self._resolve_listener(listener)
+        result = handler(*args)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    def _resolve_listener(self, listener: Callable) -> Callable:
+        if inspect.isclass(listener):
+            return self._make(listener).handle
+        return listener
+
+    def _make(self, cls):
+        if self._container is not None:
+            return self._container.resolve(cls)
+        return cls()

fastapi_startkit-0.51.0/src/fastapi_startkit/events/fake.py

@@ -0,0 +1,79 @@
+"""A recording fake dispatcher used by ``Event.fake()`` in tests.
+
+Faked events are captured instead of dispatched to their listeners; any event
+not in the fake list is forwarded to the real dispatcher. The recorded events
+can then be asserted against.
+"""
+
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from .dispatcher import Dispatcher
+
+
+class EventFake:
+    def __init__(self, dispatcher: "Dispatcher", events_to_fake=None):
+        self._dispatcher = dispatcher
+        self._events_to_fake = self._normalize(events_to_fake)
+        self._dispatched: dict[str, list] = {}
+
+    async def dispatch(self, event, payload=None, halt: bool = False):
+        name, args = self._dispatcher._parse_event_payload(event, payload)
+
+        if self._should_fake(name):
+            recorded = args if isinstance(event, str) else event
+            self._dispatched.setdefault(name, []).append(recorded)
+            return None if halt else []
+
+        return await self._dispatcher.dispatch(event, payload, halt)
+
+    async def until(self, event, payload=None):
+        return await self.dispatch(event, payload, halt=True)
+
+    def listen(self, events, listener: Callable | None = None):
+        return self._dispatcher.listen(events, listener)
+
+    def has_listeners(self, event) -> bool:
+        return self._dispatcher.has_listeners(event)
+
+    def forget(self, event) -> None:
+        self._dispatcher.forget(event)
+
+    def flush(self) -> None:
+        self._dispatcher.flush()
+
+    def dispatched(self, event, callback: Callable | None = None) -> list:
+        """Return recorded dispatches for an event, optionally filtered."""
+        records = self._dispatched.get(self._dispatcher._event_key(event), [])
+        if callback is None:
+            return list(records)
+        return [record for record in records if callback(record)]
+
+    def assert_dispatched(self, event, callback: Callable | None = None) -> list:
+        records = self.dispatched(event, callback)
+        assert records, f"The expected event [{self._dispatcher._event_key(event)}] was not dispatched."
+        return records
+
+    def assert_dispatched_times(self, event, times: int = 1) -> None:
+        count = len(self.dispatched(event))
+        assert count == times, (
+            f"The expected event [{self._dispatcher._event_key(event)}] was dispatched {count} "
+            f"time(s) instead of {times} time(s)."
+        )
+
+    def assert_not_dispatched(self, event, callback: Callable | None = None) -> None:
+        count = len(self.dispatched(event, callback))
+        assert count == 0, f"The unexpected event [{self._dispatcher._event_key(event)}] was dispatched."
+
+    def assert_nothing_dispatched(self) -> None:
+        total = sum(len(records) for records in self._dispatched.values())
+        assert total == 0, f"{total} unexpected event(s) were dispatched."
+
+    def _normalize(self, events) -> list[str]:
+        if events is None:
+            return []
+        items = events if isinstance(events, (list, tuple)) else [events]
+        return [self._dispatcher._event_key(event) for event in items]
+
+    def _should_fake(self, name: str) -> bool:
+        return not self._events_to_fake or name in self._events_to_fake

fastapi_startkit-0.51.0/src/fastapi_startkit/events/helpers.py

@@ -0,0 +1,19 @@
+"""Global ``event()`` helper mirroring Laravel's event helper."""
+
+from typing import cast
+
+from .dispatcher import Dispatcher
+
+
+def event(event, payload=None, halt: bool = False):
+    """Dispatch an event through the container's dispatcher.
+
+    Returns the awaitable produced by ``Dispatcher.dispatch`` — callers should
+    ``await`` it::
+
+        await event(OrderShipped(order))
+    """
+    from ..application import app
+
+    dispatcher = cast(Dispatcher, app().make("events"))
+    return dispatcher.dispatch(event, payload, halt)

fastapi_startkit-0.51.0/src/fastapi_startkit/events/listener.py

@@ -0,0 +1,16 @@
+"""Optional base class for class-based listeners.
+
+Listeners are not required to extend this — any callable, or any class exposing
+a ``handle`` method, works. It exists to document the contract and to give
+type checkers something to lean on. ``handle`` may be sync or async.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Listener(ABC):
+    @abstractmethod
+    def handle(self, event: Any):
+        """Handle the given event."""
+        ...

fastapi_startkit-0.51.0/src/fastapi_startkit/events/provider.py

@@ -0,0 +1,31 @@
+"""Service provider that registers the event dispatcher.
+
+Subclass and define ``listen`` to map events to their listeners, mirroring
+Laravel's ``EventServiceProvider``::
+
+    class AppEventServiceProvider(EventServiceProvider):
+        listen = {
+            UserRegistered: [SendWelcomeEmail, LogRegistration],
+        }
+"""
+
+from typing import cast
+
+from fastapi_startkit.support import Provider
+
+from .dispatcher import Dispatcher
+
+
+class EventServiceProvider(Provider):
+    provider_key = "events"
+
+    listen: dict = {}
+
+    def register(self) -> None:
+        self.app.bind("events", Dispatcher(self.app))
+
+    def boot(self) -> None:
+        dispatcher = cast(Dispatcher, self.app.make("events"))
+        for event, listeners in self.listen.items():
+            for listener in listeners:
+                dispatcher.listen(event, listener)

fastapi_startkit-0.51.0/src/fastapi_startkit/facades/Event.py

@@ -0,0 +1,5 @@
+from .Facade import Facade
+
+
+class Event(metaclass=Facade):
+    key = "events"

fastapi_startkit-0.51.0/src/fastapi_startkit/facades/Event.pyi

@@ -0,0 +1,41 @@
+from typing import Any, Callable
+
+from fastapi_startkit.events.fake import EventFake
+
+class Event:
+    """Facade for the event dispatcher registered under the 'events' key."""
+
+    @staticmethod
+    def listen(events: Any, listener: Callable | None = None) -> Callable | None:
+        """Register a listener for one or more events (or use as a decorator)."""
+        ...
+
+    @staticmethod
+    async def dispatch(event: Any, payload: Any = None, halt: bool = False) -> Any:
+        """Fire an event and invoke its listeners; returns their responses."""
+        ...
+
+    @staticmethod
+    async def until(event: Any, payload: Any = None) -> Any:
+        """Dispatch an event, returning the first non-None listener response."""
+        ...
+
+    @staticmethod
+    def has_listeners(event: Any) -> bool:
+        """Return whether any listener is registered for the event."""
+        ...
+
+    @staticmethod
+    def forget(event: Any) -> None:
+        """Remove all listeners registered for the event."""
+        ...
+
+    @staticmethod
+    def flush() -> None:
+        """Remove every registered listener."""
+        ...
+
+    @staticmethod
+    def fake(events_to_fake: Any = None) -> EventFake:
+        """Swap the dispatcher for a recording fake and return it."""
+        ...

{fastapi_startkit-0.49.0 → fastapi_startkit-0.51.0}/src/fastapi_startkit/facades/__init__.py

@@ -8,6 +8,7 @@ from .Session import Session
 from .View import View
 from .Gate import Gate
 from .Config import Config
+from .Event import Event
 from .Loader import Loader
 from .Notification import Notification
 from .Dump import Dump

fastapi_startkit-0.51.0/src/fastapi_startkit/fastapi/__init__.py

@@ -0,0 +1,15 @@
+from .providers.fastapi_provider import FastAPIProvider
+from .routers.router import Router
+from .requests.model import RequestModel
+from .config import FastAPIConfig
+from .events import RequestHandled
+from .middleware import RequestLifecycleMiddleware
+
+__all__ = [
+    "FastAPIProvider",
+    "Router",
+    "RequestModel",
+    "FastAPIConfig",
+    "RequestHandled",
+    "RequestLifecycleMiddleware",
+]

fastapi_startkit-0.51.0/src/fastapi_startkit/fastapi/events.py

@@ -0,0 +1,29 @@
+"""Structured events emitted by the FastAPI request lifecycle.
+
+These ride on the framework's Laravel-style event dispatcher (see
+``fastapi_startkit.events``) — this module only defines the event payload,
+it does not dispatch, log, or persist anything itself.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RequestHandled:
+    """Dispatched once per HTTP request by ``RequestLifecycleMiddleware``.
+
+    Register a listener the normal way to observe it::
+
+        from fastapi_startkit.facades import Event
+        from fastapi_startkit.fastapi.events import RequestHandled
+
+        Event.listen(RequestHandled, lambda e: logger.info(
+            "%s %s -> %s (%.1fms) [%s]", e.method, e.path, e.status_code, e.duration_ms, e.request_id
+        ))
+    """
+
+    method: str
+    path: str
+    status_code: int
+    duration_ms: float
+    request_id: str

fastapi_startkit-0.51.0/src/fastapi_startkit/fastapi/middleware.py

@@ -0,0 +1,54 @@
+"""ASGI middleware that emits a structured ``RequestHandled`` event per request.
+
+This is dispatch-only: it fires the event through the framework's existing
+Event dispatcher (task #940) and does not persist, log, or render anything
+itself. Consumers — a logging listener, tests, future tooling — register
+listeners the normal way via ``Event.listen(RequestHandled, ...)``.
+
+Out of scope for this middleware (left as extension points for follow-up
+work): DB query watchers, exception watchers, and any other Telescope-style
+watcher, plus storage/UI for the emitted events.
+"""
+
+import time
+import uuid
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fastapi_startkit.events.helpers import event
+
+from .events import RequestHandled
+
+REQUEST_ID_HEADER = "X-Request-Id"
+
+
+class RequestLifecycleMiddleware(BaseHTTPMiddleware):
+    """Dispatches ``RequestHandled`` (method, path, status, duration, request id)."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        request_id = request.headers.get(REQUEST_ID_HEADER) or str(uuid.uuid4())
+        request.state.request_id = request_id
+
+        started_at = time.perf_counter()
+        response = None
+        try:
+            response = await call_next(request)
+            return response
+        finally:
+            duration_ms = (time.perf_counter() - started_at) * 1000
+            status_code = response.status_code if response is not None else 500
+
+            if response is not None:
+                response.headers.setdefault(REQUEST_ID_HEADER, request_id)
+
+            await event(
+                RequestHandled(
+                    method=request.method,
+                    path=request.url.path,
+                    status_code=status_code,
+                    duration_ms=duration_ms,
+                    request_id=request_id,
+                )
+            )