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

fastapi_fastkit/__init__.py

@@ -1 +1 @@
-__version__ = 'v1.2.0'
+__version__ = 'v1.3.0'

fastapi_fastkit/backend/inspector.py

@@ -23,19 +23,23 @@ import os
 import shutil
 import subprocess
 import sys
+import tomllib
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 import yaml
 
 from fastapi_fastkit.backend.main import (
+    _parse_setup_dependencies,
     create_venv,
     find_template_core_modules,
     inject_project_metadata,
     install_dependencies_with_manager,
 )
+from fastapi_fastkit.backend.package_managers.poetry_manager import (
+    _parse_pip_requirement,
+)
 from fastapi_fastkit.backend.transducer import copy_and_convert_template
-from fastapi_fastkit.core.settings import settings
 from fastapi_fastkit.utils.logging import debug_log, get_logger
 from fastapi_fastkit.utils.main import print_error, print_success, print_warning
 
@@ -127,7 +131,6 @@ class TemplateInspector:
 
     def _force_cleanup_directory(self, directory_path: str) -> None:
         """Force cleanup of directory with multiple strategies."""
-        import stat
         import time
 
         max_retries = 5
@@ -396,20 +399,39 @@ class TemplateInspector:
         return True
 
     def _check_file_structure(self) -> bool:
-        """Check the required file and directory structure."""
-        required_paths = [
-            "tests",
-            "requirements.txt-tpl",
-            "setup.py-tpl",
-            "README.md-tpl",
+        """Check the required file and directory structure.
+
+        Modern templates may ship ``pyproject.toml-tpl`` as the primary metadata
+        file; ``setup.py-tpl`` remains accepted for backward compatibility.
+        A template must provide at least one of the two. ``requirements.txt-tpl``
+        is no longer strictly required when ``pyproject.toml-tpl`` declares
+        ``[project].dependencies``.
+        """
+        always_required = ["tests", "README.md-tpl"]
+        metadata_candidates = ["pyproject.toml-tpl", "setup.py-tpl"]
+
+        missing_required = [
+            path for path in always_required if not (self.template_path / path).exists()
         ]
+        has_metadata = any(
+            (self.template_path / name).exists() for name in metadata_candidates
+        )
 
-        for path in required_paths:
-            if not (self.template_path / path).exists():
+        if missing_required:
+            for path in missing_required:
                 error_msg = f"Missing required path: {path}"
                 self.errors.append(error_msg)
                 debug_log(f"File structure check failed: {error_msg}", "error")
-                return False
+        if not has_metadata:
+            error_msg = (
+                "Missing metadata file: expected pyproject.toml-tpl "
+                "(preferred) or setup.py-tpl"
+            )
+            self.errors.append(error_msg)
+            debug_log(f"File structure check failed: {error_msg}", "error")
+
+        if missing_required or not has_metadata:
+            return False
 
         debug_log("File structure check passed", "info")
         return True
@@ -427,40 +449,139 @@ class TemplateInspector:
         return True
 
     def _check_dependencies(self) -> bool:
-        """Check the dependencies in both setup.py-tpl and requirements.txt-tpl."""
+        """Check that FastAPI is declared in at least one supported source.
+
+        All three metadata sources are consulted independently:
+
+        - ``requirements.txt-tpl``
+        - ``pyproject.toml-tpl`` ``[project].dependencies``
+        - ``setup.py-tpl`` ``install_requires``
+
+        The check passes if *any* source declares ``fastapi``, so a template
+        with a stale ``requirements.txt-tpl`` still passes when
+        ``pyproject.toml-tpl`` is authoritative. It fails only when every
+        present source is missing ``fastapi`` (or when no source exists at
+        all — that also implies no metadata file, which
+        ``_check_file_structure`` already rejects).
+        """
         req_path = self.template_path / "requirements.txt-tpl"
+        pyproject_path = self.template_path / "pyproject.toml-tpl"
         setup_path = self.template_path / "setup.py-tpl"
 
-        if not req_path.exists():
-            error_msg = "requirements.txt-tpl not found"
-            self.errors.append(error_msg)
-            debug_log(f"Dependencies check failed: {error_msg}", "error")
-            return False
-        if not setup_path.exists():
-            error_msg = "setup.py-tpl not found"
+        sources_checked: List[str] = []
+        fastapi_declared = False
+
+        if req_path.exists():
+            sources_checked.append("requirements.txt-tpl")
+            try:
+                with open(req_path, encoding="utf-8") as f:
+                    deps = f.read().splitlines()
+                package_names = {
+                    _parse_pip_requirement(dep)[0].lower()
+                    for dep in deps
+                    if dep.strip() and not dep.strip().startswith("#")
+                }
+                debug_log(
+                    f"requirements.txt-tpl dependencies: {sorted(package_names)}",
+                    "debug",
+                )
+                if "fastapi" in package_names:
+                    fastapi_declared = True
+            except (OSError, UnicodeDecodeError) as e:
+                error_msg = f"Error reading requirements.txt-tpl: {e}"
+                self.errors.append(error_msg)
+                debug_log(f"Dependencies check failed: {error_msg}", "error")
+                return False
+
+        if pyproject_path.exists():
+            sources_checked.append("pyproject.toml-tpl")
+            package_names, parse_error = self._extract_pyproject_dependency_names(
+                pyproject_path
+            )
+            if parse_error is not None:
+                self.errors.append(parse_error)
+                debug_log(f"Dependencies check failed: {parse_error}", "error")
+                return False
+            debug_log(
+                f"pyproject.toml-tpl dependencies: {sorted(package_names)}", "debug"
+            )
+            if "fastapi" in package_names:
+                fastapi_declared = True
+
+        if setup_path.exists():
+            sources_checked.append("setup.py-tpl")
+            try:
+                with open(setup_path, encoding="utf-8") as f:
+                    content = f.read()
+                deps = _parse_setup_dependencies(content)
+                package_names = {
+                    _parse_pip_requirement(dep)[0].lower() for dep in deps if dep
+                }
+                debug_log(
+                    f"setup.py-tpl dependencies: {sorted(package_names)}", "debug"
+                )
+                if "fastapi" in package_names:
+                    fastapi_declared = True
+            except (OSError, UnicodeDecodeError) as e:
+                error_msg = f"Error reading setup.py-tpl: {e}"
+                self.errors.append(error_msg)
+                debug_log(f"Dependencies check failed: {error_msg}", "error")
+                return False
+
+        if not sources_checked:
+            error_msg = (
+                "No dependency source found: expected one of requirements.txt-tpl, "
+                "pyproject.toml-tpl, or setup.py-tpl"
+            )
             self.errors.append(error_msg)
             debug_log(f"Dependencies check failed: {error_msg}", "error")
             return False
 
-        try:
-            with open(req_path, encoding="utf-8") as f:
-                deps = f.read().splitlines()
-                package_names = [dep.split("==")[0] for dep in deps if dep]
-                debug_log(f"Found dependencies: {package_names}", "debug")
-                if "fastapi" not in package_names:
-                    error_msg = "FastAPI dependency not found in requirements.txt-tpl"
-                    self.errors.append(error_msg)
-                    debug_log(f"Dependencies check failed: {error_msg}", "error")
-                    return False
-        except (OSError, UnicodeDecodeError) as e:
-            error_msg = f"Error reading requirements.txt-tpl: {e}"
+        if not fastapi_declared:
+            error_msg = (
+                "FastAPI dependency not found in any source ("
+                + ", ".join(sources_checked)
+                + ")"
+            )
             self.errors.append(error_msg)
             debug_log(f"Dependencies check failed: {error_msg}", "error")
             return False
 
-        debug_log("Dependencies check passed", "info")
+        debug_log(
+            f"Dependencies check passed (sources: {', '.join(sources_checked)})",
+            "info",
+        )
         return True
 
+    @staticmethod
+    def _extract_pyproject_dependency_names(
+        pyproject_path: Path,
+    ) -> Tuple[set, Optional[str]]:  # type: ignore
+        """Parse a pyproject.toml-tpl and return (lowercased dep names, error).
+
+        ``error`` is ``None`` on success. Returns an empty set with a descriptive
+        error string when the file is unreadable or malformed.
+        """
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+        except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+            return set(), f"Invalid pyproject.toml-tpl: {e}"
+
+        project = data.get("project", {})
+        raw_deps = project.get("dependencies", []) or []
+        if not isinstance(raw_deps, list):
+            return set(), "pyproject.toml-tpl [project].dependencies must be a list"
+
+        names: set = set()  # type: ignore
+        for dep in raw_deps:
+            if not isinstance(dep, str) or not dep.strip():
+                continue
+            name = _parse_pip_requirement(dep)[0]
+            if name:
+                names.add(name.lower())
+        return names, None
+
     def _check_fastapi_implementation(self) -> bool:
         """Check if the template has a proper FastAPI server implementation."""
         try:

fastapi_fastkit/backend/interactive/__init__.py

@@ -9,6 +9,7 @@
 from .config_builder import InteractiveConfigBuilder
 from .prompts import (
     prompt_additional_features,
+    prompt_architecture_preset,
     prompt_authentication_selection,
     prompt_basic_info,
     prompt_caching_selection,
@@ -31,6 +32,7 @@ from .validators import (
 __all__ = [
     "InteractiveConfigBuilder",
     "prompt_basic_info",
+    "prompt_architecture_preset",
     "prompt_template_selection",
     "prompt_database_selection",
     "prompt_authentication_selection",

fastapi_fastkit/backend/interactive/config_builder.py

@@ -12,6 +12,7 @@ from fastapi_fastkit.utils.main import console, print_warning
 
 from .prompts import (
     prompt_additional_features,
+    prompt_architecture_preset,
     prompt_basic_info,
     prompt_template_selection,
 )
@@ -51,11 +52,15 @@ class InteractiveConfigBuilder:
         # Step 1: Basic information
         self._collect_basic_info()
 
-        # Step 2: Always use Empty template as base for interactive mode
+        # Step 2: Architecture preset — chosen early so downstream prompts
+        # (and later, preset-specific scaffolding) can branch on the layout.
+        self._collect_architecture_preset()
+
+        # Step 3: Always use Empty template as base for interactive mode
         # (Feature selection will build the project incrementally)
         self.config["base_template"] = None  # None = Empty project
 
-        # Step 3: Feature selections
+        # Step 4: Feature selections
         self._collect_feature_selections()
 
         # Step 4: Build final configuration
@@ -78,6 +83,20 @@ class InteractiveConfigBuilder:
         basic_info = prompt_basic_info()
         self.config.update(basic_info)
 
+    def _collect_architecture_preset(self) -> None:
+        """Collect the user's architecture preset choice.
+
+        Persists the canonical id on the config under ``architecture_preset``
+        (used by downstream code) plus the human-readable description under
+        ``architecture_preset_description`` (used by the confirmation summary
+        so users see what their choice means, not just the raw id).
+        """
+        preset = prompt_architecture_preset(self.settings)
+        self.config["architecture_preset"] = preset
+        self.config["architecture_preset_description"] = (
+            self.settings.ARCHITECTURE_PRESETS.get(preset, "")
+        )
+
     def _collect_template_selection(self) -> None:
         """Collect template selection."""
         template = prompt_template_selection(self.settings)

fastapi_fastkit/backend/interactive/prompts.py

@@ -15,7 +15,6 @@
 from typing import Any, Dict, List, Optional, cast
 
 import click
-from rich.panel import Panel
 
 from fastapi_fastkit.utils.main import console, print_error
 
@@ -64,6 +63,58 @@ def prompt_basic_info() -> Dict[str, str]:
     }
 
 
+def prompt_architecture_preset(settings: Any) -> str:
+    """
+    Prompt for the project's architecture preset.
+
+    Run early in the interactive flow so downstream prompts (and later,
+    preset-specific scaffolding) can branch on the user's choice. Returns
+    the canonical preset id (one of the keys in
+    ``settings.ARCHITECTURE_PRESETS``).
+
+    The recommended default (``settings.DEFAULT_ARCHITECTURE_PRESET``) is
+    annotated as such in the rendered table so users can spot it at a glance
+    and accept it with a single Enter press.
+
+    Args:
+        settings: FastkitConfig instance
+
+    Returns:
+        Preset id, e.g. ``"domain-starter"``.
+    """
+    console.print("\n[bold cyan]🧱 Architecture Preset[/bold cyan]")
+    console.print(
+        "[dim]Pick a project layout. Generation logic for each preset is "
+        "rolled out incrementally — your choice is recorded in the "
+        "config either way.[/dim]\n"
+    )
+
+    presets: Dict[str, str] = settings.ARCHITECTURE_PRESETS
+    default_id: str = settings.DEFAULT_ARCHITECTURE_PRESET
+    # Derive a display-only mapping so the recommended default is visibly
+    # annotated without mutating the canonical catalog in settings.
+    display_options: Dict[str, str] = {
+        preset_id: (
+            f"{description} [bold green](recommended default)[/bold green]"
+            if preset_id == default_id
+            else description
+        )
+        for preset_id, description in presets.items()
+    }
+    render_selection_table("Architecture Presets", display_options)
+
+    preset_ids = list(presets.keys())
+    default_idx = preset_ids.index(default_id) + 1
+
+    choice = click.prompt(
+        f"\nSelect architecture preset (default: {default_id})",
+        type=click.IntRange(1, len(preset_ids)),
+        default=default_idx,
+    )
+
+    return cast(str, preset_ids[choice - 1])
+
+
 def prompt_template_selection(settings: Any) -> Optional[str]:
     """
     Prompt for base template selection.

fastapi_fastkit/backend/interactive/selectors.py

@@ -133,6 +133,16 @@ def confirm_selections(config: Dict[str, Any]) -> bool:
     table.add_row("Email", config.get("author_email", "N/A"))
     table.add_row("Description", config.get("description", "N/A"))
 
+    # Architecture preset (interactive ``init`` always sets this; older
+    # callers may not — guard with a falsy check to stay backward compatible).
+    preset = config.get("architecture_preset")
+    if preset:
+        preset_description = config.get("architecture_preset_description", "")
+        table.add_row(
+            "Architecture Preset",
+            f"{preset} — {preset_description}" if preset_description else preset,
+        )
+
     # Template
     if config.get("base_template"):
         table.add_row("Base Template", config["base_template"])

fastapi_fastkit/backend/main.py

@@ -5,6 +5,7 @@
 # --------------------------------------------------------------------------
 import os
 import re
+import tomllib
 from typing import Dict, List
 
 import click
@@ -18,8 +19,9 @@ from fastapi_fastkit.core.exceptions import BackendExceptions
 from fastapi_fastkit.core.settings import settings
 from fastapi_fastkit.utils.logging import debug_log, get_logger
 from fastapi_fastkit.utils.main import (
+    FASTKIT_DESCRIPTION_MARKER,
+    FASTKIT_TOOL_SECTION,
     handle_exception,
-    print_error,
     print_info,
     print_success,
     print_warning,
@@ -82,12 +84,19 @@ def find_template_core_modules(project_dir: str) -> Dict[str, str]:
 
 def read_template_stack(template_path: str) -> List[str]:
     """
-    Read dependencies from template requirements.txt-tpl file or setup.py-tpl file.
+    Read dependencies from a template's metadata files.
+
+    Lookup order preserves legacy behaviour for templates that still ship
+    ``requirements.txt-tpl`` while allowing modern pyproject-first templates
+    to resolve their stack from ``pyproject.toml-tpl``:
+
+    1. ``requirements.txt-tpl`` (legacy, highest precedence)
+    2. ``pyproject.toml-tpl`` ``[project].dependencies``
+    3. ``setup.py-tpl`` ``install_requires``
 
     :param template_path: Path to the template directory
-    :return: List of dependencies
+    :return: List of PEP 508 requirement strings
     """
-    # First try requirements.txt-tpl
     req_file = os.path.join(template_path, "requirements.txt-tpl")
     if os.path.exists(req_file):
         try:
@@ -100,7 +109,12 @@ def read_template_stack(template_path: str) -> List[str]:
             )
             return []
 
-    # Fallback: try to read from setup.py-tpl for legacy templates
+    pyproject_file = os.path.join(template_path, "pyproject.toml-tpl")
+    if os.path.exists(pyproject_file):
+        deps = _parse_pyproject_dependencies(pyproject_file)
+        if deps:
+            return deps
+
     setup_file = os.path.join(template_path, "setup.py-tpl")
     if os.path.exists(setup_file):
         try:
@@ -153,6 +167,28 @@ def _parse_setup_dependencies(content: str) -> List[str]:
     return []
 
 
+def _parse_pyproject_dependencies(pyproject_path: str) -> List[str]:
+    """
+    Parse dependencies from a ``pyproject.toml-tpl`` file.
+
+    Returns the list of PEP 508 requirement strings from
+    ``[project].dependencies``. Returns an empty list on parse errors so
+    callers can fall through to the next metadata source.
+    """
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+        debug_log(f"Error reading pyproject.toml template: {e}", "error")
+        return []
+
+    project = data.get("project", {})
+    raw_deps = project.get("dependencies", []) or []
+    if not isinstance(raw_deps, list):
+        return []
+    return [dep.strip() for dep in raw_deps if isinstance(dep, str) and dep.strip()]
+
+
 # ------------------------------------------------------------
 # Project Setup Functions
 # ------------------------------------------------------------
@@ -185,6 +221,7 @@ def inject_project_metadata(
             description,
         )
         _process_config_file(core_modules.get("config", ""), project_name)
+        _process_main_file(core_modules.get("main", ""), project_name)
 
         print_success("Project metadata injected successfully")
 
@@ -235,6 +272,40 @@ def _process_setup_file(
         raise BackendExceptions(f"Failed to process setup.py: {e}")
 
 
+def _process_main_file(main_py: str, project_name: str) -> None:
+    """
+    Replace project name placeholders in the template main.py file.
+
+    Some templates (e.g. fastapi-single-module) inline the project name directly
+    in main.py rather than reading it from a settings module, so the placeholder
+    must be substituted here as well.
+
+    :param main_py: Path to main.py file
+    :param project_name: Project name
+    """
+    if not main_py or not os.path.exists(main_py):
+        return
+
+    try:
+        with open(main_py, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        if "<project_name>" not in content:
+            return
+
+        content = content.replace("<project_name>", project_name)
+
+        with open(main_py, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        debug_log("Injected project name into main.py", "info")
+        print_info("Injected project name into main.py")
+
+    except (OSError, UnicodeDecodeError) as e:
+        debug_log(f"Error processing main.py: {e}", "error")
+        raise BackendExceptions(f"Failed to process main.py: {e}")
+
+
 def _process_config_file(config_py: str, project_name: str) -> None:
     """
     Process config file and inject project name.
@@ -297,6 +368,8 @@ def _process_pyproject_file(
         for placeholder, value in replacements.items():
             content = content.replace(placeholder, value)
 
+        content = _ensure_pyproject_fastkit_markers(content)
+
         with open(pyproject_toml, "w", encoding="utf-8") as f:
             f.write(content)
 
@@ -308,6 +381,41 @@ def _process_pyproject_file(
         raise BackendExceptions(f"Failed to process pyproject.toml: {e}")
 
 
+_DESCRIPTION_LINE_PATTERN = re.compile(
+    r'^(?P<prefix>description\s*=\s*)"(?P<value>.*?)"(?P<suffix>\s*)$',
+    re.MULTILINE,
+)
+
+
+def _ensure_pyproject_fastkit_markers(content: str) -> str:
+    """Idempotently ensure pyproject content carries FastAPI-fastkit markers.
+
+    Adds the canonical description marker if the ``description`` field does
+    not already include it (case-insensitive check), and appends a
+    ``[tool.fastapi-fastkit]`` section with ``managed = true`` if one is not
+    already present. Safe to run on already-marked content — no duplicates
+    are introduced.
+    """
+    marker = FASTKIT_DESCRIPTION_MARKER
+    match = _DESCRIPTION_LINE_PATTERN.search(content)
+    if match and marker.lower() not in match.group("value").lower():
+        existing = match.group("value")
+        new_value = f"{marker} {existing}".strip() if existing else marker
+        content = (
+            content[: match.start()]
+            + f'{match.group("prefix")}"{new_value}"{match.group("suffix")}'
+            + content[match.end() :]
+        )
+
+    tool_header = f"[tool.{FASTKIT_TOOL_SECTION}]"
+    if tool_header not in content:
+        if not content.endswith("\n"):
+            content += "\n"
+        content += f"\n{tool_header}\nmanaged = true\n"
+
+    return content
+
+
 def update_setup_py_dependencies(project_dir: str, dependencies: List[str]) -> None:
     """
     Update setup.py file's install_requires list with new dependencies.
@@ -519,7 +627,7 @@ def _ensure_project_structure(src_dir: str) -> Dict[str, str]:
             # Create __init__.py if it doesn't exist
             init_file = os.path.join(dir_path, "__init__.py")
             if not os.path.exists(init_file):
-                with open(init_file, "w") as f:
+                with open(init_file, "w"):
                     pass
 
     return target_dirs

fastapi_fastkit/backend/package_managers/factory.py

@@ -136,7 +136,7 @@ class PackageManagerFactory:
         :param manager_class: Package manager class
         """
         if not issubclass(manager_class, BasePackageManager):
-            raise ValueError(f"Manager class must inherit from BasePackageManager")
+            raise ValueError("Manager class must inherit from BasePackageManager")
 
         self._managers[name.lower()] = manager_class
         debug_log(f"Registered package manager: {name}", "info")

fastapi_fastkit/backend/package_managers/pdm_manager.py

@@ -152,11 +152,11 @@ class PdmManager(BasePackageManager):
 
             # Create basic pyproject.toml content as string
             pyproject_content = f"""[project]
-name = "{project_name or 'fastapi-project'}"
+name = "{project_name or "fastapi-project"}"
 version = "0.1.0"
-description = "{description or 'A FastAPI project'}"
+description = "{description or "A FastAPI project"}"
 authors = [
-    {{name = "{author or 'Author'}", email = "{author_email or 'author@example.com'}"}},
+    {{name = "{author or "Author"}", email = "{author_email or "author@example.com"}"}},
 ]
 dependencies = {deps_toml}
 requires-python = ">=3.8"