FastAPI-fastkit 1.2.1__py3-none-any.whl → 1.4.0__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

@@ -5,6 +5,7 @@
 # --------------------------------------------------------------------------
 import os
 import re
+import tomllib
 import traceback
 from typing import Any, Dict, Optional
 
@@ -24,6 +25,14 @@ logger = get_logger(__name__)
 REGEX = r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b"
 
 
+# Canonical identity markers used to distinguish FastAPI-fastkit-managed
+# projects from unrelated FastAPI projects in the user workspace. Kept as
+# module-level constants so templates, metadata injection, and detection
+# logic all reference the same strings.
+FASTKIT_DESCRIPTION_MARKER = "[FastAPI-fastkit templated]"
+FASTKIT_TOOL_SECTION = "fastapi-fastkit"  # the [tool.<this>] table key
+
+
 def get_optimal_console_size() -> tuple[int, int]:
     """
     Get optimal console size based on terminal dimensions.
@@ -273,19 +282,115 @@ def validate_email(ctx: Context, param: Any, value: Any) -> Any:
 
 def is_fastkit_project(project_dir: str) -> bool:
     """
-    Check if the project was created with fastkit.
-    Inspects the contents of the setup.py file for FastAPI-fastkit markers.
+    Check if the project was created/managed by FastAPI-fastkit.
+
+    Detection precedence (any single match is sufficient):
+
+    1. ``pyproject.toml`` with ``[tool.fastapi-fastkit].managed = true``
+       (machine-readable marker; set by ``fastkit`` during project generation).
+    2. ``pyproject.toml`` ``[project].description`` contains the
+       ``[FastAPI-fastkit templated]`` marker (case-insensitive).
+    3. ``setup.py`` contains ``fastapi-fastkit`` (case-insensitive) — preserves
+       the legacy detection path for projects generated before the pyproject
+       marker existed.
 
     :param project_dir: Path to the project directory
     :return: True if the project was created with fastkit, False otherwise
     """
+    if _pyproject_marks_fastkit(os.path.join(project_dir, "pyproject.toml")):
+        return True
+
     setup_py = os.path.join(project_dir, "setup.py")
-    if not os.path.exists(setup_py):
+    if os.path.exists(setup_py):
+        try:
+            with open(setup_py, "r", encoding="utf-8") as f:
+                content = f.read()
+            if FASTKIT_TOOL_SECTION in content.lower():
+                return True
+        except (OSError, UnicodeDecodeError):
+            pass
+
+    return False
+
+
+def _pyproject_marks_fastkit(pyproject_path: str) -> bool:
+    """Return True if ``pyproject.toml`` carries a FastAPI-fastkit marker.
+
+    Tries structured TOML parsing first (authoritative), falling back to a
+    plain-text scan if the file is malformed so detection still works on
+    hand-edited or partially written pyproject files.
+    """
+    if not os.path.exists(pyproject_path):
         return False
 
     try:
-        with open(setup_py, "r", encoding="utf-8") as f:
-            content = f.read()
-            return "FastAPI-fastkit" in content
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError):
+        return _pyproject_text_marks_fastkit(pyproject_path)
+
+    tool_section = data.get("tool", {}).get(FASTKIT_TOOL_SECTION, {})
+    if isinstance(tool_section, dict) and tool_section.get("managed") is True:
+        return True
+
+    description = data.get("project", {}).get("description", "")
+    if (
+        isinstance(description, str)
+        and FASTKIT_DESCRIPTION_MARKER.lower() in description.lower()
+    ):
+        return True
+
+    return False
+
+
+def _pyproject_text_marks_fastkit(pyproject_path: str) -> bool:
+    """Fallback plain-text scan for malformed pyproject files."""
+    try:
+        with open(pyproject_path, "r", encoding="utf-8") as f:
+            content = f.read().lower()
     except (OSError, UnicodeDecodeError):
         return False
+
+    if f"[tool.{FASTKIT_TOOL_SECTION}]" in content:
+        return True
+    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.2.1.dist-info → fastapi_fastkit-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FastAPI-fastkit
-Version: 1.2.1
+Version: 1.4.0
 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
 
@@ -82,6 +86,12 @@ fastkit init [OPTIONS]
 - 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
@@ -90,6 +100,7 @@ fastkit init --interactive
 ```
 - What it does: 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
   - **Authentication**: JWT, OAuth2, FastAPI-Users, Session-based
   - **Background tasks**: Celery, Dramatiq
@@ -97,14 +108,20 @@ 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:
-  - `main.py` with selected features integrated
-  - Database and authentication configuration files
-  - Docker deployment files (Dockerfile, docker-compose.yml)
+- 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
@@ -114,8 +131,16 @@ fastkit startdemo [TEMPLATE] [OPTIONS]
 - 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`
 
+New in v1.4.0: `fastapi-auth-jwt` (JWT auth with refresh rotation),
+`fastapi-sqlmodel` (async SQLModel + Alembic + generic CRUD), and
+`fastapi-llm-agent` (streaming Claude agent with a tool loop).
+`fastapi-dockerized` and `fastapi-async-crud` are deprecated — they still
+work, but are no longer recommended starting points.
+
 ### Add a new route
 ```console
 fastkit addroute <project_name> <route_name>
@@ -144,9 +169,11 @@ fastkit deleteproject <project_name>
 
 For comprehensive guides and detailed usage instructions, visit our documentation:
 
+- 🧭 **[Which starter should I choose?](https://bnbong.github.io/FastAPI-fastkit/user-guide/choosing-a-starter/)** - Beginner decision guide for `startdemo` templates and interactive presets
 - 📚 **[User Guide](https://bnbong.github.io/FastAPI-fastkit/user-guide/quick-start/)** - Detailed installation and usage guides
 - 🎯 **[Tutorial](https://bnbong.github.io/FastAPI-fastkit/tutorial/getting-started/)** - Step-by-step tutorials for beginners
 - 📖 **[CLI Reference](https://bnbong.github.io/FastAPI-fastkit/user-guide/cli-reference/)** - Complete command reference
+- 🧱 **[Architecture Preset Matrix](https://bnbong.github.io/FastAPI-fastkit/reference/preset-feature-matrix/)** - Per-preset / per-feature contract for interactive generation
 - 🔍 **[Template Quality Assurance](https://bnbong.github.io/FastAPI-fastkit/reference/template-quality-assurance/)** - Automated testing and quality standards
 
 ## Contributing