fastapi-startkit 0.59.0__tar.gz → 0.61.0__tar.gz

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.59.0
+Version: 0.61.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

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.59.0"
+version = "0.61.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_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/fastapi/commands/serve_command.py

@@ -11,6 +11,9 @@ from fastapi_startkit.support import Uri, Uriable
 if TYPE_CHECKING:
     from fastapi_startkit.application import Application
 
+# Values accepted by uvicorn's `ws` setting.
+WS_BACKENDS = ("auto", "none", "websockets", "websockets-sansio", "wsproto")
+
 
 class ServeCommand(Command):
     name = "serve"
@@ -45,6 +48,13 @@ class ServeCommand(Command):
             default=None,
             description="The application to serve (overrides fastapi config)",
         ),
+        option(
+            "ws",
+            None,
+            flag=False,
+            default=None,
+            description=f"The uvicorn WebSocket backend: {', '.join(WS_BACKENDS)} (overrides fastapi config)",
+        ),
     ]
 
     def config_value(self, key: str) -> Any:
@@ -72,11 +82,20 @@ class ServeCommand(Command):
 
         return uri.with_port(port) if port else uri
 
+    def resolve_ws(self) -> str:
+        """CLI flag > fastapi config > FastAPIConfig default ('auto')."""
+        return str(self.option("ws") or self.config_value("ws"))
+
     def handle(self) -> int:
         import uvicorn
 
         from fastapi_startkit.container import Container
 
+        ws = self.resolve_ws()
+        if ws not in WS_BACKENDS:
+            self.line_error(f"Invalid --ws backend '{ws}'. Allowed values: {', '.join(WS_BACKENDS)}.", style="error")
+            return 1
+
         url = self.resolve_url()
         reload = self.resolve_option("reload")
         app = self.resolve_option("app")
@@ -85,7 +104,7 @@ class ServeCommand(Command):
             "host": url.host(),
             "port": url.port(),
             "reload": reload,
-            "ws": "websockets-sansio",
+            "ws": ws,
         }
 
         if self.is_app_exist(app):

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/fastapi/config/fastapi.py

@@ -8,6 +8,8 @@ class FastAPIConfig:
     app_url: str = dataclasses.field(default_factory=lambda: env("APP_URL", "http://127.0.0.1:8000"))
     app: str = "bootstrap.application:app"
     reload: bool = dataclasses.field(default_factory=lambda: env("APP_RELOAD", True))
+    # 'auto' keeps the optional `websockets` package from being required at startup.
+    ws: str = dataclasses.field(default_factory=lambda: env("APP_WS", "auto"))
     reload_dirs: list | None = None
     reload_excludes: list = dataclasses.field(
         default_factory=lambda: [

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/inertia/inertia.py

@@ -1,4 +1,7 @@
 import inspect
+import asyncio
+import json
+import urllib.request
 from typing import Any, Dict, Optional, Union
 from urllib.parse import urlparse
 
@@ -19,6 +22,8 @@ class ResponseFactory:
         self.root_view: str = "index.html"
         self.shared_props: dict = {}
         self.version = None
+        self.ssr_url: Optional[str] = None
+        self.ssr_timeout: float = 1.0
 
     def set_root_view(self, view: str):
         self.root_view = view
@@ -36,6 +41,11 @@ class ResponseFactory:
         v = self.version() if callable(self.version) else self.version
         return str(v) if v is not None else None
 
+    def set_ssr(self, url: Optional[str], timeout: float = 1.0):
+        """Configure the Inertia SSR server endpoint. Pass None to disable SSR."""
+        self.ssr_url = url.rstrip("/") if url else None
+        self.ssr_timeout = timeout
+
     def render(self, component: str, props: dict) -> "InertiaResponse":
         return InertiaResponse(
             component=component,
@@ -43,6 +53,8 @@ class ResponseFactory:
             props=props,
             root_view=self.root_view,
             version=self.get_version() or "",
+            ssr_url=self.ssr_url,
+            ssr_timeout=self.ssr_timeout,
         )
 
 
@@ -54,6 +66,8 @@ class InertiaResponse(Response):
         props: dict,
         root_view: str = "index.html",
         version: str = "",
+        ssr_url: Optional[str] = None,
+        ssr_timeout: float = 1.0,
     ):
         # Do not call supper().__init__() — body is built lazily in __call__
         self.background = None  # required by FastAPI's response handling
@@ -62,6 +76,8 @@ class InertiaResponse(Response):
         self.props = props
         self.root_view = root_view
         self.version = version
+        self.ssr_url = ssr_url
+        self.ssr_timeout = ssr_timeout
 
     def with_(self, key: Union[str, Dict[str, Any]], value: Any = None) -> "InertiaResponse":
         if isinstance(key, dict):
@@ -114,6 +130,13 @@ class InertiaResponse(Response):
             "version": self.version,
         }
 
+        # SSR is used only for the initial HTML response. Inertia XHR requests
+        # continue returning the regular page JSON and never contact Node.
+        if not request.headers.get(Header.INERTIA) and self.ssr_url:
+            rendered = await self._render_ssr(page)
+            if rendered:
+                page["ssr"] = rendered
+
         if request.headers.get(Header.INERTIA):
             return JSONResponse(
                 content=page,
@@ -135,6 +158,33 @@ class InertiaResponse(Response):
             )
         )
 
+    async def _render_ssr(self, page: dict) -> Optional[dict]:
+        """Ask the configured Inertia Node server to render this page."""
+        ssr_url = self.ssr_url
+        if ssr_url is None:
+            return None
+
+        def request_ssr():
+            body = json.dumps(page).encode("utf-8")
+            req = urllib.request.Request(
+                ssr_url.rstrip("/") + "/render",
+                data=body,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=self.ssr_timeout) as response:
+                result = json.loads(response.read().decode("utf-8"))
+            if not isinstance(result, dict) or not isinstance(result.get("body"), str):
+                raise ValueError("Invalid Inertia SSR response")
+            return {"body": result["body"], "head": result.get("head", [])}
+
+        try:
+            return await asyncio.to_thread(request_ssr)
+        except Exception:
+            # SSR is an enhancement: if its process is unavailable, send the
+            # normal page shell so the client can still hydrate it.
+            return None
+
     def _get_url(self, request: Request) -> str:
         parsed = urlparse(str(request.url))
         url = parsed.path
@@ -174,6 +224,11 @@ class Inertia:
     def version(version):
         Inertia.instance().set_version(version)
 
+    @staticmethod
+    def ssr(url: Optional[str] = "http://127.0.0.1:13714", timeout: float = 1.0):
+        """Enable SSR through the standard Inertia SSR server endpoint."""
+        Inertia.instance().set_ssr(url, timeout)
+
     @staticmethod
     def get_version() -> Optional[str]:
         return Inertia.instance().get_version()

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/inertia/provider.py

@@ -18,10 +18,19 @@ class InertiaProvider(Provider):
             templates = self.app.make("templates")
 
             def inertia_helper(page):
-                encoded_page = json.dumps(page)
+                client_page = {key: value for key, value in page.items() if key != "ssr"}
+                encoded_page = json.dumps(client_page).replace("<", "\\u003c")
+                ssr_body = page.get("ssr", {}).get("body", "")
                 return Markup(
-                    f'<script data-page="app" type="application/json">{encoded_page}</script><div id="app"></div>'
+                    f'<script data-page="app" type="application/json">{encoded_page}</script><div id="app">{ssr_body}</div>'
                 )
 
+            def inertia_head(page):
+                head = page.get("ssr", {}).get("head", [])
+                if isinstance(head, str):
+                    head = [head]
+                return Markup("".join(str(item) for item in head))
+
             templates.env.globals["inertia"] = inertia_helper
+            templates.env.globals["inertia_head"] = inertia_head
             templates.env.globals["Inertia"] = self.app.make("inertia")

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/logging/config/logging.py

@@ -7,6 +7,7 @@ from fastapi_startkit.logging.config import StackChannel, DailyChannel, Terminal
 @dataclasses.dataclass
 class LoggingConfig:
     default: str = dataclasses.field(default_factory=lambda: env("LOG_CHANNEL", "stack"))
+    level: str = dataclasses.field(default_factory=lambda: env("LOG_LEVEL", "info"))
 
     channels: dict = dataclasses.field(
         default_factory=lambda: {

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/logging/handler.py

@@ -1,5 +1,8 @@
 import logging
 
+# Framework-only severities have no stdlib equivalent; map them to the nearest one.
+_STDLIB_LEVELS = {"notice": "INFO", "alert": "CRITICAL", "emergency": "CRITICAL"}
+
 
 class LoggingHandler(logging.Handler):
     def emit(self, record: logging.LogRecord) -> None:
@@ -8,8 +11,9 @@ class LoggingHandler(logging.Handler):
         Logger.log(record.levelname, self.format(record))
 
     @staticmethod
-    def install():
+    def install(level: str | None = None):
         root_logger = logging.getLogger()
         if not any(isinstance(h, LoggingHandler) for h in root_logger.handlers):
             root_logger.addHandler(LoggingHandler())
-            root_logger.setLevel(logging.DEBUG)
+        if level:
+            root_logger.setLevel(_STDLIB_LEVELS.get(level.lower(), level.upper()))

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/logging/managers/LoggingManager.py

@@ -7,10 +7,11 @@ class LoggingManager:
         self,
         channel_factory: type[ChannelFactory] = ChannelFactory,
         driver_factory: type[DriverFactory] = DriverFactory,
+        level: str | None = None,
     ):
         self.channel_factory = channel_factory
         self.driver_factory = driver_factory
-        self.configure_python_logging()
+        self.configure_python_logging(level)
 
     def channel(self, channel: str):
         channel_class = self.channel_factory.make(channel)
@@ -19,7 +20,7 @@ class LoggingManager:
         return channel_class()
 
     @classmethod
-    def configure_python_logging(cls):
+    def configure_python_logging(cls, level: str | None = None):
         from ..handler import LoggingHandler
 
-        LoggingHandler.install()
+        LoggingHandler.install(level)

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/logging/providers/log_provider.py

@@ -17,7 +17,7 @@ class LogProvider(Provider):
 
         self.app.bind("LogChannelFactory", ChannelFactory)
         self.app.bind("LogDriverFactory", DriverFactory)
-        self.app.bind("LoggingManager", LoggingManager(ChannelFactory, DriverFactory))
+        self.app.bind("LoggingManager", LoggingManager(ChannelFactory, DriverFactory, config.get("level")))
 
     def boot(self):
         self.publishes({Path(__file__).resolve().parent.parent.joinpath("config/logging.py"): "config/logging.py"})

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/masoniteorm/config/config.py

@@ -1,5 +1,6 @@
 from typing import Optional, Dict, Any
 from pydantic.dataclasses import dataclass
+from pydantic.fields import Field
 from fastapi_startkit.environment.environment import env
 
 
@@ -8,6 +9,7 @@ class SQLiteConfig:
     driver: str = "sqlite"
     url: Optional[str] = env("DB_URL", None, cast=False)
     database: str = env("DB_DATABASE", "database.sqlite")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None
 
 
@@ -23,6 +25,7 @@ class MySQLConfig:
     unix_socket: str = env("DB_SOCKET", "", cast=False)
     charset: str = env("DB_CHARSET", "utf8mb4")
     collation: str = env("DB_COLLATION", "utf8mb4_unicode_ci")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None
 
 
@@ -37,4 +40,5 @@ class PostgresConfig:
     password: str = env("DB_PASSWORD", "", cast=False)
     charset: str = env("DB_CHARSET", "utf8")
     sslmode: str = env("DB_SSLMODE", "prefer")
+    echo: bool = Field(default_factory=lambda: env("DB_ECHO", False))
     options: Optional[Dict[str, Any]] = None

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/masoniteorm/connections/factory.py

@@ -64,7 +64,7 @@ class ConnectionFactory:
     @classmethod
     def create_engine(cls, cfg: dict) -> AsyncEngine:
         url = cls.build_url(cfg)
-        kwargs: dict[str, Any] = {"echo": True}
+        kwargs: dict[str, Any] = {"echo": bool(cfg.get("echo", False))}
         from fastapi_startkit.application import app
 
         if cast("Application", app()).is_testing():

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/masoniteorm/models/builder.py

@@ -29,6 +29,11 @@ TModel = TypeVar("TModel", bound="Model")
 # returns it, which the parent renders as a parenthesised subgroup.
 type WhereGroup[M: "Model"] = Callable[["QueryBuilder[M]"], "QueryBuilder[M]"]
 
+# select_sub()/add_select() subquery source: a builder, or a callable that
+# receives a fresh builder and returns the subquery.
+type Subquery = "QueryBuilder[Any] | Callable[[QueryBuilder[Any]], QueryBuilder[Any]]"
+type SelectEntry = "str | dict[str, str | Subquery]"
+
 
 class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
     operators = [
@@ -129,6 +134,59 @@ class QueryBuilder(EagerLoadMixin, SupportMixin, Generic[TModel]):
                     self._columns += (SelectExpression(column),)
         return self
 
+    def select_sub(self, subquery: "Subquery", alias: str) -> "Self":
+        """Add ``(subquery) AS alias`` to the selection.
+
+        ``subquery`` is a builder, or a callable that receives a fresh table-less
+        builder and returns one.
+        """
+        if not isinstance(subquery, QueryBuilder) and callable(subquery):
+            subquery = subquery(QueryBuilder(self.connection, self.grammar, self.processor))
+        if not isinstance(subquery, QueryBuilder):
+            raise TypeError("select_sub() expects a QueryBuilder subquery or a callable returning one.")
+        self._columns.append(SubGroupExpression(subquery, alias))
+        return self
+
+    def add_select(self, *columns: "SelectEntry | list[SelectEntry]") -> "Self":
+        """Append columns to the current selection without replacing it.
+
+        Plain string columns are appended once. A ``{alias: subquery}`` entry
+        adds a correlated column via :meth:`select_sub`, first selecting
+        ``{table}.*`` when nothing is selected yet so the base columns survive.
+        A string value under a string key is still a plain column.
+        """
+        entries: list[SelectEntry] = []
+        for column in columns:
+            if isinstance(column, list):
+                entries.extend(column)
+            else:
+                entries.append(column)
+
+        for entry in entries:
+            pairs: Iterable[tuple[str | None, str | Subquery]] = (
+                entry.items() if isinstance(entry, dict) else [(None, entry)]
+            )
+            for alias, value in pairs:
+                if isinstance(value, str):
+                    if not self._is_selected(value):
+                        self._columns.append(SelectExpression(value))
+                    continue
+                if alias is None:
+                    raise TypeError(
+                        "add_select() received a subquery without a string alias; "
+                        "pass {alias: subquery} or use select_sub(subquery, alias)."
+                    )
+                if not self._columns:
+                    self.select(f"{self._table}.*")
+                self.select_sub(value, alias)
+        return self
+
+    def _is_selected(self, column: str) -> bool:
+        return any(
+            isinstance(existing, SelectExpression) and existing.alias is None and existing.column == column
+            for existing in self._columns
+        )
+
     def limit(self, limit: int) -> "Self":
         self._limit = limit
         return self

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/masoniteorm/query/grammars/BaseGrammar.py

@@ -898,7 +898,7 @@ class BaseGrammar:
                         self.add_binding(*column.builder._bindings)
                 else:
                     builder_sql = column.builder.to_sql()
-                sql += f"({builder_sql}) AS {column.alias}, "
+                sql += f"({builder_sql}) " + self.subquery_alias_string().format(alias=column.alias) + ", "
                 continue
 
             sql += self._table_column_string(column, alias=alias, separator=separator)

{fastapi_startkit-0.59.0 → fastapi_startkit-0.61.0}/src/fastapi_startkit/masoniteorm/relationships/BelongsToMany.py

@@ -456,8 +456,7 @@ class BelongsToMany(BaseRelationship):
         if not builder._columns:
             builder = builder.select("*")
 
-        return_query = builder.add_select(
-            f"{query.get_table_name()}_count",
+        return_query = builder.select_sub(
             lambda q: (
                 q.count("*")
                 .where_column(
@@ -473,6 +472,7 @@ class BelongsToMany(BaseRelationship):
                     ),
                 )
             ),
+            f"{query.get_table_name()}_count",
         )
 
         return return_query