FastAPI-fastkit 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

fastapi_fastkit/backend/route_generators.py

@@ -0,0 +1,163 @@
+# --------------------------------------------------------------------------
+# Route generators for fastkit addroute.
+# --------------------------------------------------------------------------
+import keyword
+import os
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+from fastapi_fastkit.backend import main as backend
+from fastapi_fastkit.backend.project_builder.preset_layout import PresetLayoutStrategist
+from fastapi_fastkit.backend.route_wiring import register_router, router_alias
+from fastapi_fastkit.backend.transducer import copy_and_convert_template_file
+from fastapi_fastkit.core.exceptions import BackendExceptions
+from fastapi_fastkit.core.settings import settings
+from fastapi_fastkit.utils.main import print_warning, read_fastkit_metadata
+
+ROUTE_LAYOUTS = ("classic-layer", "domain")
+
+
+def resolve_route_layout(project_dir: str, layout: Optional[str] = None) -> str:
+    """Resolve the route layout from the option or project metadata."""
+    if layout is not None:
+        if layout not in ROUTE_LAYOUTS:
+            raise BackendExceptions(f"Unknown route layout: {layout!r}")
+        return layout
+
+    metadata = read_fastkit_metadata(project_dir)
+    preset = metadata.get("preset")
+    if not preset:
+        template = metadata.get("template")
+        domain_template = PresetLayoutStrategist("domain-starter").base_template
+        if template == domain_template:
+            return "domain"
+    if preset == "domain-starter":
+        return "domain"
+    if preset and preset not in ("classic-layered", "minimal", "single-module"):
+        print_warning(f"Unknown preset {preset!r}; using classic-layer route layout.")
+    return "classic-layer"
+
+
+def _validate_route_name(route_name: str) -> None:
+    """Validate the route module name."""
+    if not route_name.isidentifier() or keyword.iskeyword(route_name):
+        raise BackendExceptions(f"Route name {route_name!r} is not a Python identifier")
+
+
+class ClassicLayeredRouteGenerator:
+    """Generate api/routes, crud, and schemas modules."""
+
+    def add_new_route(
+        self, project_dir: str, route_name: str, project_layout: Dict[str, str]
+    ) -> None:
+        """Create route files and register the router."""
+        src_dir = project_layout["package_dir"]
+        _validate_route_name(route_name)
+        modules_dir = os.path.join(settings.FASTKIT_TEMPLATE_ROOT, "modules")
+        target_dirs = backend._ensure_project_structure(src_dir)
+        backend._create_route_files(
+            modules_dir, target_dirs, route_name, project_layout["package_module"]
+        )
+        backend._handle_api_router_file(
+            target_dirs, modules_dir, route_name, project_layout["api_router_file"]
+        )
+        backend._process_init_files(
+            modules_dir, target_dirs, ["api/routes", "crud", "schemas"]
+        )
+        backend._update_main_app(
+            src_dir,
+            route_name,
+            router_module=project_layout["api_router_module"],
+            main_py_path=project_layout["main"],
+        )
+
+
+class DomainRouteGenerator:
+    """Generate a domain module."""
+
+    def add_new_route(
+        self, project_dir: str, route_name: str, project_layout: Dict[str, str]
+    ) -> None:
+        """Create domain files and register the router."""
+        package = Path(project_layout["package_dir"])
+        _validate_route_name(route_name)
+        if not package.is_dir():
+            raise BackendExceptions(f"Source directory not found at {package}")
+
+        domain_module = _create_domain_files(package, route_name, project_layout)
+        alias = router_alias(
+            project_layout["api_router_file"],
+            domain_module,
+            "router",
+            f"{route_name}_router",
+        )
+        register_router(
+            project_layout,
+            f"from {domain_module} import router as {alias}",
+            f'api_router.include_router({alias}.router, prefix="/{route_name}", tags=["{route_name}"])',
+        )
+        backend._update_main_app(
+            str(package),
+            route_name,
+            router_module=project_layout["api_router_module"],
+            main_py_path=project_layout["main"],
+        )
+
+
+def _create_domain_files(
+    package: Path, route_name: str, project_layout: Dict[str, str]
+) -> str:
+    templates = Path(settings.FASTKIT_TEMPLATE_ROOT) / "modules" / "domain"
+    filenames = (
+        "__init__.py",
+        "models.py",
+        "schemas.py",
+        "repository.py",
+        "service.py",
+        "router.py",
+    )
+    for filename in filenames:
+        if not (templates / f"{filename}-tpl").is_file():
+            raise BackendExceptions(f"Missing domain template: {filename}-tpl")
+
+    domain_dir = package / "domains" / route_name
+    domain_dir.mkdir(parents=True, exist_ok=True)
+    domains_init = domain_dir.parent / "__init__.py"
+    if not domains_init.exists():
+        domains_init.write_text("", encoding="utf-8")
+    prefix = project_layout["package_module"]
+    domain_module = (
+        f"{prefix}.domains.{route_name}" if prefix else f"domains.{route_name}"
+    )
+    entity_class = (
+        "".join(part[:1].upper() + part[1:] for part in route_name.split("_")) or "_"
+    )
+    if keyword.iskeyword(entity_class):
+        entity_class += "Entity"
+    replacements = {
+        "<new_route>": route_name,
+        "<domain_module>": domain_module,
+        "<entity_class>": entity_class,
+    }
+    for filename in filenames:
+        target = domain_dir / filename
+        if target.exists():
+            print_warning(f"File {target} already exists, skipping...")
+            continue
+        if not copy_and_convert_template_file(
+            str(templates / f"{filename}-tpl"), str(target), replacements
+        ):
+            raise BackendExceptions(f"Failed to create domain file: {target}")
+
+    return domain_module
+
+
+def get_route_generator(
+    route_layout: str,
+) -> Union[ClassicLayeredRouteGenerator, DomainRouteGenerator]:
+    """Return the generator for the selected layout."""
+    if route_layout == "classic-layer":
+        return ClassicLayeredRouteGenerator()
+    if route_layout == "domain":
+        return DomainRouteGenerator()
+    raise BackendExceptions(f"Unknown route layout: {route_layout!r}")

fastapi_fastkit/backend/route_wiring.py

@@ -0,0 +1,117 @@
+"""Router registration helpers."""
+
+import ast
+from pathlib import Path
+from typing import Dict
+
+from fastapi_fastkit.utils.main import print_info
+
+
+def _parse_module(content: str) -> ast.Module:
+    try:
+        return ast.parse(content)
+    except SyntaxError:
+        statements: list[ast.stmt] = []
+        for line in content.splitlines():
+            try:
+                statements.extend(ast.parse(line.strip()).body)
+            except SyntaxError:
+                continue
+        return ast.Module(body=statements, type_ignores=[])
+
+
+def _router_argument(call: ast.Call) -> ast.expr | None:
+    if call.args:
+        return call.args[0]
+    return next((item.value for item in call.keywords if item.arg == "router"), None)
+
+
+def register_router(
+    project_layout: Dict[str, str], import_line: str, statement: str
+) -> None:
+    """Register a router in the API router module."""
+
+    from fastapi_fastkit.backend.main import insert_import_line, insert_statement_line
+
+    api_dir = Path(project_layout["api_dir"])
+    api_dir.mkdir(parents=True, exist_ok=True)
+    init = api_dir / "__init__.py"
+    if not init.exists():
+        init.write_text("", encoding="utf-8")
+    target = Path(project_layout["api_router_file"])
+    content = target.read_text(encoding="utf-8") if target.exists() else ""
+    if not content.strip():
+        content = "from fastapi import APIRouter\n\napi_router = APIRouter()\n"
+    registration = ast.parse(statement).body[0]
+    existing = None
+    if isinstance(registration, ast.Expr) and isinstance(registration.value, ast.Call):
+        expected = registration.value
+        expected_router = _router_argument(expected)
+        existing = next(
+            (
+                node
+                for node in ast.walk(_parse_module(content))
+                if isinstance(node, ast.Call)
+                and ast.dump(node.func) == ast.dump(expected.func)
+                and (argument := _router_argument(node)) is not None
+                and expected_router is not None
+                and ast.dump(argument) == ast.dump(expected_router)
+            ),
+            None,
+        )
+        if existing is not None:
+            current_options = {
+                item.arg: ast.dump(item.value)
+                for item in existing.keywords
+                if item.arg != "router"
+            }
+            expected_options = {
+                item.arg: ast.dump(item.value)
+                for item in expected.keywords
+                if item.arg != "router"
+            }
+            if (
+                current_options != expected_options
+                or existing.args[1:] != expected.args[1:]
+            ):
+                print_info(
+                    f"Keeping existing router registration in {target} with its current prefix and options."
+                )
+    updated = insert_import_line(content, import_line)
+    if existing is None:
+        updated = insert_statement_line(updated, statement)
+    if not target.exists() or updated != content:
+        target.write_text(updated, encoding="utf-8")
+
+
+def router_alias(file: str, module: str, name: str, preferred: str) -> str:
+    """Reuse the router import alias or choose an unused name."""
+
+    target = Path(file)
+    if not target.exists():
+        return preferred
+    tree = _parse_module(target.read_text(encoding="utf-8"))
+    occupied: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom):
+            for imported in node.names:
+                if node.module == module and imported.name == name:
+                    return imported.asname or name
+                occupied.add(imported.asname or imported.name)
+        elif isinstance(node, ast.Import):
+            occupied.update(
+                item.asname or item.name.split(".")[0] for item in node.names
+            )
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            occupied.add(node.name)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            occupied.update(
+                target.id for target in targets if isinstance(target, ast.Name)
+            )
+    alias = preferred
+    counter = 2
+    while alias in occupied:
+        alias = f"{preferred}_{counter}"
+        counter += 1
+    return alias

fastapi_fastkit/backend/transducer.py

@@ -22,6 +22,104 @@ logger = get_logger(__name__)
 #: here are the *converted* names (the ``-tpl`` marker already stripped).
 TEMPLATE_ONLY_FILES = frozenset({"template-config.yml"})
 
+#: Extensions of files that are known to be text and therefore safe to rewrite
+#: with Unix line endings. Anything outside this list is copied byte for byte,
+#: so an image or an archive shipped inside a template survives untouched.
+TEXT_FILE_EXTENSIONS = frozenset(
+    {
+        ".bash",
+        ".cfg",
+        ".css",
+        ".env",
+        ".html",
+        ".ini",
+        ".js",
+        ".json",
+        ".mako",
+        ".md",
+        ".py",
+        ".rst",
+        ".sh",
+        ".sql",
+        ".toml",
+        ".ts",
+        ".txt",
+        ".yaml",
+        ".yml",
+    }
+)
+
+#: Extension-less file names that are text as well.
+TEXT_FILE_NAMES = frozenset(
+    {
+        ".dockerignore",
+        ".env",
+        ".gitignore",
+        "CHANGELOG",
+        "Dockerfile",
+        "LICENSE",
+        "Makefile",
+        "Procfile",
+        "README",
+    }
+)
+
+#: How much of a file is sampled when looking for a NUL byte. A NUL in the
+#: first chunk is the same heuristic Git uses to call a blob binary.
+BINARY_SNIFF_BYTES = 8192
+
+
+def _looks_like_text_file(file_path: str, file_name: str) -> bool:
+    """
+    Decide whether a copied file may have its line endings normalised.
+
+    The check is deliberately conservative: the name has to be on the text
+    whitelist *and* the content must carry no NUL byte, so a mislabelled
+    binary is left alone rather than corrupted.
+
+    :param file_path: Path of the file to inspect
+    :param file_name: File name used for the extension/name whitelist
+    :return: True when the file is safe to rewrite as text
+    """
+    _, extension = os.path.splitext(file_name)
+    if (
+        extension.lower() not in TEXT_FILE_EXTENSIONS
+        and file_name not in TEXT_FILE_NAMES
+    ):
+        return False
+
+    try:
+        with open(file_path, "rb") as f:
+            return b"\x00" not in f.read(BINARY_SNIFF_BYTES)
+    except OSError as e:
+        debug_log(f"Could not sniff {file_path} for binary content: {e}", "warning")
+        return False
+
+
+def _normalize_line_endings(file_path: str, file_name: str) -> None:
+    """
+    Rewrite a copied text file with Unix line endings.
+
+    Templates checked out on Windows (or with ``core.autocrlf=true``) carry
+    CRLF, which makes a generated project's shell scripts unusable inside a
+    Linux container: ``env: 'bash\r': No such file or directory``. The rewrite
+    happens in place through :func:`fix_script_line_endings`, which truncates
+    rather than recreates the file and therefore keeps the executable bit
+    ``shutil.copy2`` just carried over.
+
+    :param file_path: Path of the copied file
+    :param file_name: File name used for the text/binary decision
+    """
+    if not _looks_like_text_file(file_path, file_name):
+        return
+
+    # Imported lazily: ``fastapi_fastkit.backend.inspection`` pulls in the
+    # scaffolder, which imports this module, so a top-level import would be
+    # circular.
+    from fastapi_fastkit.backend.inspection.fsutils import fix_script_line_endings
+
+    fix_script_line_endings(file_path)
+
 
 def copy_and_convert_template(
     template_dir: str, target_dir: str, project_name: str = ""
@@ -130,6 +228,7 @@ def _copy_template_file(
 
     try:
         shutil.copy2(src_file, dst_file)
+        _normalize_line_endings(dst_file, dst_file_name)
         debug_log(f"Copied {src_file} to {dst_file}", "debug")
         return dst_file
 
@@ -223,8 +322,8 @@ def _write_target_file(target_file: str, content: str, source_file: str) -> bool
         target_dir = os.path.dirname(target_file)
         os.makedirs(target_dir, exist_ok=True)
 
-        with open(target_file, "w", encoding="utf-8") as f:
-            f.write(content)
+        with open(target_file, "w", encoding="utf-8", newline="\n") as f:
+            f.write(content.replace("\r\n", "\n").replace("\r", "\n"))
 
         debug_log(
             f"Successfully copied template file from {source_file} to {target_file}",

fastapi_fastkit/cli.py

@@ -37,6 +37,7 @@ from fastapi_fastkit.backend.project_builder.config_schema import (
     ConfigSchemaError,
     normalize_project_config,
 )
+from fastapi_fastkit.backend.route_generators import resolve_route_layout
 from fastapi_fastkit.backend.scaffolder import (
     ProjectScaffolder,
     ScaffoldOptions,
@@ -829,8 +830,16 @@ def _init_from_config(
 @fastkit_cli.command()
 @click.argument("route_name")
 @click.argument("project_dir", default=".")
+@click.option(
+    "--layout",
+    type=click.Choice(["classic-layer", "domain"]),
+    default=None,
+    help="Route layout. Defaults to domain for domain-starter, otherwise classic-layer.",
+)
 @click.pass_context
-def addroute(ctx: Context, route_name: str, project_dir: str) -> None:
+def addroute(
+    ctx: Context, route_name: str, project_dir: str, layout: Optional[str]
+) -> None:
     """
     Add a new route to the FastAPI project.
 
@@ -879,12 +888,14 @@ def addroute(ctx: Context, route_name: str, project_dir: str) -> None:
         return
 
     try:
+        route_layout = resolve_route_layout(actual_project_dir, layout)
         # Show information about the operation
         table = create_info_table(
             "Adding New Route",
             {
                 "Project": project_name,
                 "Route Name": route_name,
+                "Layout": route_layout,
                 "Target Directory": actual_project_dir,
             },
         )
@@ -903,7 +914,7 @@ def addroute(ctx: Context, route_name: str, project_dir: str) -> None:
             return
 
         # Add the new route
-        add_new_route(actual_project_dir, route_name)
+        add_new_route(actual_project_dir, route_name, layout=route_layout)
 
         if project_dir == ".":
             print_success(

fastapi_fastkit/core/settings.py

@@ -257,13 +257,13 @@ class FastkitConfig:
             DatabaseChoice.NONE: [],
         },
         FeatureAxis.AUTHENTICATION: {
-            AuthChoice.JWT: ["python-jose[cryptography]", "passlib[bcrypt]"],
+            AuthChoice.JWT: ["pyjwt[crypto]", "pwdlib[argon2]"],
             # SessionMiddleware (used by the OAuth2 login flow) needs itsdangerous.
             AuthChoice.OAUTH2: ["authlib", "itsdangerous", "httpx"],
             AuthChoice.FASTAPI_USERS: [
                 "fastapi-users[sqlalchemy]",
-                "python-jose[cryptography]",
-                "passlib[bcrypt]",
+                "pyjwt[crypto]",
+                "pwdlib[argon2]",
             ],
             AuthChoice.SESSION: ["itsdangerous"],
             AuthChoice.NONE: [],

fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/pyproject.toml-tpl

@@ -19,7 +19,7 @@ dependencies = [
     "sqlmodel>=0.0.42",
     "SQLAlchemy>=2.0.52",
     "alembic>=1.19.1",
-    "PyJWT>=2.13.0",
+    "PyJWT>=2.15.1",
     "pwdlib[argon2]>=0.3.1",
     "psycopg[binary]>=3.3.5",
 ]

fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/requirements.txt-tpl

@@ -12,7 +12,7 @@ SQLAlchemy==2.0.52
 alembic==1.19.1
 psycopg[binary]==3.3.5
 # Authentication
-PyJWT==2.13.0
+PyJWT==2.15.1
 pwdlib[argon2]==0.3.1
 # Development & tests
 pytest==9.1.1

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/api/router.py-tpl

@@ -11,5 +11,5 @@ from src.app.domains.items import router as items_router
 
 api_router = APIRouter()
 api_router.include_router(health.router)
-api_router.include_router(items_router.router)
+api_router.include_router(items_router.router, prefix="/items", tags=["items"])
 # fastkit:routes

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/src/app/domains/items/router.py-tpl

@@ -7,7 +7,7 @@ from fastapi import APIRouter, Depends, HTTPException, Response, status
 from src.app.domains.items.schemas import ItemCreate, ItemRead
 from src.app.domains.items.service import ItemNotFoundError, ItemService
 
-router = APIRouter(prefix="/items", tags=["items"])
+router = APIRouter()
 
 
 def get_item_service() -> ItemService:

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/tests/conftest.py-tpl

@@ -2,19 +2,31 @@
 # pytest fixtures for <project_name>.
 # --------------------------------------------------------------------------
 from collections.abc import Generator
+from importlib import import_module
+from pkgutil import iter_modules
 
 import pytest
 from fastapi.testclient import TestClient
+from src.app import domains
 from src.app.domains.items.repository import ItemRepository
 from src.app.main import app
 
 
-@pytest.fixture(autouse=True)
-def reset_items_store() -> Generator[None, None, None]:
-    """Each test starts with an empty items store."""
+def reset_stores() -> None:
     ItemRepository().reset()
+    for module in iter_modules(domains.__path__, prefix=f"{domains.__name__}."):
+        if module.ispkg:
+            domain = import_module(module.name)
+            reset = getattr(getattr(domain, "service", None), "reset_store", None)
+            if reset is not None:
+                reset()
+
+
+@pytest.fixture(autouse=True)
+def reset_domain_stores() -> Generator[None, None, None]:
+    reset_stores()
     yield
-    ItemRepository().reset()
+    reset_stores()
 
 
 @pytest.fixture

fastapi_fastkit/fastapi_project_template/fastapi-mcp/.env-tpl

@@ -21,7 +21,7 @@ MCP_TITLE=FastAPI MCP Server
 MCP_DESCRIPTION=FastAPI endpoints exposed as MCP tools
 
 # Authentication Settings
-SECRET_KEY=changethis
+SECRET_KEY=changethis-please-use-openssl-rand-hex-32
 ALGORITHM=HS256
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 

fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl

@@ -75,7 +75,7 @@ MCP_TITLE=FastAPI MCP Server
 MCP_DESCRIPTION=FastAPI endpoints exposed as MCP tools
 
 # Authentication Settings
-SECRET_KEY=changethis
+SECRET_KEY=changethis-please-use-openssl-rand-hex-32
 ALGORITHM=HS256
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 

fastapi_fastkit/fastapi_project_template/fastapi-mcp/pyproject.toml-tpl

@@ -17,9 +17,8 @@ dependencies = [
     "python-dotenv>=1.2.3",
     "fastapi-mcp>=0.3.7,<0.4.0",
     "mcp>=1.29.1,<2.0.0",
-    "bcrypt>=4.0.1,<4.1.0",
-    "passlib>=1.7.4",
-    "python-jose>=3.5.0",
+    "pwdlib[argon2]>=0.3.1",
+    "PyJWT[crypto]>=2.15.1",
     "python-multipart>=0.0.32",
 ]
 

fastapi_fastkit/fastapi_project_template/fastapi-mcp/requirements.txt-tpl

@@ -1,9 +1,10 @@
 annotated-doc==0.0.5
 annotated-types==0.8.0
 anyio==4.15.0
+argon2-cffi==25.1.0
+argon2-cffi-bindings==26.1.0
 ast-serialize==0.9.0
 attrs==26.1.0
-bcrypt==4.0.1
 black==26.5.1
 certifi==2026.7.22
 cffi==2.1.1
@@ -11,7 +12,6 @@ charset-normalizer==3.5.1
 click==8.5.0
 coverage==7.16.0
 cryptography==50.0.1
-ecdsa==0.19.2
 fastapi==0.141.1
 fastapi-mcp==0.3.7
 h11==0.16.0
@@ -31,21 +31,19 @@ mdurl==0.1.2
 mypy==2.3.1
 mypy-extensions==1.1.0
 packaging==26.3
-passlib==1.7.4
 pathspec==1.1.1
 platformdirs==4.11.7
 pluggy==1.6.0
-pyasn1==0.6.4
+pwdlib==0.3.1
 pycparser==3.0
 pydantic==2.13.5
 pydantic-core==2.46.5
 pydantic-settings==2.15.0
 pygments==2.21.0
-pyjwt==2.13.0
+PyJWT==2.15.1
 pytest==9.1.1
 pytest-cov==7.1.0
 python-dotenv==1.2.3
-python-jose==3.5.0
 python-multipart==0.0.32
 pytokens==0.4.1
 PyYAML==6.0.3
@@ -53,9 +51,7 @@ referencing==0.37.0
 requests==2.34.2
 rich==15.0.0
 rpds-py==2026.6.3
-rsa==4.9.1
 shellingham==1.5.4
-six==1.17.0
 SQLAlchemy==2.0.52
 sse-starlette==3.4.10
 starlette==1.6.0
@@ -63,7 +59,7 @@ tomli==2.4.1
 typer==0.27.2
 typing-extensions==4.16.0
 typing-inspection==0.4.4
-urllib3==2.7.0
+urllib3==2.8.0
 uvicorn==0.52.4
 uvloop==0.22.1
 watchfiles==1.2.0

fastapi_fastkit/fastapi_project_template/fastapi-mcp/setup.cfg-tpl

@@ -29,9 +29,8 @@ install_requires =
     pydantic>=2.10.6
     pydantic-settings>=2.7.1
     python-dotenv>=1.0.1
-    python-jose>=3.3.0
-    passlib>=1.7.4
-    bcrypt>=4.1.2
+    PyJWT[crypto]>=2.15.1
+    pwdlib[argon2]>=0.3.1
     python-multipart>=0.0.17
 
 [options.extras_require]