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

fastapi_fastkit/utils/config_file.py

@@ -0,0 +1,263 @@
+# --------------------------------------------------------------------------
+# Project configuration file (de)serialization for non-interactive ``init``.
+#
+# ``fastkit init --interactive`` builds a plain configuration dict; this
+# module lets that same dict travel through a file so a project can be
+# reproduced without answering a single prompt (``--config``), and so an
+# interactive session can be captured for later reuse (``--save-config``).
+#
+# Supported formats are picked from the file extension: JSON and TOML are
+# always available (both ship with the stdlib on Python 3.12), YAML only
+# when PyYAML happens to be installed — fastkit deliberately does not add it
+# as a runtime dependency.
+#
+# @author bnbong bbbong9@gmail.com
+# --------------------------------------------------------------------------
+import importlib
+import json
+import os
+import tomllib
+from typing import Any, Dict, List, Tuple
+
+from fastapi_fastkit.backend.interactive.validators import (
+    validate_email_format,
+    validate_project_name,
+)
+from fastapi_fastkit.backend.project_builder.config_schema import (
+    ConfigSchemaError,
+    normalize_project_config,
+    validate_project_config_schema,
+)
+
+JSON_EXTENSIONS: Tuple[str, ...] = (".json",)
+TOML_EXTENSIONS: Tuple[str, ...] = (".toml",)
+YAML_EXTENSIONS: Tuple[str, ...] = (".yaml", ".yml")
+
+SUPPORTED_EXTENSIONS: Tuple[str, ...] = (
+    JSON_EXTENSIONS + TOML_EXTENSIONS + YAML_EXTENSIONS
+)
+
+# Keys the scaffolder needs; everything else in the file is passed through
+# untouched so feature blocks stay forward-compatible.
+REQUIRED_KEYS: Tuple[str, ...] = ("project_name", "author", "author_email")
+
+
+class ConfigFileError(Exception):
+    """Raised when a project config file cannot be read, parsed or trusted."""
+
+
+def _yaml_module() -> Any:
+    """Return the optional PyYAML module, or None when it isn't installed."""
+    try:
+        # Imported dynamically: PyYAML is optional, so a static import would
+        # make it look like a hard dependency to type checkers and readers.
+        return importlib.import_module("yaml")
+    except ImportError:
+        return None
+
+
+def load_project_config(path: str) -> Dict[str, Any]:
+    """
+    Load a project configuration dict from a JSON / TOML / YAML file.
+
+    :param path: Path to the configuration file
+    :return: Configuration dictionary equivalent to the interactive builder's
+    :raises ConfigFileError: If the file is missing, of an unsupported format,
+        unparsable, or does not describe a mapping.
+    """
+    if not os.path.exists(path):
+        raise ConfigFileError(f"Config file not found: {path}")
+
+    extension = os.path.splitext(path)[1].lower()
+
+    if extension in JSON_EXTENSIONS:
+        raw = _load_json(path)
+    elif extension in TOML_EXTENSIONS:
+        raw = _load_toml(path)
+    elif extension in YAML_EXTENSIONS:
+        raw = _load_yaml(path)
+    else:
+        raise ConfigFileError(
+            f"Unsupported config file extension '{extension or path}'. "
+            f"Supported extensions: {', '.join(SUPPORTED_EXTENSIONS)}"
+        )
+
+    if not isinstance(raw, dict):
+        raise ConfigFileError(
+            f"Config file '{path}' must contain a mapping at its top level."
+        )
+
+    return raw
+
+
+def _load_json(path: str) -> Any:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise ConfigFileError(f"Could not parse JSON config '{path}': {e}")
+
+
+def _load_toml(path: str) -> Any:
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError) as e:
+        raise ConfigFileError(f"Could not parse TOML config '{path}': {e}")
+
+
+def _load_yaml(path: str) -> Any:
+    yaml = _yaml_module()
+    if yaml is None:
+        raise ConfigFileError(
+            "YAML config files need PyYAML, which is not installed. "
+            "Install it (pip install pyyaml) or use a .json / .toml config file instead."
+        )
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except Exception as e:
+        # PyYAML raises its own YAMLError hierarchy; catching broadly keeps
+        # this import-optional module free of a yaml type import.
+        raise ConfigFileError(f"Could not parse YAML config '{path}': {e}")
+
+
+def validate_project_config(config: Dict[str, Any]) -> List[str]:
+    """
+    Validate a loaded configuration against the interactive-mode rules.
+
+    Reuses ``interactive.validators`` so a file-driven run is held to exactly
+    the same standard as an answered prompt.
+
+    :param config: Configuration dictionary
+    :return: List of human-readable error messages (empty when the config is valid)
+    """
+    errors: List[str] = []
+
+    for key in REQUIRED_KEYS:
+        if not config.get(key):
+            errors.append(f"Missing required config key: '{key}'")
+
+    project_name = config.get("project_name")
+    if isinstance(project_name, str) and project_name:
+        is_valid, message = validate_project_name(project_name)
+        if not is_valid and message:
+            errors.append(message)
+
+    author_email = config.get("author_email")
+    if isinstance(author_email, str) and author_email:
+        if not validate_email_format(author_email):
+            errors.append(f"Invalid author email format: '{author_email}'")
+
+    # Feature selections are held to the catalog: an axis spelled in a shape
+    # the pipeline cannot read used to reach generation and produce a project
+    # whose ``main.py`` imported modules nobody wrote.
+    errors.extend(validate_project_config_schema(config))
+
+    return errors
+
+
+def load_normalized_project_config(path: str) -> Dict[str, Any]:
+    """
+    Load a config file and return it in the canonical pipeline shape.
+
+    ``load_project_config`` deliberately hands back exactly what the file
+    said (so ``--save-config`` round-trips byte for byte); this wrapper is
+    what the generation pipeline consumes, because every consumer of a
+    configuration must see the same normalised selections.
+
+    :param path: Path to the configuration file
+    :return: Normalised configuration dictionary
+    :raises ConfigFileError: If the file cannot be read, parsed or trusted
+    """
+    raw = load_project_config(path)
+    try:
+        return normalize_project_config(raw)
+    except ConfigSchemaError as e:
+        raise ConfigFileError(f"Invalid project config '{path}': {e}")
+
+
+def save_project_config(config: Dict[str, Any], path: str) -> None:
+    """
+    Write a configuration dict to a JSON / TOML / YAML file.
+
+    :param config: Configuration dictionary produced by the interactive builder
+    :param path: Destination path; the extension selects the format
+    :raises ConfigFileError: If the format is unsupported or the write fails
+    """
+    extension = os.path.splitext(path)[1].lower()
+
+    if extension in JSON_EXTENSIONS:
+        content = (
+            json.dumps(config, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+        )
+    elif extension in TOML_EXTENSIONS:
+        content = _dump_toml(config)
+    elif extension in YAML_EXTENSIONS:
+        yaml = _yaml_module()
+        if yaml is None:
+            raise ConfigFileError(
+                "Saving YAML config files needs PyYAML, which is not installed. "
+                "Use a .json / .toml path instead."
+            )
+        content = str(yaml.safe_dump(config, sort_keys=True, allow_unicode=True))
+    else:
+        raise ConfigFileError(
+            f"Unsupported config file extension '{extension or path}'. "
+            f"Supported extensions: {', '.join(SUPPORTED_EXTENSIONS)}"
+        )
+
+    try:
+        parent = os.path.dirname(os.path.abspath(path))
+        os.makedirs(parent, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(content)
+    except OSError as e:
+        raise ConfigFileError(f"Could not write config file '{path}': {e}")
+
+
+def _dump_toml(config: Dict[str, Any]) -> str:
+    """
+    Serialize a configuration dict to TOML.
+
+    Python 3.12 ships a TOML reader but no writer, and fastkit may not add a
+    runtime dependency for one. The interactive config only ever holds
+    strings, booleans, numbers, string lists and one level of nested tables
+    (``database``), which this covers.
+    """
+    scalars: List[str] = []
+    tables: List[str] = []
+
+    for key in sorted(config):
+        value = config[key]
+        if isinstance(value, dict):
+            table_lines = [f"[{key}]"]
+            for sub_key in sorted(value):
+                table_lines.append(f"{sub_key} = {format_toml_value(value[sub_key])}")
+            tables.append("\n".join(table_lines))
+        else:
+            scalars.append(f"{key} = {format_toml_value(value)}")
+
+    sections = ["\n".join(scalars)] if scalars else []
+    sections.extend(tables)
+    return "\n\n".join(section for section in sections if section) + "\n"
+
+
+def format_toml_value(value: Any) -> str:
+    """
+    Render a Python value as a TOML literal.
+
+    Shared with pyproject metadata injection so both writers escape and
+    quote values identically.
+
+    :param value: Value to render (bool / int / float / list / str)
+    :return: TOML literal string
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(format_toml_value(item) for item in value) + "]"
+    escaped = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'

fastapi_fastkit/utils/main.py

@@ -356,3 +356,41 @@ def _pyproject_text_marks_fastkit(pyproject_path: str) -> bool:
     if FASTKIT_DESCRIPTION_MARKER.lower() in content:
         return True
     return False
+
+
+def read_fastkit_metadata(project_dir: str) -> Dict[str, Any]:
+    """Read the ``[tool.fastapi-fastkit]`` block of a generated project.
+
+    The block is the shared contract between generation (``init`` /
+    ``startdemo``) and the commands that operate on an existing project
+    (``runserver``, ``addroute``): it records the template, preset,
+    package manager, selected features and — most importantly — the
+    ``app_module`` entrypoint, so those commands no longer have to
+    re-derive the layout heuristically.
+
+    :param project_dir: Path to the generated project directory
+    :return: The metadata mapping, or an empty dict when the project has no
+        readable ``pyproject.toml`` / no fastkit block.
+    """
+    pyproject_path = os.path.join(project_dir, "pyproject.toml")
+    if not os.path.exists(pyproject_path):
+        return {}
+
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+        debug_log(
+            f"Could not read fastkit metadata from {pyproject_path}: {e}", "warning"
+        )
+        return {}
+
+    tool_section = data.get("tool", {})
+    if not isinstance(tool_section, dict):
+        return {}
+
+    metadata = tool_section.get(FASTKIT_TOOL_SECTION, {})
+    if not isinstance(metadata, dict):
+        return {}
+
+    return dict(metadata)

{fastapi_fastkit-1.3.0.dist-info → fastapi_fastkit-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FastAPI-fastkit
-Version: 1.3.0
+Version: 1.4.1
 Summary: Fast, easy-to-use starter kit for new users of Python and FastAPI
 Author-Email: bnbong <bbbong9@gmail.com>
 License: MIT
@@ -11,6 +11,7 @@ Project-URL: Changelog, https://bnbong.github.io/FastAPI-fastkit/changelog/
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1.7
 Requires-Dist: rich>=13.9.2
+Requires-Dist: jinja2>=3.1
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.3; extra == "dev"
 Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
@@ -19,10 +20,11 @@ Requires-Dist: pre-commit>=4.0.1; extra == "dev"
 Requires-Dist: mypy>=1.12.0; extra == "dev"
 Requires-Dist: isort>=5.13.2; extra == "dev"
 Requires-Dist: pygments>=2.20.0; extra == "dev"
+Requires-Dist: types-pyyaml>=6.0.12.20260408; extra == "dev"
 Description-Content-Type: text/markdown
 
 <p align="center">
-    <img align="top" width="70%" src="https://bnbong.github.io/projects/img/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
+    <img align="top" width="70%" src=".github/fastkit_general_logo.png" alt="FastAPI-fastkit"/>
 </p>
 <p align="center">
 <em><b>FastAPI-fastkit</b>: Fast, easy-to-use starter kit for new users of Python and FastAPI</em>
@@ -57,6 +59,8 @@ This project was inspired by the `SpringBoot initializer` & Python Django's `dja
 - **🔍 Automated template quality assurance** : Weekly automated testing ensures all templates remain functional and up-to-date
 - **🚀 Multiple project templates** : Choose from various pre-configured templates for different use cases (async CRUD, Docker, PostgreSQL, etc.)
 - **📦 Multiple package manager support** : Choose your preferred Python package manager (pip, uv, pdm, poetry) for dependency management
+- **🧾 Reproducible project configs** : Save an interactive session to a `.json` / `.toml` / `.yaml` file and replay it with `fastkit init --config`
+- **🏷️ Self-describing projects** : Every generated project records its template, preset, package manager, entrypoint and selected features in a `[tool.fastapi-fastkit]` block that `runserver` and `addroute` read back
 
 ## Installation
 
@@ -78,17 +82,27 @@ $ pip install FastAPI-fastkit
 ```console
 fastkit init [OPTIONS]
 ```
-- What it does: Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+> [!TIP]
+> Scaffolds an empty FastAPI project, creates a virtual environment, installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--config <path>`: create the project from a saved config file (`.json` / `.toml`, and `.yaml` when PyYAML is installed) with no prompts
+  - `--save-config <path>`: with `--interactive`, record the answers for later reuse
+  - `--dry-run`: print the files and packages that would be created, write nothing
+  - `--no-venv`: skip virtual environment creation (implies `--no-install`)
+  - `--no-install`: skip dependency installation
+  - `--yes` / `-y`: skip the "Overwrite these files?" confirmation when deploying in place
   - Stack selection: `minimal` | `standard` | `full` (interactive)
 
 ### Create a project with interactive mode
 ```console
 fastkit init --interactive
 ```
-- What it does: Guided step-by-step project setup with intelligent feature selection
+> [!TIP]
+> Guided step-by-step project setup with intelligent feature selection
+
 - Features:
   - **Architecture preset**: `minimal` | `single-module` | `classic-layered` | `domain-starter` (default)
   - **Database selection**: PostgreSQL, MySQL, MongoDB, Redis, SQLite
@@ -98,23 +112,33 @@ fastkit init --interactive
   - **Monitoring**: Loguru, OpenTelemetry, Prometheus
   - **Testing**: Basic (pytest), Coverage, Advanced (with faker, factory-boy)
   - **Utilities**: CORS, Rate-Limiting, Pagination, WebSocket
+  - **Logging**: structured JSON logging with a request-id middleware
+  - **Migrations**: Alembic (async env, baseline revision)
+  - **Tooling**: ruff, pre-commit, GitHub Actions, devcontainer, Makefile (multi-select)
   - **Deployment**: Docker, docker-compose with auto-generated configs
   - **Package manager**: pip, uv, pdm, poetry
   - **Custom packages**: Add your own dependencies
-- Auto-generates (varies by preset — see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
+- Auto-generates (varies by preset - see [the matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/) for details):
   - `main.py` regenerated from selected features for `minimal` / `single-module`; preserved as-shipped for `classic-layered` / `domain-starter`
   - Database and authentication configuration files at preset-specific paths
   - Docker deployment files (`Dockerfile`, `docker-compose.yml`) with the preset's correct uvicorn entrypoint
   - Test configuration (pytest with coverage)
+  - `/health` and `/ready` endpoints on every generated project
+  - Real working code — not just installed packages — for background tasks, caching, WebSocket, pagination, OpenTelemetry, OAuth2 and session-based auth
+  - `--dry-run` previews the exact file tree a run would create, including logging/migrations/tooling artifacts
 
 ### Create a project from a template
 ```console
 fastkit startdemo [TEMPLATE] [OPTIONS]
 ```
-- What it does: Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+> [!TIP]
+> Creates a project from a template (e.g., `fastapi-default`) and installs dependencies
+
 - Key options:
   - `--project-name`, `--author`, `--author-email`, `--description`
   - `--package-manager` [pip|uv|pdm|poetry]
+  - `--dry-run`, `--no-venv`, `--no-install`, `--yes`/`-y` — same meaning as on `init`
+  - Refuses to run if the target project directory already exists (`--dry-run` excepted)
 - Tip: List available templates with `fastkit list-templates`
 
 ### Add a new route
@@ -136,6 +160,25 @@ fastkit runserver [OPTIONS]
 fastkit list-templates
 ```
 
+Available templates:
+
+| Template | Description | Notes |
+|---|---|---|
+| [`fastapi-default`](src/fastapi_fastkit/fastapi_project_template/fastapi-default/README.md-tpl) | Simple FastAPI project with a classic layered layout | Good first choice |
+| [`fastapi-empty`](src/fastapi_fastkit/fastapi_project_template/fastapi-empty/README.md-tpl) | Minimal FastAPI template | Base for `minimal` preset |
+| [`fastapi-single-module`](src/fastapi_fastkit/fastapi_project_template/fastapi-single-module/README.md-tpl) | Single-file FastAPI app | Base for `single-module` preset |
+| [`fastapi-domain-starter`](src/fastapi_fastkit/fastapi_project_template/fastapi-domain-starter/README.md-tpl) | Domain-oriented, pyproject-first starter for medium-sized APIs | Base for `domain-starter` preset |
+| [`fastapi-auth-jwt`](src/fastapi_fastkit/fastapi_project_template/fastapi-auth-jwt/README.md-tpl) | JWT authentication with refresh-token rotation, argon2 hashing and scopes | New in v1.4.0 |
+| [`fastapi-sqlmodel`](src/fastapi_fastkit/fastapi_project_template/fastapi-sqlmodel/README.md-tpl) | Async SQLModel + Alembic migrations + generic CRUD with pagination | New in v1.4.0 |
+| [`fastapi-llm-agent`](src/fastapi_fastkit/fastapi_project_template/fastapi-llm-agent/README.md-tpl) | Streaming Claude chat agent (SSE) with a tool-call loop | New in v1.4.0 |
+| [`fastapi-mcp`](src/fastapi_fastkit/fastapi_project_template/fastapi-mcp/README.md-tpl) | FastAPI app exposed as an MCP server | |
+| [`fastapi-psql-orm`](src/fastapi_fastkit/fastapi_project_template/fastapi-psql-orm/README.md-tpl) | Item management API with PostgreSQL, SQLModel, Alembic and docker-compose | Requires Docker |
+| [`fastapi-custom-response`](src/fastapi_fastkit/fastapi_project_template/fastapi-custom-response/README.md-tpl) | Item management API with a custom response envelope, error handling and pagination | |
+| [`fastapi-async-crud`](src/fastapi_fastkit/fastapi_project_template/fastapi-async-crud/README.md-tpl) | Async item management API | **Deprecated** — use `fastapi-sqlmodel` |
+| [`fastapi-dockerized`](src/fastapi_fastkit/fastapi_project_template/fastapi-dockerized/README.md-tpl) | Dockerized item management API | **Deprecated** — use `fastapi-default` with the Docker option in `init --interactive` |
+
+Deprecated templates still work but are no longer recommended starting points. See [Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/) for a decision guide.
+
 ### Delete a project
 ```console
 fastkit deleteproject <project_name>