fastapi-startkit 0.62.0__tar.gz → 0.63.0__tar.gz

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.62.0
+Version: 0.63.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.62.0 → fastapi_startkit-0.63.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-startkit"
-version = "0.62.0"
+version = "0.63.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.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/ai/config/ai.py

@@ -1,3 +1,4 @@
+from fastapi_startkit.configuration import Config
 from dataclasses import dataclass, field
 
 from fastapi_startkit.environment import env
@@ -6,15 +7,15 @@ from fastapi_startkit.ai import AnthropicConfig, ElevenLabsConfig, GoogleConfig,
 
 
 @dataclass
-class AIConfig:
+class AIConfig(Config):
     """Top-level AI configuration — selects the default provider per modality and holds per-provider configs."""
 
-    default: str = field(default_factory=lambda: env("AI_PROVIDER", "google"))
-    default_image: str = field(default_factory=lambda: env("AI_DEFAULT_IMAGE_PROVIDER", "openai"))
-    default_audio: str = field(default_factory=lambda: env("AI_DEFAULT_AUDIO_PROVIDER", "openai"))
-    default_transcribe: str = field(default_factory=lambda: env("AI_DEFAULT_TRANSCRIBE_PROVIDER", "openai"))
+    default: str = env("AI_PROVIDER", "google")
+    default_image: str = env("AI_DEFAULT_IMAGE_PROVIDER", "openai")
+    default_audio: str = env("AI_DEFAULT_AUDIO_PROVIDER", "openai")
+    default_transcribe: str = env("AI_DEFAULT_TRANSCRIBE_PROVIDER", "openai")
 
-    providers: dict = field(
+    providers: dict[str, Config] = field(
         default_factory=lambda: {
             "google": GoogleConfig(),
             "openai": OpenAIConfig(),

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/ai/config/config.py

@@ -1,19 +1,23 @@
 from __future__ import annotations
 
+import os
+
+from fastapi_startkit.configuration import Config
+
 from dataclasses import dataclass, field
 
 from fastapi_startkit.environment import env
 
 
 @dataclass
-class AnthropicConfig:
+class AnthropicConfig(Config):
     """Configuration for the Anthropic provider."""
 
     driver: str = "anthropic"
-    key: str = field(default_factory=lambda: env("ANTHROPIC_API_KEY", "", cast=False))
-    url: str = field(default_factory=lambda: env("ANTHROPIC_BASE_URL", "https://api.anthropic.com"))
+    key: str = env("ANTHROPIC_API_KEY", "", cast=False)
+    url: str = env("ANTHROPIC_BASE_URL", "https://api.anthropic.com")
 
-    models: dict = field(
+    models: dict[str, str] = field(
         default_factory=lambda: {
             "default": "claude-sonnet-4-6",
         }
@@ -21,14 +25,14 @@ class AnthropicConfig:
 
 
 @dataclass
-class OpenAIConfig:
+class OpenAIConfig(Config):
     """Configuration for the OpenAI provider."""
 
     driver: str = "openai"
-    key: str = field(default_factory=lambda: env("OPENAI_API_KEY", "", cast=False))
-    url: str = field(default_factory=lambda: env("OPENAI_BASE_URL", "https://api.openai.com/v1"))
+    key: str = env("OPENAI_API_KEY", "", cast=False)
+    url: str = env("OPENAI_BASE_URL", "https://api.openai.com/v1")
 
-    models: dict = field(
+    models: dict[str, str] = field(
         default_factory=lambda: {
             "default": "gpt-4o",
             "default_image": "dall-e-3",
@@ -37,15 +41,13 @@ class OpenAIConfig:
 
 
 @dataclass
-class GoogleConfig:
+class GoogleConfig(Config):
     """Configuration for the Google / Gemini provider."""
 
     driver: str = "google"
-    key: str = field(
-        default_factory=lambda: env("GEMINI_API_KEY", "", cast=False) or env("GOOGLE_API_KEY", "", cast=False)
-    )
+    key: str = field(default_factory=lambda: os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY") or "")
 
-    models: dict = field(
+    models: dict[str, str] = field(
         default_factory=lambda: {
             "default": "gemini-2.5-flash-lite",
             "default_image": "imagen-3.0-generate-002",
@@ -54,13 +56,13 @@ class GoogleConfig:
 
 
 @dataclass
-class ElevenLabsConfig:
+class ElevenLabsConfig(Config):
     """Configuration for the ElevenLabs provider."""
 
     driver: str = "elevenlabs"
-    key: str = field(default_factory=lambda: env("ELEVENLABS_API_KEY", "", cast=False))
+    key: str = env("ELEVENLABS_API_KEY", "", cast=False)
 
-    models: dict = field(
+    models: dict[str, str] = field(
         default_factory=lambda: {
             "default_audio": "eleven_multilingual_v2",
             "default_transcribe": "scribe_v1",

fastapi_startkit-0.63.0/src/fastapi_startkit/broadcasting/config.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass, field
+
+from fastapi_startkit.configuration import Config
+from fastapi_startkit.environment import env
+
+
+@dataclass
+class ReverbConnectionConfig(Config):
+    driver: str = "reverb"
+    key: str = env("REVERB_APP_KEY", "local")
+    secret: str = env("REVERB_APP_SECRET", "secret")
+    app_id: str = env("REVERB_APP_ID", "1")
+    host: str = env("REVERB_HOST", "0.0.0.0")
+    port: int = env("REVERB_PORT", 8080)
+    scheme: str = env("REVERB_SCHEME", "http")
+
+
+@dataclass
+class LogConnectionConfig(Config):
+    driver: str = "log"
+
+
+@dataclass
+class BroadcastingConfig(Config):
+    default: str = env("BROADCAST_DRIVER", "log")
+
+    connections: dict[str, ReverbConnectionConfig | LogConnectionConfig] = field(
+        default_factory=lambda: {
+            "reverb": ReverbConnectionConfig(),
+            "log": LogConnectionConfig(),
+        }
+    )

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/carbon/__init__.py

@@ -1 +1,3 @@
 from .carbon import Carbon
+
+__all__ = ["Carbon"]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/config/app.py

@@ -1,11 +1,12 @@
+from fastapi_startkit.configuration import Config
 import os
-from dataclasses import field, dataclass
-from fastapi_startkit.environment.environment import env
+from dataclasses import dataclass, field
+from fastapi_startkit.environment import env as environment_value
 
 
 @dataclass
-class AppConfig:
+class AppConfig(Config):
     name: str = field(default_factory=lambda: os.getenv("APP_NAME", "FastAPI starter kit"))
     env: str = field(default_factory=lambda: os.getenv("APP_ENV", "development"))
-    debug: bool = field(default_factory=lambda: env("APP_DEBUG", True))
+    debug: bool = environment_value("APP_DEBUG", True)
     timezone: str = field(default_factory=lambda: os.getenv("APP_TIMEZONE", "UTC"))

fastapi_startkit-0.63.0/src/fastapi_startkit/configuration/__init__.py

@@ -0,0 +1,5 @@
+from .helpers import config
+from .Configuration import Configuration
+from fastapi_startkit.support.config import Config
+
+__all__ = ["config", "Configuration", "Config"]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/configuration/providers/__init__.py

@@ -1 +1,3 @@
 from .ConfigurationProvider import ConfigurationProvider
+
+__all__ = ["ConfigurationProvider"]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/container/__init__.py

@@ -1 +1,3 @@
 from .container import Container
+
+__all__ = ["Container"]

fastapi_startkit-0.63.0/src/fastapi_startkit/environment/__init__.py

@@ -0,0 +1,3 @@
+from .environment import env, into, value
+
+__all__ = ["env", "into", "value"]

fastapi_startkit-0.63.0/src/fastapi_startkit/environment/environment.py

@@ -0,0 +1,205 @@
+"""Module for the LoadEnvironment class."""
+
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import Field, MISSING, field
+from pathlib import Path
+import typing
+from typing import Literal, TypeVar, overload
+
+from dotenv import load_dotenv
+
+
+T = TypeVar("T")
+U = TypeVar("U")
+EnvValue = str | int | bool
+_UNSET = object()
+_BOOLEANS: dict[str, bool] = {"true": True, "True": True, "false": False, "False": False}
+
+
+class Environment:
+    @staticmethod
+    def resolve_environment(base_path: Path | None = None, env: str | None = None):
+        Environment.resolve_environment_from_argument()
+
+        if "PYTEST_CURRENT_TEST" in os.environ:
+            return "testing"
+
+        # Explicit env parameter takes priority over os.environ APP_ENV
+        if env:
+            return env
+
+        if os.environ.get("APP_ENV"):
+            return os.environ["APP_ENV"]
+
+        path = Environment._require_base_path(base_path) / ".env"
+        if not path.exists():
+            raise ValueError("Unable to determine environment.")
+
+        _ = load_dotenv(path, override=True)
+
+        env = os.environ.get("APP_ENV")
+        if not env:
+            raise ValueError("APP_ENV not set after loading .env")
+
+        return env
+
+    @staticmethod
+    def _require_base_path(base_path: Path | None) -> Path:
+        # Keeps the TypeError the old unguarded `None / ".env"` raised, with a clearer message.
+        if base_path is None:
+            raise TypeError("base_path is required to locate .env files")
+        return base_path
+
+    @staticmethod
+    def load_base(base_path: Path | None = None):
+        """Load the base .env file, resetting vars to their default values."""
+        path = Environment._require_base_path(base_path) / ".env"
+        if path.exists():
+            _ = load_dotenv(path, override=True)
+
+    @staticmethod
+    def load(env: str, override: bool = True, base_path: Path | None = None):
+        path = Environment._require_base_path(base_path) / f".env.{env}"
+        if not path.exists():
+            return
+        _ = load_dotenv(path, override=override)
+
+    @staticmethod
+    def resolve_environment_from_argument():
+        """Parse --env=<value> or --env <value> from sys.argv, set APP_ENV,
+        and remove the tokens so downstream CLI parsers (e.g. cleo) never see them."""
+        args = sys.argv[1:]
+        for i, arg in enumerate(args):
+            if arg.startswith("--env="):
+                os.environ["APP_ENV"] = arg.split("=", 1)[1]
+                del sys.argv[i + 1]
+                break
+            if arg == "--env" and i + 1 < len(args):
+                os.environ["APP_ENV"] = args[i + 1]
+                del sys.argv[i + 1 : i + 3]
+                break
+
+
+@overload
+def env(val: str, *, cast: Literal[True] = True) -> EnvValue: ...
+
+
+@overload
+def env(val: str, default: None, cast: Literal[True] = True) -> EnvValue | None: ...
+
+
+@overload
+def env(val: str, default: T, cast: Literal[True] = True) -> T: ...
+
+
+@overload
+def env(val: str, *, cast: Literal[False]) -> str: ...
+
+
+@overload
+def env(val: str, default: T, cast: Literal[False]) -> str | T: ...
+
+
+@overload
+def env(val: str, *, cast: bool) -> EnvValue: ...
+
+
+@overload
+def env(val: str, default: None, cast: bool) -> EnvValue | None: ...
+
+
+@overload
+def env(val: str, default: T, cast: bool) -> str | T: ...
+
+
+def env(val: str, default: object = _UNSET, cast: bool = True) -> object:
+    def read() -> object:
+        env_var = os.getenv(val, "" if default is _UNSET else default)
+
+        try:
+            return into(env_var, default, cast)
+        except ValueError as error:
+            raise ValueError(f"Cannot cast environment variable {val!r} to {type(default).__name__}") from error
+
+    return field(default_factory=read)
+
+
+def value(item: T) -> T:
+    if isinstance(item, Field):
+        declared = typing.cast(Field[T], item)
+        if declared.default_factory is not MISSING:
+            return declared.default_factory()
+    return item
+
+
+@overload
+def into(item: bool) -> bool: ...
+
+
+@overload
+def into(item: int) -> int: ...
+
+
+@overload
+def into(item: None) -> None: ...
+
+
+@overload
+def into(item: str) -> EnvValue: ...
+
+
+@overload
+def into(item: object, default: None) -> EnvValue | None: ...
+
+
+@overload
+def into(item: object, default: T) -> T: ...
+
+
+@overload
+def into(item: U, *, cast: Literal[False]) -> U: ...
+
+
+@overload
+def into(item: U, default: T, cast: Literal[False]) -> U | T: ...
+
+
+@overload
+def into(item: U, *, cast: bool) -> U | EnvValue: ...
+
+
+@overload
+def into(item: U, default: None, cast: bool) -> U | EnvValue | None: ...
+
+
+@overload
+def into(item: U, default: T, cast: bool) -> U | T: ...
+
+
+def into(item: object, default: object = _UNSET, cast: bool = True) -> object:
+    if not cast:
+        return default if item is None and default is not _UNSET else item
+
+    if item is None or item == "":
+        return item if default is _UNSET else default
+
+    if isinstance(item, bool):
+        return item
+
+    if default is _UNSET or default is None:
+        if isinstance(item, int) or (isinstance(item, str) and item.isnumeric()):
+            return int(item)
+        return _BOOLEANS.get(item, item) if isinstance(item, str) else item
+
+    if isinstance(default, bool):
+        if isinstance(item, str) and item in _BOOLEANS:
+            return _BOOLEANS[item]
+        raise ValueError(f"Cannot cast {item!r} to bool")
+
+    convert = typing.cast(Callable[[object], object], type(default))
+    try:
+        return convert(item)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"Cannot cast {item!r} to {type(default).__name__}") from error

fastapi_startkit-0.63.0/src/fastapi_startkit/exceptions/__init__.py

@@ -0,0 +1,69 @@
+from .handler import ExceptionHandler
+from .exceptions import (
+    AuthorizationException,
+    InvalidRouteCompileException,
+    RouteMiddlewareNotFound,
+    ContainerError,
+    MissingContainerBindingNotFound,
+    StrictContainerException,
+    ResponseError,
+    InvalidHTTPStatusCode,
+    RequiredContainerBindingNotFound,
+    ViewException,
+    RouteNotFoundException,
+    DumpException,
+    InvalidSecretKey,
+    InvalidCSRFToken,
+    NotificationException,
+    InvalidToken,
+    ProjectLimitReached,
+    ProjectProviderTimeout,
+    ProjectProviderHttpError,
+    ProjectTargetNotEmpty,
+    MixFileNotFound,
+    MixManifestNotFound,
+    InvalidConfigurationLocation,
+    InvalidConfigurationSetup,
+    InvalidPackageName,
+    LoaderNotFound,
+    QueueException,
+    ValidationException,
+    AmbiguousError,
+    MethodNotAllowedException,
+    ThrottleRequestsException,
+)
+
+__all__ = [
+    "ExceptionHandler",
+    "AuthorizationException",
+    "InvalidRouteCompileException",
+    "RouteMiddlewareNotFound",
+    "ContainerError",
+    "MissingContainerBindingNotFound",
+    "StrictContainerException",
+    "ResponseError",
+    "InvalidHTTPStatusCode",
+    "RequiredContainerBindingNotFound",
+    "ViewException",
+    "RouteNotFoundException",
+    "DumpException",
+    "InvalidSecretKey",
+    "InvalidCSRFToken",
+    "NotificationException",
+    "InvalidToken",
+    "ProjectLimitReached",
+    "ProjectProviderTimeout",
+    "ProjectProviderHttpError",
+    "ProjectTargetNotEmpty",
+    "MixFileNotFound",
+    "MixManifestNotFound",
+    "InvalidConfigurationLocation",
+    "InvalidConfigurationSetup",
+    "InvalidPackageName",
+    "LoaderNotFound",
+    "QueueException",
+    "ValidationException",
+    "AmbiguousError",
+    "MethodNotAllowedException",
+    "ThrottleRequestsException",
+]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/facades/__init__.py

@@ -16,3 +16,24 @@ from .Queue import Queue
 from .Cache import Cache
 from .RateLimiter import RateLimiter
 from .Redis import Redis
+
+__all__ = [
+    "Facade",
+    "Request",
+    "Response",
+    "Mail",
+    "Hash",
+    "Url",
+    "Session",
+    "View",
+    "Gate",
+    "Config",
+    "Event",
+    "Loader",
+    "Notification",
+    "Dump",
+    "Queue",
+    "Cache",
+    "RateLimiter",
+    "Redis",
+]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/fastapi/commands/__init__.py

@@ -1 +1,3 @@
 from .serve_command import ServeCommand
+
+__all__ = ["ServeCommand"]

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/fastapi/commands/serve_command.py

@@ -4,12 +4,12 @@ from cleo.helpers import option
 
 from fastapi_startkit import Config
 from fastapi_startkit.console.command import Command
-from fastapi_startkit.environment import value as cast_value
 from fastapi_startkit.fastapi.config import FastAPIConfig
 from fastapi_startkit.support import Uri, Uriable
 
 if TYPE_CHECKING:
     from fastapi_startkit.application import Application
+    from fastapi_startkit.config import AppConfig
 
 # Values accepted by uvicorn's `ws` setting.
 WS_BACKENDS = ("auto", "none", "websockets", "websockets-sansio", "wsproto")
@@ -69,7 +69,10 @@ class ServeCommand(Command):
 
     def resolve_option(self, key: str) -> Any:
         """CLI flag > fastapi config > FastAPIConfig default."""
-        return cast_value(self.option(key) or self.config_value(key))
+        selected = self.option(key) or self.config_value(key)
+        if key == "reload" and isinstance(selected, str):
+            return {"true": True, "false": False}.get(selected.lower(), selected)
+        return selected
 
     def resolve_url(self) -> Uriable:
         host = self.option("host") or self.config_value("app_url")
@@ -100,7 +103,7 @@ class ServeCommand(Command):
         reload = self.resolve_option("reload")
         app = self.resolve_option("app")
 
-        kwargs = {
+        kwargs: dict[str, Any] = {
             "host": url.host(),
             "port": url.port(),
             "reload": reload,
@@ -128,7 +131,7 @@ class ServeCommand(Command):
 
         else:
             self.line(f"<info>Starting Uvicorn server on {url.host()}:{url.port()}...</info>")
-            kwargs.update({"app": cast("Application", Container.instance()).fastapi, "reload": False})
+            kwargs.update({"app": cast("Application[AppConfig]", Container.instance()).fastapi, "reload": False})
 
         try:
             uvicorn.run(**kwargs)

{fastapi_startkit-0.62.0 → fastapi_startkit-0.63.0}/src/fastapi_startkit/fastapi/config/fastapi.py

@@ -1,17 +1,19 @@
+from dataclasses import field
+from fastapi_startkit.configuration import Config
 import dataclasses
 
 from fastapi_startkit.environment import env
 
 
 @dataclasses.dataclass
-class FastAPIConfig:
-    app_url: str = dataclasses.field(default_factory=lambda: env("APP_URL", "http://127.0.0.1:8000"))
+class FastAPIConfig(Config):
+    app_url: str = 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))
+    reload: bool = 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"))
+    ws: str = env("APP_WS", "auto")
     reload_dirs: list | None = None
-    reload_excludes: list = dataclasses.field(
+    reload_excludes: list = field(
         default_factory=lambda: [
             "*.log",
             "tests/*",

fastapi_startkit-0.63.0/src/fastapi_startkit/inertia/encoding.py

@@ -0,0 +1,24 @@
+import json
+from typing import Any
+
+HTML_UNSAFE_CHARACTERS = str.maketrans({"<": "\\u003c", ">": "\\u003e", "&": "\\u0026"})
+
+
+def html_safe_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=True).translate(HTML_UNSAFE_CHARACTERS)
+
+
+MAX_SAFE_INTEGER = 2**53 - 1
+BIG_INTEGER_KEY = "$bigint"
+
+
+def encode_big_integers(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return {BIG_INTEGER_KEY: str(value)} if abs(value) > MAX_SAFE_INTEGER else value
+    if isinstance(value, dict):
+        return {key: encode_big_integers(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [encode_big_integers(item) for item in value]
+    return value