astris-python 0.1.0__py3-none-any.whl

astris/config.py

@@ -0,0 +1,50 @@
+from functools import lru_cache
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Centralized application and framework configuration."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    # Core Application
+    app_name: str = "Astris Application"
+    app_env: str = "local"
+    app_debug: bool = True
+    app_key: str = ""
+
+    # Database
+    database_url: str = "sqlite:///database/app.db"
+    db_echo: bool = False
+    auto_create_tables: bool = True
+
+    # Sessions & Security
+    session_cookie_name: str = "astris_session"
+    session_max_age: int | None = 14 * 24 * 60 * 60  # 14 days
+    session_https_only: bool = False
+    session_same_site: Literal["lax", "strict", "none"] = "lax"
+
+    # CORS & CSRF
+    cors_origins: list[str] = [
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+    ]
+    enable_csrf: bool = True
+    csrf_exempt_paths: list[str] = []
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return the cached application settings instance."""
+    return Settings()
+
+
+# Global settings singleton
+settings = get_settings()

astris/database/__init__.py

@@ -0,0 +1,28 @@
+from sqlmodel import (
+    Field,
+    Relationship,
+    Session,
+    SQLModel,
+    col,
+    select,
+)
+
+from astris.database.session import (
+    Database,
+    DatabaseSession,
+    db,
+    get_session,
+)
+
+__all__ = [
+    "Database",
+    "DatabaseSession",
+    "Field",
+    "Relationship",
+    "SQLModel",
+    "Session",
+    "col",
+    "db",
+    "get_session",
+    "select",
+]

astris/database/migrations.py

@@ -0,0 +1,259 @@
+import importlib
+import pkgutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from alembic import command
+from alembic.config import Config
+from alembic.runtime.migration import MigrationContext
+from alembic.script import ScriptDirectory
+
+from astris.database.session import db
+
+ENV_PY_TEMPLATE = """from astris.database.migrations import run_env
+
+run_env()
+"""
+
+SCRIPT_MAKO_TEMPLATE = '''"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: str | Sequence[str] | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}
+'''
+
+ALEMBIC_INI_TEMPLATE = """[alembic]
+script_location = database/migrations
+prepend_sys_path = .
+version_path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
+"""
+
+
+def discover_models(base_path: Path | None = None) -> None:
+    """Discover and import all domain model files to populate SQLModel.metadata."""
+    root = base_path or Path.cwd()
+    root_str = str(root)
+    if root_str not in sys.path:
+        sys.path.insert(0, root_str)
+
+    modules_dir = root / "app" / "modules"
+    if not modules_dir.exists():
+        return
+
+    for _, modname, ispkg in pkgutil.walk_packages(
+        [str(modules_dir)], prefix="app.modules."
+    ):
+        if ispkg:
+            continue
+        last_part = modname.split(".")[-1]
+        if last_part.endswith(("_model", "_models")) or last_part in (
+            "models",
+            "model",
+        ):
+            try:
+                importlib.import_module(modname)
+            except ImportError:
+                pass
+
+
+def ensure_migration_setup(base_path: Path | None = None) -> tuple[Path, Path]:
+    """Ensure alembic.ini and database/migrations/ directory structure exist."""
+    root = base_path or Path.cwd()
+    ini_path = root / "alembic.ini"
+    migrations_dir = root / "database" / "migrations"
+    versions_dir = migrations_dir / "versions"
+
+    migrations_dir.mkdir(parents=True, exist_ok=True)
+    versions_dir.mkdir(parents=True, exist_ok=True)
+
+    if not ini_path.exists():
+        ini_path.write_text(ALEMBIC_INI_TEMPLATE, encoding="utf-8")
+
+    env_path = migrations_dir / "env.py"
+    if not env_path.exists():
+        env_path.write_text(ENV_PY_TEMPLATE, encoding="utf-8")
+
+    mako_path = migrations_dir / "script.py.mako"
+    if not mako_path.exists():
+        mako_path.write_text(SCRIPT_MAKO_TEMPLATE, encoding="utf-8")
+
+    return ini_path, migrations_dir
+
+
+def get_alembic_config(base_path: Path | None = None) -> Config:
+    """Create and configure an Alembic Config object."""
+    root = base_path or Path.cwd()
+    ini_path, migrations_dir = ensure_migration_setup(root)
+
+    discover_models(root)
+
+    cfg = Config(str(ini_path))
+    cfg.set_main_option("script_location", str(migrations_dir))
+    cfg.set_main_option("sqlalchemy.url", db.url)
+    return cfg
+
+
+def create_migration(
+    message: str,
+    autogenerate: bool = True,
+    base_path: Path | None = None,
+) -> None:
+    """Generate a new database migration file."""
+    cfg = get_alembic_config(base_path)
+    command.revision(cfg, message=message, autogenerate=autogenerate)
+
+
+def run_migrations(
+    revision: str = "head",
+    base_path: Path | None = None,
+) -> None:
+    """Apply database migrations up to the target revision (default: 'head')."""
+    cfg = get_alembic_config(base_path)
+    command.upgrade(cfg, revision)
+
+
+def rollback_migrations(
+    revision: str = "-1",
+    base_path: Path | None = None,
+) -> None:
+    """Roll back database migrations down to the target revision (default: '-1')."""
+    cfg = get_alembic_config(base_path)
+    command.downgrade(cfg, revision)
+
+
+def get_migration_status(base_path: Path | None = None) -> dict[str, Any]:
+    """Retrieve the current migration revision and available heads."""
+    cfg = get_alembic_config(base_path)
+    script_dir = ScriptDirectory.from_config(cfg)
+    with db.engine.connect() as conn:
+        context = MigrationContext.configure(conn)
+        current_revs = context.get_current_heads()
+        heads = script_dir.get_heads()
+
+    return {
+        "current_revisions": list(current_revs),
+        "heads": list(heads),
+        "is_up_to_date": set(current_revs) == set(heads),
+    }
+
+
+def run_env(
+    target_metadata: Any = None,
+    base_path: Path | None = None,
+) -> None:
+    """Run migrations in offline or online mode.
+
+    Executed by database/migrations/env.py during Alembic migration runs.
+    """
+    from logging.config import fileConfig
+
+    from alembic import context
+    from sqlalchemy import engine_from_config, pool
+
+    from astris.database import SQLModel
+
+    root = base_path or Path.cwd()
+    root_str = str(root)
+    if root_str not in sys.path:
+        sys.path.insert(0, root_str)
+
+    discover_models(root)
+
+    config = context.config
+
+    if config.config_file_name is not None:
+        fileConfig(config.config_file_name)
+
+    metadata = target_metadata if target_metadata is not None else SQLModel.metadata
+
+    if context.is_offline_mode():
+        url = config.get_main_option("sqlalchemy.url")
+        is_sqlite = url and url.startswith("sqlite")
+        context.configure(
+            url=url,
+            target_metadata=metadata,
+            literal_binds=True,
+            dialect_opts={"paramstyle": "named"},
+            render_as_batch=bool(is_sqlite),
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+    else:
+        connectable = config.attributes.get("connection", None)
+        if connectable is None:
+            connectable = engine_from_config(
+                config.get_section(config.config_ini_section, {}),
+                prefix="sqlalchemy.",
+                poolclass=pool.NullPool,
+            )
+
+        with connectable.connect() as connection:
+            is_sqlite = connection.dialect.name == "sqlite"
+            context.configure(
+                connection=connection,
+                target_metadata=metadata,
+                render_as_batch=is_sqlite,
+            )
+
+            with context.begin_transaction():
+                context.run_migrations()

astris/database/session.py

@@ -0,0 +1,108 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import Depends
+from sqlalchemy import Engine
+from sqlmodel import Session, SQLModel, create_engine
+
+
+class Database:
+    """Manages the SQLModel engine and session lifecycle."""
+
+    def __init__(
+        self,
+        url: str | None = None,
+        echo: bool = False,
+        base_path: Path | None = None,
+        **engine_kwargs: Any,
+    ) -> None:
+        self._url = url
+        self._echo = echo
+        self._base_path = base_path or Path.cwd()
+        self._engine_kwargs = engine_kwargs
+        self._engine: Engine | None = None
+
+    @property
+    def url(self) -> str:
+        if self._url:
+            return self._url
+        from astris.config import get_settings
+
+        config_url = get_settings().database_url
+        if config_url:
+            return config_url
+
+        # Default to SQLite at database/app.db
+        db_dir = self._base_path / "database"
+        db_dir.mkdir(parents=True, exist_ok=True)
+        db_path = db_dir / "app.db"
+        return f"sqlite:///{db_path}"
+
+    @property
+    def engine(self) -> Engine:
+        if self._engine is not None:
+            return self._engine
+
+        connect_args: dict[str, Any] = {}
+        if self.url.startswith("sqlite"):
+            connect_args["check_same_thread"] = False
+
+        kwargs = {**self._engine_kwargs}
+        if connect_args:
+            kwargs["connect_args"] = {
+                **connect_args,
+                **kwargs.get("connect_args", {}),
+            }
+
+        engine = create_engine(self.url, echo=self._echo, **kwargs)
+        self._engine = engine
+        return engine
+
+    def configure(
+        self,
+        url: str | None = None,
+        echo: bool = False,
+        base_path: Path | None = None,
+        **engine_kwargs: Any,
+    ) -> None:
+        """Reconfigure database settings and reset the engine."""
+        self._url = url
+        self._echo = echo
+        if base_path:
+            self._base_path = base_path
+        self._engine_kwargs = engine_kwargs
+        self._engine = None
+
+    def create_all(self) -> None:
+        """Create all registered SQLModel tables."""
+        SQLModel.metadata.create_all(self.engine)
+
+    def drop_all(self) -> None:
+        """Drop all registered SQLModel tables."""
+        SQLModel.metadata.drop_all(self.engine)
+
+    def get_session(self) -> Generator[Session]:
+        """FastAPI dependency yielding a Session."""
+        with Session(self.engine) as session:
+            yield session
+
+    @contextmanager
+    def session(self) -> Generator[Session]:
+        """Context manager yielding a Session for background tasks, CLI, and scripts."""
+        with Session(self.engine) as session:
+            yield session
+
+
+# Global default database instance
+db = Database()
+
+
+def get_session() -> Generator[Session]:
+    """Astris dependency that yields a database session."""
+    yield from db.get_session()
+
+
+# First-class dependency injection alias for route & controller handlers
+DatabaseSession = Annotated[Session, Depends(get_session)]

astris/http/__init__.py

@@ -0,0 +1,25 @@
+from fastapi import BackgroundTasks, HTTPException, status
+from fastapi.requests import Request
+from fastapi.responses import (
+    FileResponse,
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    StreamingResponse,
+)
+
+__all__ = [
+    "BackgroundTasks",
+    "FileResponse",
+    "HTMLResponse",
+    "HTTPException",
+    "JSONResponse",
+    "PlainTextResponse",
+    "RedirectResponse",
+    "Request",
+    "Response",
+    "StreamingResponse",
+    "status",
+]

astris/http/static.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import FileResponse, Response
+from starlette.types import ASGIApp
+
+
+class PublicStaticMiddleware(BaseHTTPMiddleware):
+    """Serve physical static files directly from the public/ directory."""
+
+    def __init__(self, app: ASGIApp, public_dir: Path) -> None:
+        super().__init__(app)
+        self.public_dir = public_dir
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if request.method in ("GET", "HEAD"):
+            raw_path = request.url.path.lstrip("/")
+            if raw_path and not raw_path.startswith("build/"):
+                file_path = (self.public_dir / raw_path).resolve()
+                try:
+                    if file_path.is_file() and file_path.is_relative_to(
+                        self.public_dir
+                    ):
+                        return FileResponse(file_path)
+                except (ValueError, OSError):
+                    pass
+
+        return await call_next(request)

astris/inertia/__init__.py

@@ -0,0 +1,8 @@
+from astris.inertia.response import InertiaResponse
+from astris.inertia.shared import flash, share
+
+__all__ = [
+    "InertiaResponse",
+    "flash",
+    "share",
+]

astris/inertia/exceptions.py

@@ -0,0 +1,133 @@
+import json
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from starlette.responses import JSONResponse, RedirectResponse, Response
+
+
+def format_validation_errors(
+    exc: RequestValidationError | ValidationError,
+) -> dict[str, str]:
+    """Extract a clean, human-readable dictionary of field -> message from Pydantic validation errors."""
+    errors: dict[str, str] = {}
+    for error in exc.errors():
+        # Strip internal FastAPI/Pydantic location qualifiers like 'body', 'query', '__root__'
+        raw_loc = error.get("loc")
+        loc_parts: list[str] = []
+        if isinstance(raw_loc, (tuple, list)):
+            for part in raw_loc:
+                part_str = f"{part}"
+                if part_str not in (
+                    "body",
+                    "query",
+                    "header",
+                    "cookie",
+                    "path",
+                    "__root__",
+                ):
+                    loc_parts.append(part_str)
+
+        field = ".".join(loc_parts) if loc_parts else "non_field_errors"
+        if field not in errors:
+            msg = error.get("msg")
+            errors[field] = msg if isinstance(msg, str) else "Invalid value"
+    return errors
+
+
+def create_inertia_validation_response(
+    request: Request,
+    errors: dict[str, Any],
+) -> Response:
+    """Create an Inertia-compliant validation error response.
+
+    Returns a 303 redirect with flashed errors for state-changing form requests,
+    or a 422 JSON response with the X-Inertia header.
+    """
+    referer = request.headers.get("Referer")
+    if referer and request.method.upper() in ("POST", "PUT", "PATCH", "DELETE"):
+        if hasattr(request, "session"):
+            request.session["_errors"] = errors
+        response = RedirectResponse(url=referer, status_code=303)
+        response.set_cookie(
+            key="_inertia_errors",
+            value=quote(json.dumps(errors)),
+            path="/",
+            httponly=True,
+            samesite="lax",
+            max_age=10,
+        )
+        return response
+
+    return JSONResponse(
+        status_code=422,
+        content={"errors": errors},
+        headers={"X-Inertia": "true"},
+    )
+
+
+async def inertia_validation_exception_handler(
+    request: Request,
+    exc: Exception,
+) -> Response:
+    """Handle validation errors for Inertia requests by returning an Inertia-compliant
+
+    303 redirect with session errors, or a standard 422 JSON response for API consumers.
+    """
+    if isinstance(exc, (RequestValidationError, ValidationError)):
+        errors = format_validation_errors(exc)
+        detail = exc.errors()
+    else:
+        errors = {"non_field_errors": "Validation error"}
+        detail = [{"msg": "Validation error", "type": "value_error"}]
+
+    is_inertia = request.headers.get("X-Inertia") == "true"
+
+    if is_inertia:
+        return create_inertia_validation_response(request, errors)
+
+    return JSONResponse(
+        status_code=422,
+        content={"detail": detail, "errors": errors},
+    )
+
+
+async def inertia_http_exception_handler(
+    request: Request,
+    exc: Exception,
+) -> Response:
+    """Handle HTTPExceptions for Inertia and standard API requests.
+
+    Formats 422 unprocessable entity errors as Inertia-compliant 303 redirects or {"errors": {...}}
+    responses with the X-Inertia header, so frontend form validation states update seamlessly.
+    """
+    is_inertia = request.headers.get("X-Inertia") == "true"
+    status_code = getattr(exc, "status_code", 500)
+    detail = getattr(exc, "detail", "An error occurred")
+
+    if is_inertia and status_code == 422:
+        if isinstance(detail, dict):
+            errors = {str(k): str(v) for k, v in detail.items()}
+        elif isinstance(detail, list):
+            errors = {}
+            for item in detail:
+                if isinstance(item, dict):
+                    loc = item.get("loc", ["non_field_errors"])[-1]
+                    errors[str(loc)] = str(item.get("msg", "Invalid value"))
+                else:
+                    errors["non_field_errors"] = str(item)
+        elif isinstance(detail, str):
+            errors = {"non_field_errors": detail}
+        else:
+            errors = {"non_field_errors": "Validation error"}
+
+        return create_inertia_validation_response(request, errors)
+
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(
+        status_code=status_code,
+        content={"detail": detail},
+        headers=headers,
+    )