austial 0.1.1__py3-none-any.whl

austial/__init__.py

@@ -0,0 +1,136 @@
+"""Austial -- a NestJS-inspired, batteries-included web framework for Python,
+built on top of FastAPI.
+
+Quickstart::
+
+    from austial import Module, Controller, Get, Injectable, AustialFactory
+
+Most day-to-day symbols (decorators, exceptions, guards, etc.) are re-exported
+here for convenience, mirroring how ``@nestjs/common`` re-exports everything
+Nest apps need. Deeper framework internals live in ``austial.core``,
+``austial.config``, ``austial.database``, ``austial.terminus``,
+``austial.testing`` and ``austial.cli``.
+"""
+
+from austial.common import (
+    AllExceptionsFilter,
+    ArgumentMetadata,
+    ArgumentsHost,
+    BadRequestException,
+    Body,
+    CallHandler,
+    CanActivate,
+    Catch,
+    ConflictException,
+    Controller,
+    Delete,
+    ExceptionFilter,
+    ExecutionContext,
+    ForbiddenException,
+    Get,
+    Global,
+    Head,
+    Header,
+    Headers,
+    HttpCode,
+    HttpException,
+    Inject,
+    Injectable,
+    InternalServerErrorException,
+    Logger,
+    LoggingMiddleware,
+    MethodNotAllowedException,
+    MiddlewareConsumer,
+    Module,
+    NestInterceptor,
+    NestMiddleware,
+    NotFoundException,
+    NotImplementedException,
+    Optional_,
+    Options,
+    Param,
+    Patch,
+    PipeTransform,
+    Post,
+    Put,
+    Query,
+    Req,
+    Res,
+    Scope,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    TransformInterceptor,
+    UnauthorizedException,
+    UnprocessableEntityException,
+    UseFilters,
+    UseGuards,
+    UseInterceptors,
+    UsePipes,
+    ValidationPipe,
+)
+from austial.core import DynamicModule, Reflector
+from austial.core.app import AustialApplication
+from austial.core.factory import AustialFactory
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AllExceptionsFilter",
+    "ArgumentMetadata",
+    "ArgumentsHost",
+    "AustialApplication",
+    "AustialFactory",
+    "BadRequestException",
+    "Body",
+    "CallHandler",
+    "CanActivate",
+    "Catch",
+    "ConflictException",
+    "Controller",
+    "Delete",
+    "DynamicModule",
+    "ExceptionFilter",
+    "ExecutionContext",
+    "ForbiddenException",
+    "Get",
+    "Global",
+    "Head",
+    "Header",
+    "Headers",
+    "HttpCode",
+    "HttpException",
+    "Inject",
+    "Injectable",
+    "InternalServerErrorException",
+    "Logger",
+    "LoggingMiddleware",
+    "MethodNotAllowedException",
+    "MiddlewareConsumer",
+    "Module",
+    "NestInterceptor",
+    "NestMiddleware",
+    "NotFoundException",
+    "NotImplementedException",
+    "Options",
+    "Optional_",
+    "Param",
+    "Patch",
+    "PipeTransform",
+    "Post",
+    "Put",
+    "Query",
+    "Reflector",
+    "Req",
+    "Res",
+    "Scope",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "TransformInterceptor",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "UseFilters",
+    "UseGuards",
+    "UseInterceptors",
+    "UsePipes",
+    "ValidationPipe",
+]

austial/cli/generators/__init__.py

@@ -0,0 +1,13 @@
+from austial.cli.generators.controller_gen import generate_controller
+from austial.cli.generators.module_gen import generate_module
+from austial.cli.generators.new_project import create_new_project
+from austial.cli.generators.resource_gen import generate_resource
+from austial.cli.generators.service_gen import generate_service
+
+__all__ = [
+    "create_new_project",
+    "generate_controller",
+    "generate_module",
+    "generate_resource",
+    "generate_service",
+]

austial/cli/generators/app_module_patcher.py

@@ -0,0 +1,61 @@
+"""Best-effort patcher that registers a newly generated module into the
+nearest ``app_module.py``, mirroring how the real ``nest`` CLI updates
+``app.module.ts`` after ``nest g module``/``nest g resource``.
+
+Text-based and intentionally conservative: if the file doesn't look like what
+`austial new`/`austial generate` produce, it leaves it alone and tells the
+caller so a manual edit instruction can be printed instead.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_IMPORTS_ARRAY_RE = re.compile(r"imports\s*=\s*\[(.*?)\]", re.DOTALL)
+
+
+def register_module(app_module_path: Path, class_name: str, import_line: str) -> bool:
+    """Returns True if the patch was applied, False if it was already present
+    or the file couldn't be safely patched."""
+    text = app_module_path.read_text()
+
+    if import_line in text:
+        return False  # already registered, nothing to do
+
+    lines = text.splitlines()
+
+    # Group the new import with its isort "block" (contiguous run of
+    # from/import lines sharing the same top-level package as `import_line`,
+    # e.g. all `from src...` lines) and re-sort that block alphabetically, so
+    # the patched file stays isort-clean instead of just tacking the new line
+    # onto the end of the whole import section.
+    package = import_line.split()[1].split(".")[0]
+    prefixes = (f"from {package}.", f"import {package}.")
+    block_indices = [i for i, line in enumerate(lines) if line.startswith(prefixes)]
+
+    if block_indices:
+        first, last = block_indices[0], block_indices[-1]
+        block = [lines[i] for i in block_indices] + [import_line]
+        block = sorted(set(block))
+        lines[first : last + 1] = block
+    else:
+        last_import_idx = 0
+        for i, line in enumerate(lines):
+            if line.startswith("from ") or line.startswith("import "):
+                last_import_idx = i
+        lines.insert(last_import_idx + 1, import_line)
+
+    text = "\n".join(lines) + "\n"
+
+    match = _IMPORTS_ARRAY_RE.search(text)
+    if not match:
+        app_module_path.write_text(text)
+        return False
+
+    inner = match.group(1)
+    new_inner = f"{inner.rstrip()}, {class_name}" if inner.strip() else class_name
+    text = text[: match.start(1)] + new_inner + text[match.end(1) :]
+
+    app_module_path.write_text(text)
+    return True

austial/cli/generators/base.py

@@ -0,0 +1,61 @@
+"""Shared helpers for every generator: template rendering + project-root
+discovery, mirroring what the ``nest`` CLI's schematics engine does."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader
+
+TEMPLATES_DIR = Path(__file__).resolve().parent.parent / "templates"
+
+_env = Environment(
+    loader=FileSystemLoader(str(TEMPLATES_DIR)),
+    keep_trailing_newline=True,
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+def render(template_relpath: str, **context: Any) -> str:
+    template = _env.get_template(template_relpath)
+    return template.render(**context)
+
+
+def write_file(path: Path, content: str, *, force: bool = False) -> bool:
+    """Writes `content` to `path`, creating parent directories as needed.
+    Returns False (and leaves the file untouched) if it already exists and
+    `force` wasn't given -- mirrors `nest g`'s "already exists" guard."""
+    if path.exists() and not force:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return True
+
+
+def ensure_package_init(directory: Path) -> None:
+    """Creates an empty ``__init__.py`` in `directory` (and does *not* recurse
+    -- callers create the full chain explicitly) if one doesn't exist yet."""
+    init_file = directory / "__init__.py"
+    if not init_file.exists():
+        directory.mkdir(parents=True, exist_ok=True)
+        init_file.write_text("")
+
+
+class ProjectNotFoundError(Exception):
+    pass
+
+
+def find_project_root(start: Path | None = None) -> Path:
+    """Walks upward from `start` (default: cwd) looking for `src/app_module.py`,
+    the marker of an Austial project root."""
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / "src" / "app_module.py").exists():
+            return candidate
+    raise ProjectNotFoundError(
+        "Couldn't find an Austial project in this or any parent directory "
+        "(looked for `src/app_module.py`). Run this inside a project created "
+        "with `austial new`, or create `src/app_module.py` by hand first."
+    )

austial/cli/generators/controller_gen.py

@@ -0,0 +1,21 @@
+"""``austial generate controller <name>`` -- mirrors ``nest g controller``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from austial.cli.generators.base import find_project_root, render, write_file
+from austial.cli.naming import to_kebab_case, to_pascal_case, to_snake_case
+
+
+def generate_controller(name: str, *, project_root: Path | None = None) -> Path:
+    root = project_root or find_project_root()
+    snake_name = to_snake_case(name)
+    class_name = to_pascal_case(name)
+    ctx = {"snake_name": snake_name, "class_name": class_name, "kebab_name": to_kebab_case(name)}
+
+    module_dir = root / "src" / "modules" / snake_name
+    write_file(module_dir / "__init__.py", "")
+    file_path = module_dir / f"{snake_name}_controller.py"
+    write_file(file_path, render("controller/controller.py.j2", **ctx))
+    return file_path

austial/cli/generators/module_gen.py

@@ -0,0 +1,30 @@
+"""``austial generate module <name>`` -- mirrors ``nest g module``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from austial.cli.generators.app_module_patcher import register_module
+from austial.cli.generators.base import find_project_root, render, write_file
+from austial.cli.naming import to_kebab_case, to_pascal_case, to_snake_case
+
+
+def generate_module(name: str, *, project_root: Path | None = None) -> Path:
+    root = project_root or find_project_root()
+    snake_name = to_snake_case(name)
+    class_name = to_pascal_case(name)
+    ctx = {"snake_name": snake_name, "class_name": class_name, "kebab_name": to_kebab_case(name)}
+
+    module_dir = root / "src" / "modules" / snake_name
+    write_file(module_dir / "__init__.py", "")
+    file_path = module_dir / f"{snake_name}_module.py"
+    write_file(file_path, render("module/module.py.j2", **ctx))
+
+    app_module_path = root / "src" / "app_module.py"
+    if app_module_path.exists():
+        register_module(
+            app_module_path,
+            f"{class_name}Module",
+            f"from src.modules.{snake_name}.{snake_name}_module import {class_name}Module",
+        )
+    return file_path

austial/cli/generators/new_project.py

@@ -0,0 +1,67 @@
+"""``austial new <name>`` -- mirrors ``nest new <name>``."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from austial.cli.generators.base import render, write_file
+from austial.cli.naming import to_kebab_case
+
+
+def create_new_project(
+    name: str,
+    *,
+    directory: Path | None = None,
+    austial_source_path: str | None = None,
+    skip_install: bool = False,
+    skip_git: bool = False,
+) -> Path:
+    project_dir = (directory or Path.cwd() / name).resolve()
+    project_slug = to_kebab_case(name)
+    ctx = {"project_name": name, "project_slug": project_slug, "austial_source_path": austial_source_path}
+
+    write_file(project_dir / "pyproject.toml", render("project/pyproject.toml.j2", **ctx))
+    write_file(project_dir / "README.md", render("project/readme.j2", **ctx))
+    write_file(project_dir / ".env.example", render("project/env_example.j2", **ctx))
+    write_file(project_dir / ".gitignore", render("project/gitignore.j2", **ctx))
+    write_file(project_dir / ".pre-commit-config.yaml", render("project/pre_commit_config.yaml.j2", **ctx))
+
+    write_file(project_dir / "src" / "__init__.py", "")
+    write_file(project_dir / "src" / "main.py", render("project/main.py.j2", **ctx))
+    write_file(project_dir / "src" / "app_module.py", render("project/app_module.py.j2", **ctx))
+    write_file(project_dir / "src" / "app_controller.py", render("project/app_controller.py.j2", **ctx))
+    write_file(project_dir / "src" / "app_service.py", render("project/app_service.py.j2", **ctx))
+
+    write_file(project_dir / "src" / "modules" / "__init__.py", "")
+    health_dir = project_dir / "src" / "modules" / "health"
+    write_file(health_dir / "__init__.py", "")
+    write_file(health_dir / "health_module.py", render("project/modules/health/health_module.py.j2", **ctx))
+    write_file(health_dir / "health_controller.py", render("project/modules/health/health_controller.py.j2", **ctx))
+    write_file(health_dir / "health_service.py", render("project/modules/health/health_service.py.j2", **ctx))
+    write_file(health_dir / "health_dto.py", render("project/modules/health/health_dto.py.j2", **ctx))
+    write_file(health_dir / "guards" / "__init__.py", "")
+    write_file(
+        health_dir / "guards" / "api_key_guard.py",
+        render("project/modules/health/guards/api_key_guard.py.j2", **ctx),
+    )
+
+    write_file(project_dir / "tests" / "__init__.py", "")
+    write_file(project_dir / "tests" / "unit" / "__init__.py", "")
+    write_file(project_dir / "tests" / "e2e" / "__init__.py", "")
+    write_file(
+        project_dir / "tests" / "unit" / "health_service_spec.py",
+        render("project/tests/unit/health_service_spec.py.j2", **ctx),
+    )
+    write_file(
+        project_dir / "tests" / "e2e" / "app_e2e_spec.py",
+        render("project/tests/e2e/app_e2e_spec.py.j2", **ctx),
+    )
+
+    if not skip_git:
+        subprocess.run(["git", "init", "-q"], cwd=project_dir, check=False)
+
+    if not skip_install:
+        subprocess.run(["uv", "sync"], cwd=project_dir, check=False)
+
+    return project_dir

austial/cli/generators/resource_gen.py

@@ -0,0 +1,39 @@
+"""``austial generate resource <name>`` -- mirrors ``nest g resource``:
+scaffolds a full CRUD module (module + controller + service + dto + entity)
+in one shot and registers it into the nearest ``app_module.py``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from austial.cli.generators.app_module_patcher import register_module
+from austial.cli.generators.base import find_project_root, render, write_file
+from austial.cli.naming import to_kebab_case, to_pascal_case, to_snake_case
+
+
+def generate_resource(name: str, *, project_root: Path | None = None) -> Path:
+    root = project_root or find_project_root()
+    snake_name = to_snake_case(name)
+    class_name = to_pascal_case(name)
+    ctx = {"snake_name": snake_name, "class_name": class_name, "kebab_name": to_kebab_case(name)}
+
+    module_dir = root / "src" / "modules" / snake_name
+    write_file(module_dir / "__init__.py", "")
+    write_file(module_dir / "dto" / "__init__.py", "")
+    write_file(module_dir / "entities" / "__init__.py", "")
+
+    write_file(module_dir / "entities" / f"{snake_name}_entity.py", render("resource/entity.py.j2", **ctx))
+    write_file(module_dir / "dto" / f"create_{snake_name}_dto.py", render("resource/create_dto.py.j2", **ctx))
+    write_file(module_dir / "dto" / f"update_{snake_name}_dto.py", render("resource/update_dto.py.j2", **ctx))
+    write_file(module_dir / f"{snake_name}_service.py", render("resource/service.py.j2", **ctx))
+    write_file(module_dir / f"{snake_name}_controller.py", render("resource/controller.py.j2", **ctx))
+    write_file(module_dir / f"{snake_name}_module.py", render("resource/module.py.j2", **ctx))
+
+    app_module_path = root / "src" / "app_module.py"
+    if app_module_path.exists():
+        register_module(
+            app_module_path,
+            f"{class_name}Module",
+            f"from src.modules.{snake_name}.{snake_name}_module import {class_name}Module",
+        )
+    return module_dir / f"{snake_name}_module.py"

austial/cli/generators/service_gen.py

@@ -0,0 +1,21 @@
+"""``austial generate service <name>`` -- mirrors ``nest g service``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from austial.cli.generators.base import find_project_root, render, write_file
+from austial.cli.naming import to_kebab_case, to_pascal_case, to_snake_case
+
+
+def generate_service(name: str, *, project_root: Path | None = None) -> Path:
+    root = project_root or find_project_root()
+    snake_name = to_snake_case(name)
+    class_name = to_pascal_case(name)
+    ctx = {"snake_name": snake_name, "class_name": class_name, "kebab_name": to_kebab_case(name)}
+
+    module_dir = root / "src" / "modules" / snake_name
+    write_file(module_dir / "__init__.py", "")
+    file_path = module_dir / f"{snake_name}_service.py"
+    write_file(file_path, render("service/service.py.j2", **ctx))
+    return file_path

austial/cli/main.py

@@ -0,0 +1,133 @@
+"""``austial`` -- the CLI, mirrors the ``nest`` command.
+
+austial new my-app
+austial generate module cats      (alias: austial g module cats)
+austial generate controller cats
+austial generate service cats
+austial generate resource cats
+austial serve
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from austial.cli.generators import (
+    create_new_project,
+    generate_controller,
+    generate_module,
+    generate_resource,
+    generate_service,
+)
+from austial.cli.generators.base import ProjectNotFoundError, find_project_root
+
+console = Console()
+app = typer.Typer(
+    name="austial",
+    help="Austial CLI -- scaffold and run NestJS-style Python projects, built on FastAPI.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+_SCHEMATICS = {
+    "module": generate_module,
+    "controller": generate_controller,
+    "service": generate_service,
+    "resource": generate_resource,
+}
+
+
+@app.command("new")
+def new_project(
+    name: str = typer.Argument(..., help="Name of the new project/directory to create."),
+    directory: str | None = typer.Option(None, "--directory", "-d", help="Target directory (defaults to ./<name>)."),
+    skip_install: bool = typer.Option(False, "--skip-install", help="Don't run `uv sync` after scaffolding."),
+    skip_git: bool = typer.Option(False, "--skip-git", help="Don't run `git init` after scaffolding."),
+    link: str | None = typer.Option(
+        None,
+        "--link",
+        help="Path to a local Austial framework checkout to depend on via `uv`'s editable path sources "
+        "(useful before the framework is published to PyPI).",
+    ),
+) -> None:
+    """Scaffold a brand-new Austial project -- mirrors `nest new <name>`."""
+    console.print(f"[bold green]CREATE[/bold green] {name}/ ...")
+    target = Path(directory).resolve() if directory else None
+    project_dir = create_new_project(
+        name,
+        directory=target,
+        austial_source_path=link,
+        skip_install=skip_install,
+        skip_git=skip_git,
+    )
+    console.print(f"[bold green]\u2714[/bold green] Project created at [bold]{project_dir}[/bold]")
+    console.print("\nNext steps:")
+    console.print(f"  cd {project_dir.name}")
+    if skip_install:
+        console.print("  uv sync")
+    console.print("  cp .env.example .env")
+    console.print("  uv run austial serve\n")
+
+
+def _generate(schematic: str, name: str) -> None:
+    schematic = schematic.lower()
+    if schematic not in _SCHEMATICS:
+        console.print(f"[bold red]Unknown schematic[/bold red] '{schematic}'. Choose one of: {', '.join(_SCHEMATICS)}.")
+        raise typer.Exit(code=1)
+    try:
+        path = _SCHEMATICS[schematic](name)
+    except ProjectNotFoundError as exc:
+        console.print(f"[bold red]\u2716[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+    console.print(f"[bold green]CREATE[/bold green] {path}")
+
+
+@app.command("generate")
+def generate(
+    schematic: str = typer.Argument(..., help="One of: module, controller, service, resource"),
+    name: str = typer.Argument(..., help="Name for the generated artifact, e.g. 'cats'."),
+) -> None:
+    """Generate a module/controller/service/resource -- mirrors `nest generate`."""
+    _generate(schematic, name)
+
+
+@app.command("g", hidden=True)
+def generate_alias(
+    schematic: str = typer.Argument(..., help="One of: module, controller, service, resource"),
+    name: str = typer.Argument(..., help="Name for the generated artifact, e.g. 'cats'."),
+) -> None:
+    """Alias for `generate` -- mirrors Nest CLI's `nest g`."""
+    _generate(schematic, name)
+
+
+@app.command("serve")
+def serve(
+    host: str = typer.Option("0.0.0.0", help="Bind host."),
+    port: int = typer.Option(8000, help="Bind port."),
+    reload: bool = typer.Option(True, help="Auto-reload on file changes (dev mode)."),
+) -> None:
+    """Runs the current project (mirrors `nest start --watch`)."""
+    import uvicorn
+
+    try:
+        project_root = find_project_root()
+    except ProjectNotFoundError as exc:
+        console.print(f"[bold red]\u2716[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    import sys
+
+    sys.path.insert(0, str(project_root))
+    console.print(f"[bold green]\u25b6[/bold green] Serving {project_root.name} on http://{host}:{port}")
+    uvicorn.run("src.main:app", host=host, port=port, reload=reload, app_dir=str(project_root))
+
+
+def run() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    run()

austial/cli/naming.py

@@ -0,0 +1,33 @@
+"""Naming helpers shared by every generator -- turns whatever the user typed
+(``cats``, ``cat-breed``, ``CatBreed``, ``cat_breed``) into the forms needed
+for file names, class names and route prefixes, mirroring how ``nest g``
+normalizes its ``<name>`` argument."""
+
+from __future__ import annotations
+
+import re
+
+_BOUNDARY_RE = re.compile(r"[-_\s]+|(?<=[a-z0-9])(?=[A-Z])")
+
+
+def _words(name: str) -> list[str]:
+    return [w for w in _BOUNDARY_RE.split(name.strip()) if w]
+
+
+def to_snake_case(name: str) -> str:
+    return "_".join(w.lower() for w in _words(name))
+
+
+def to_kebab_case(name: str) -> str:
+    return "-".join(w.lower() for w in _words(name))
+
+
+def to_pascal_case(name: str) -> str:
+    return "".join(w.capitalize() for w in _words(name))
+
+
+def to_camel_case(name: str) -> str:
+    words = _words(name)
+    if not words:
+        return name
+    return words[0].lower() + "".join(w.capitalize() for w in words[1:])

austial/cli/templates/controller/controller.py.j2

@@ -0,0 +1,8 @@
+from austial import Controller, Get
+
+
+@Controller("{{ kebab_name }}")
+class {{ class_name }}Controller:
+    @Get()
+    async def find_all(self):
+        return []

austial/cli/templates/module/module.py.j2

@@ -0,0 +1,6 @@
+from austial import Module
+
+
+@Module()
+class {{ class_name }}Module:
+    pass

austial/cli/templates/project/app_controller.py.j2

@@ -0,0 +1,13 @@
+from austial import Controller, Get
+
+from src.app_service import AppService
+
+
+@Controller()
+class AppController:
+    def __init__(self, app_service: AppService):
+        self.app_service = app_service
+
+    @Get()
+    async def get_hello(self):
+        return self.app_service.get_hello()

austial/cli/templates/project/app_module.py.j2

@@ -0,0 +1,19 @@
+"""Root application module -- mirrors Nest's ``src/app.module.ts``."""
+
+from austial import Module
+from austial.common.middleware import LoggingMiddleware, MiddlewareConsumer
+from austial.config import ConfigModule
+
+from src.app_controller import AppController
+from src.app_service import AppService
+from src.modules.health.health_module import HealthModule
+
+
+@Module(
+    imports=[ConfigModule.for_root(), HealthModule],
+    controllers=[AppController],
+    providers=[AppService],
+)
+class AppModule:
+    def configure(self, consumer: MiddlewareConsumer) -> None:
+        consumer.apply(LoggingMiddleware).for_routes("*")