FastAPI-fastkit 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

fastapi_fastkit/cli.py

@@ -43,9 +43,28 @@ from fastapi_fastkit.utils.main import (
     validate_email,
 )
 
+from . import __version__
+
 console = utils_console
 
-from . import __version__
+
+def _cleanup_failed_project(
+    project_dir: str, user_workspace: str, create_project_folder: bool
+) -> None:
+    """
+    Clean up a partially created project after an error.
+
+    Only deletes a freshly created project folder. When the project was deployed
+    in-place (create_project_folder=False), project_dir equals the user's workspace,
+    and removing it would destroy unrelated files, so no cleanup is performed.
+    """
+    if not create_project_folder:
+        return
+    if not project_dir or not os.path.exists(project_dir):
+        return
+    if os.path.abspath(project_dir) == os.path.abspath(user_workspace):
+        return
+    shutil.rmtree(project_dir, ignore_errors=True)
 
 
 @click.group()
@@ -248,7 +267,7 @@ def startdemo(
     if template_deps:
         deps_table = create_info_table(
             "Template Dependencies",
-            {f"Dependency {i+1}": dep for i, dep in enumerate(template_deps)},
+            {f"Dependency {i + 1}": dep for i, dep in enumerate(template_deps)},
         )
         console.print("\n")
         console.print(deps_table)
@@ -315,7 +334,11 @@ def startdemo(
     "--interactive",
     is_flag=True,
     default=False,
-    help="Enable interactive mode for guided project setup with feature selection.",
+    help=(
+        "Enable interactive mode for guided project setup. Walks through an "
+        "architecture preset (minimal / single-module / classic-layered / "
+        "domain-starter, default: domain-starter), then feature selection."
+    ),
 )
 @click.option(
     "--project-name",
@@ -353,7 +376,11 @@ def init(
     """
     Start a FastAPI project setup.
 
-    Use --interactive for guided setup with dynamic feature selection.
+    Use --interactive for guided setup. Interactive mode prompts for an
+    architecture preset (``minimal`` / ``single-module`` / ``classic-layered``
+    / ``domain-starter`` — default: ``domain-starter``) and then walks
+    through feature selection (database, auth, testing, deployment, ...).
+
     Without --interactive, creates an empty project with predefined stacks.
 
     This command will automatically create a new FastAPI project directory
@@ -395,8 +422,17 @@ def init(
         try:
             user_local = settings.USER_WORKSPACE
 
-            # Use fastapi-empty template as base
-            template = "fastapi-empty"
+            # Pick the base template from the architecture preset chosen
+            # earlier in the interactive flow. Older callers without a
+            # preset fall back to ``minimal`` (= fastapi-empty), preserving
+            # pre-#45 behaviour.
+            from fastapi_fastkit.backend.project_builder import (
+                PresetLayoutStrategist,
+            )
+
+            preset_id = config.get("architecture_preset")
+            strategist = PresetLayoutStrategist(preset_id)
+            template = strategist.base_template
             template_dir = settings.FASTKIT_TEMPLATE_ROOT
             target_template = os.path.join(template_dir, template)
 
@@ -445,56 +481,72 @@ def init(
 
             generator = DynamicConfigGenerator(config, project_dir)
 
-            # Generate main.py with selected features
-            main_py_content = generator.generate_main_py()
-            main_py_path = os.path.join(project_dir, "src", "main.py")
-            if not os.path.exists(main_py_path):
-                main_py_path = os.path.join(project_dir, "main.py")
-
-            with open(main_py_path, "w") as f:
-                f.write(main_py_content)
+            # main.py overlay — only regenerated for presets that ship a
+            # placeholder app (minimal, single-module). For richer presets
+            # (classic-layered, domain-starter) we keep the template's
+            # router-aware main.py intact.
+            #
+            # The strategist's ``main_py_target`` is always ``src/main.py``
+            # for both regenerate-main presets, and both fastapi-empty and
+            # fastapi-single-module ship that file, so we can write
+            # straight to the strategist's path without a flat-``main.py``
+            # fallback branch.
+            if strategist.should_regenerate_main:
+                main_py_path = strategist.main_py_target(project_dir)
+                main_py_path.parent.mkdir(parents=True, exist_ok=True)
+                main_py_path.write_text(generator.generate_main_py())
+            else:
+                print_info(
+                    f"Preserving template-shipped main.py for preset "
+                    f"'{strategist.preset_id}'."
+                )
 
-            # Generate database configuration if selected
+            # Generate database configuration if selected — preset chooses
+            # where the file lives so it sits next to the existing structure.
             db_info = config.get("database", {})
             if isinstance(db_info, dict) and db_info.get("type") != "None":
                 db_config_content = generator.generate_database_config()
                 if db_config_content:
-                    db_config_path = os.path.join(
-                        project_dir, "src", "config", "database.py"
-                    )
-                    os.makedirs(os.path.dirname(db_config_path), exist_ok=True)
-                    with open(db_config_path, "w") as f:
-                        f.write(db_config_content)
+                    db_config_path = strategist.db_config_target(project_dir)
+                    db_config_path.parent.mkdir(parents=True, exist_ok=True)
+                    db_config_path.write_text(db_config_content)
 
             # Generate auth configuration if selected
             auth_type = config.get("authentication", "None")
             if auth_type != "None":
                 auth_config_content = generator.generate_auth_config()
                 if auth_config_content:
-                    auth_config_path = os.path.join(
-                        project_dir, "src", "config", "auth.py"
-                    )
-                    os.makedirs(os.path.dirname(auth_config_path), exist_ok=True)
-                    with open(auth_config_path, "w") as f:
-                        f.write(auth_config_content)
+                    auth_config_path = strategist.auth_config_target(project_dir)
+                    auth_config_path.parent.mkdir(parents=True, exist_ok=True)
+                    auth_config_path.write_text(auth_config_content)
 
             # Generate test configuration if testing selected
             testing_type = config.get("testing", "None")
             if testing_type != "None":
                 test_config_content = generator.generate_test_config()
                 if test_config_content:
-                    test_config_path = os.path.join(project_dir, "tests", "conftest.py")
-                    os.makedirs(os.path.dirname(test_config_path), exist_ok=True)
+                    test_config_path = os.path.join(project_dir, "pytest.ini")
                     with open(test_config_path, "w") as f:
                         f.write(test_config_content)
 
             # Generate Docker files if deployment selected
             deployment = config.get("deployment", [])
             if deployment and deployment != ["None"]:
-                generator.generate_docker_files()
-                print_success(f"Generated Docker deployment files")
-
-            print_success(f"Generated configuration files for selected stack")
+                # Thread the preset-aware app module so the generated
+                # Dockerfile's ``CMD ["uvicorn", "<module>:app", ...]``
+                # matches the layout the user actually generated. Default
+                # ``src.main:app`` only works for minimal / single-module /
+                # classic-layered; domain-starter needs ``src.app.main:app``.
+                generator.generate_docker_files(app_module=strategist.app_module)
+                print_success("Generated Docker deployment files")
+
+            # Surface preset-specific warnings (e.g. "you picked a preset
+            # whose shipped main.py we kept; CORS/Prometheus must be wired
+            # manually").
+            for warning in strategist.compatibility_warnings(config):
+                print_warning(warning, title="Preset compatibility")
+
+            print_success("Generated configuration files for selected stack")
 
             # Create virtual environment and install dependencies
             venv_path = create_venv_with_manager(project_dir, package_manager)
@@ -514,8 +566,9 @@ def init(
                 logger = get_logger()
                 logger.exception(f"Error during project creation in init: {str(e)}")
             print_error(f"Error during project creation: {str(e)}")
-            if os.path.exists(project_dir):
-                shutil.rmtree(project_dir, ignore_errors=True)
+            _cleanup_failed_project(
+                project_dir, settings.USER_WORKSPACE, create_project_folder
+            )
 
         return
 
@@ -560,7 +613,7 @@ def init(
     for stack_name, deps in settings.PROJECT_STACKS.items():
         table = create_info_table(
             f"{stack_name.upper()} Stack",
-            {f"Dependency {i+1}": dep for i, dep in enumerate(deps)},
+            {f"Dependency {i + 1}": dep for i, dep in enumerate(deps)},
         )
         console.print(table)
         console.print("\n")
@@ -662,8 +715,9 @@ def init(
             logger = get_logger()
             logger.exception(f"Error during project creation in init: {str(e)}")
         print_error(f"Error during project creation: {str(e)}")
-        if os.path.exists(project_dir):
-            shutil.rmtree(project_dir, ignore_errors=True)
+        _cleanup_failed_project(
+            project_dir, settings.USER_WORKSPACE, create_project_folder
+        )
 
 
 @fastkit_cli.command()
@@ -799,6 +853,20 @@ def deleteproject(ctx: Context, project_name: str) -> None:
         print_error(f"Error during project deletion: {e}")
 
 
+def _derive_app_module(project_dir: str, main_path: str) -> str:
+    """Convert a discovered ``main.py`` path into a uvicorn ``module:attr``.
+
+    Templates can place ``main.py`` anywhere under the project (``main.py``,
+    ``src/main.py``, ``src/app/main.py``, ...). The previous ``"src/"`` /
+    ``""`` heuristic mis-mapped the domain-starter layout (``src/app/main.py``
+    → wrongly produced ``src.main:app``); deriving the dotted path from the
+    actual relative location avoids that drift for any future layout too.
+    """
+    rel_path = os.path.relpath(main_path, project_dir)
+    module_part = os.path.splitext(rel_path)[0].replace(os.sep, ".")
+    return f"{module_part}:app"
+
+
 @fastkit_cli.command()
 @click.option(
     "--host",
@@ -873,10 +941,7 @@ def runserver(
         return
 
     main_path = core_modules["main"]
-    if "src/" in main_path:
-        app_module = "src.main:app"
-    else:
-        app_module = "main:app"
+    app_module = _derive_app_module(project_dir, main_path)
 
     if venv_python:
         print_info(f"Using Python from virtual environment: {venv_python}")
@@ -930,9 +995,9 @@ def runserver(
         logger.exception(f"FileNotFoundError when starting server: {e}")
         if venv_python:
             print_error(
-                f"Failed to run Python from the virtual environment. Make sure uvicorn is installed in the project's virtual environment."
+                "Failed to run Python from the virtual environment. Make sure uvicorn is installed in the project's virtual environment."
             )
         else:
             print_error(
-                f"uvicorn not found. Make sure it's installed in your system Python."
+                "uvicorn not found. Make sure it's installed in your system Python."
             )

fastapi_fastkit/core/settings.py

@@ -24,6 +24,7 @@ class FastkitConfig:
     TEMPLATE_PATHS: dict[str, list[str] | dict[str, list[str]]] = {
         "main": [
             "src/main.py",
+            "src/app/main.py",
             "main.py",
         ],
         "setup": [
@@ -37,12 +38,27 @@ class FastkitConfig:
             "files": ["settings.py", "config.py"],
             "paths": [
                 "src/core",
+                "src/app/core",
                 "src",
                 "",
             ],
         },
     }
 
+    # Architecture Presets (interactive ``init`` wizard)
+    #
+    # The preset shapes how the generated project is laid out (single file vs.
+    # layered vs. domain-oriented). Preset-specific generation logic lives in
+    # later issues — this catalog is the user-facing menu and the canonical
+    # set of preset ids persisted in the interactive config.
+    ARCHITECTURE_PRESETS: dict[str, str] = {
+        "minimal": "Smallest viable FastAPI app — a single app + a couple of files.",
+        "single-module": "Everything in one module; ideal for tiny scripts and prototypes.",
+        "classic-layered": "Layered split: api/routes, crud, schemas, core (a la fastapi-default).",
+        "domain-starter": "Domain-oriented: src/app/domains/<concept>/ with router/service/repository (recommended).",
+    }
+    DEFAULT_ARCHITECTURE_PRESET: str = "domain-starter"
+
     # Startproject Options
     PROJECT_STACKS: dict[str, list[str]] = {
         "minimal": ["fastapi", "uvicorn", "pydantic", "pydantic-settings"],
@@ -102,7 +118,7 @@ class FastkitConfig:
             "MySQL": ["pymysql", "aiomysql", "sqlalchemy", "alembic"],
             "MongoDB": ["motor", "beanie"],
             "Redis": ["redis[hiredis]", "aioredis"],
-            "SQLite": ["sqlalchemy", "alembic"],
+            "SQLite": ["sqlalchemy", "aiosqlite", "alembic"],
             "None": [],
         },
         "authentication": {

fastapi_fastkit/fastapi_project_template/README.md

@@ -18,37 +18,86 @@ template-name/
 │ ├── models/
 │ ├── routes/
 │ └── utils/
-├── tests/
+├── tests/                    # required
 ├── scripts/
-├── requirements.txt-tpl
-├── setup.py-tpl
-└── README.md-tpl
+├── pyproject.toml-tpl        # preferred primary metadata file (PEP 621)
+├── setup.py-tpl              # legacy alternative, still accepted
+├── requirements.txt-tpl      # optional when pyproject.toml-tpl declares deps
+└── README.md-tpl             # required
 ```
 
+The minimum required files for a modern template are `tests/`, `README.md-tpl`,
+and at least one metadata file (`pyproject.toml-tpl` or `setup.py-tpl`).
+`requirements.txt-tpl` is optional when the template's dependencies are
+declared under `[project].dependencies` in `pyproject.toml-tpl`.
+
+Modern templates **SHOULD** ship `pyproject.toml-tpl` as the primary metadata
+file. `setup.py-tpl` remains supported for backward compatibility.
+
 ### Key Requirements:
 
 1. All source files must use `.py-tpl` extension
-2. `setup.py` must include `fastapi-fastkit` string in project description
-   for example:
-   ```
-   ...
-   setup(
-      ...
-      description = "[fastapi-fastkit templated] <description>",
-      ...
-   )
-   ```
-3. `setup.py` must include `install_requires` section, it must include essential dependencies for the template project. Also, note that install_requires list must be type annotated.
-   for example:
+2. The template must declare `fastapi` as a dependency in at least one of:
+   - `pyproject.toml-tpl` under `[project].dependencies` (preferred)
+   - `requirements.txt-tpl`
+   - `setup.py-tpl` under `install_requires`
+3. `pyproject.toml-tpl` (preferred) should use PEP 621 metadata and carry the
+   FastAPI-fastkit identity markers so that `is_fastkit_project()` can tell
+   generated projects apart from unrelated FastAPI projects in the user's
+   workspace:
    ```
-   ...
-   install_requires: list[str] = [
-      ...
-   ],
+   [project]
+   name = "<project_name>"
+   version = "0.1.0"
+   description = "[FastAPI-fastkit templated] <description>"
+   dependencies = [
+       "fastapi>=0.115.0",
+       ...
+   ]
+
+   [tool.fastapi-fastkit]
+   managed = true
    ```
-4. Basic CRUD operations example
-5. Unit tests implementation
-6. API documentation (OpenAPI/Swagger)
+   The `[FastAPI-fastkit templated]` marker in `description` and the
+   `[tool.fastapi-fastkit]` table are both recognized by detection (any one
+   suffices; matching is case-insensitive). Metadata injection will also add
+   these markers at project-generation time if a template forgets them, but
+   authors should include them explicitly.
+4. Legacy templates using `setup.py-tpl` should:
+   - declare dependencies via a type-annotated `install_requires` list, e.g.
+     ```
+     install_requires: list[str] = [
+        ...
+     ]
+     ```
+   - include the `[FastAPI-fastkit templated]` marker in the project
+     description. Detection falls back to a case-insensitive scan for
+     `fastapi-fastkit` in `setup.py`, so this marker keeps legacy projects
+     identifiable:
+     ```
+     setup(
+        ...
+        description = "[FastAPI-fastkit templated] <description>",
+        ...
+     )
+     ```
+5. Basic CRUD operations example
+6. Unit tests implementation
+7. API documentation (OpenAPI/Swagger)
+
+## Available templates
+
+| Template | When to choose |
+|---|---|
+| `fastapi-default` | Quick CRUD demo with the classic layered layout (`api/routes`, `crud`, `schemas`). Good first stop. |
+| `fastapi-empty` | Minimal scaffold for users who want to add their own structure on top. |
+| `fastapi-single-module` | Single-file sandbox for tiny prototypes / scripts. |
+| `fastapi-async-crud` | Async-flavoured equivalent of `fastapi-default`. |
+| `fastapi-custom-response` | Demonstrates custom response formatting / envelope patterns. |
+| `fastapi-dockerized` | Adds a production-ready Dockerfile to the default layout. |
+| `fastapi-psql-orm` | PostgreSQL + SQLAlchemy + Alembic; pick this when you need a real database. |
+| `fastapi-mcp` | Model Context Protocol integration. |
+| `fastapi-domain-starter` | **Recommended modern default for medium-sized APIs.** Pyproject-first, domain-oriented layout (`src/app/domains/<concept>/`) with a clean transport / service / repository split, plus a built-in `/health` probe. |
 
 ## Base structure of modules template
 

fastapi_fastkit/fastapi_project_template/fastapi-async-crud/pyproject.toml-tpl

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -41,6 +41,9 @@ dev = [
     "PyYAML>=6.0.2",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

fastapi_fastkit/fastapi_project_template/fastapi-custom-response/pyproject.toml-tpl

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -41,6 +41,9 @@ dev = [
     "PyYAML>=6.0.2",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

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

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -38,6 +38,9 @@ dev = [
     "PyYAML>=6.0.2",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

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

@@ -1,7 +1,7 @@
 [project]
 name = "<project_name>"
 version = "0.1.0"
-description = "<description>"
+description = "[FastAPI-fastkit templated] <description>"
 authors = [
     {name = "<author>", email = "<author_email>"},
 ]
@@ -41,6 +41,9 @@ dev = [
     "setuptools-scm>=8.1.0",
 ]
 
+[tool.fastapi-fastkit]
+managed = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/.env-tpl

@@ -0,0 +1,2 @@
+SECRET_KEY=changethis
+ENVIRONMENT=development

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/.gitignore-tpl

@@ -0,0 +1,31 @@
+.idea
+.ipynb_checkpoints
+.mypy_cache
+.vscode
+__pycache__
+.pytest_cache
+htmlcov
+dist
+site
+.coverage*
+coverage.xml
+.netlify
+test.db
+log.txt
+Pipfile.lock
+env3.*
+env
+docs_build
+site_build
+venv
+.venv
+docs.zip
+archive.zip
+
+# vim temporary files
+*~
+.*.sw?
+.cache
+
+# macOS
+.DS_Store

fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl

@@ -0,0 +1,128 @@
+# FastAPI Domain Starter
+
+Modern, domain-oriented FastAPI starter — the recommended default for
+medium-sized API projects.
+
+> Generated project: **<project_name>** — <description>
+
+## When to choose this starter
+
+Pick this template when you want:
+
+- A **domain-oriented layout** (one folder per business concept under
+  `src/app/domains/`) rather than the layered `routes/ + crud/ + schemas/`
+  split. Domains scale better as the API grows.
+- A clear separation between **transport** (`router.py`), **business
+  logic** (`service.py`), and **data access** (`repository.py`) so each
+  layer can evolve independently.
+- A **`pyproject.toml`-first** project (PEP 621) compatible with `uv`,
+  `pdm`, or `poetry` out of the box — no `setup.py` to maintain.
+- Sensible defaults for settings, testing, formatting, and a built-in
+  `/health` probe.
+
+If you only need a quick CRUD demo, start with `fastapi-default`. If you
+need PostgreSQL, start with `fastapi-psql-orm`. If you want a single-file
+sandbox, use `fastapi-single-module`.
+
+## Project structure
+
+```
+.
+├── README.md
+├── pyproject.toml
+├── .env
+├── .gitignore
+├── scripts/
+│   ├── format.sh
+│   ├── lint.sh
+│   ├── run-server.sh
+│   └── test.sh
+├── src/
+│   └── app/
+│       ├── main.py             # FastAPI app entry point
+│       ├── core/
+│       │   └── config.py       # pydantic-settings configuration
+│       ├── db/
+│       │   └── memory.py       # in-memory store stand-in for a real DB
+│       ├── api/
+│       │   ├── router.py       # aggregates health + every domain router
+│       │   └── health.py       # GET /health
+│       └── domains/
+│           └── items/          # example domain (CRUD over an item entity)
+│               ├── models.py       # entity dataclass
+│               ├── schemas.py      # API I/O schemas (pydantic)
+│               ├── repository.py   # data access layer
+│               ├── service.py      # business logic
+│               └── router.py       # FastAPI router for the domain
+└── tests/
+    ├── conftest.py
+    ├── test_health.py
+    └── test_items.py
+```
+
+The recipe for adding a new domain is:
+
+1. Create `src/app/domains/<your_domain>/`.
+2. Mirror the `items` layout (`models.py`, `schemas.py`, `repository.py`,
+   `service.py`, `router.py`).
+3. Register the router in `src/app/api/router.py`.
+4. Add tests under `tests/test_<your_domain>.py`.
+
+## Running the app
+
+```bash
+# create a virtualenv and install dependencies
+$ uv sync   # or: pip install -e ".[dev]"
+
+# launch the dev server
+$ bash scripts/run-server.sh
+# or directly:
+$ uvicorn src.app.main:app --reload
+```
+
+API docs are then served at:
+
+- Swagger UI: <http://127.0.0.1:8000/docs>
+- ReDoc:      <http://127.0.0.1:8000/redoc>
+
+## API endpoints
+
+| Method | Endpoint                  | Description                  |
+|--------|---------------------------|------------------------------|
+| GET    | `/api/v1/health`          | Liveness probe               |
+| GET    | `/api/v1/items`           | List items                   |
+| GET    | `/api/v1/items/{item_id}` | Read a single item           |
+| POST   | `/api/v1/items`           | Create an item               |
+| PUT    | `/api/v1/items/{item_id}` | Replace an item              |
+| DELETE | `/api/v1/items/{item_id}` | Delete an item               |
+
+## Running tests
+
+```bash
+$ bash scripts/test.sh
+# or directly:
+$ pytest
+```
+
+## Configuration
+
+`src/app/core/config.py` reads settings from environment variables (or a
+local `.env` file). The provided `.env` only sets a placeholder
+`SECRET_KEY` — replace it before deploying.
+
+## Project Origin
+
+This project was created from the **`fastapi-domain-starter`** template
+shipped with [FastAPI-fastkit](https://github.com/bnbong/FastAPI-fastkit).
+
+The `FastAPI-fastkit` is an open-source project that helps Python and
+FastAPI beginners quickly set up a FastAPI-based application development
+environment in a framework-like structure.
+
+For an end-to-end walkthrough of this template — the generated tree,
+the bundled `items` example, and how to add your next domain — see the
+[**Domain-oriented Project tutorial**](https://bnbong.github.io/FastAPI-fastkit/tutorial/domain-starter/).
+
+### Template Information
+- Template creator: [bnbong](mailto:bbbong9@gmail.com)
+- FastAPI-fastkit project maintainer: [bnbong](mailto:bbbong9@gmail.com)