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

fastapi_fastkit/__init__.py

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

fastapi_fastkit/backend/inspection/__init__.py

@@ -0,0 +1,26 @@
+# --------------------------------------------------------------------------
+# Template inspection package.
+#
+# ``TemplateInspector`` generates a throwaway project from a template and runs
+# the checks defined in the sibling modules against it:
+#
+# - ``checks``      : structure, extensions, dependencies, implementation, tests
+# - ``consistency`` : Python-version pins and dependency drift
+# - ``lint``        : compileall (required) and mypy (opt-in)
+# - ``smoke``       : boots the generated app and probes /docs and /health
+# - ``strategies``  : how the template's own test suite is executed
+# - ``docker``      : Docker Compose orchestration
+# - ``freshness``   : PyPI version-lag warnings
+# - ``report``      : report construction and printing
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+from .context import InspectionContext, InspectionOptions
+from .core import TemplateInspector, inspect_fastapi_template
+
+__all__ = [
+    "InspectionContext",
+    "InspectionOptions",
+    "TemplateInspector",
+    "inspect_fastapi_template",
+]

fastapi_fastkit/backend/inspection/checks.py

@@ -0,0 +1,349 @@
+# --------------------------------------------------------------------------
+# Static template checks: structure, file extensions, declared dependencies,
+# FastAPI implementation and the mandatory test suite.
+#
+# Every function takes an ``InspectionContext`` and returns ``True`` when the
+# check passes, appending a descriptive message to ``ctx.errors`` otherwise.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import ast
+import os
+import tomllib
+from pathlib import Path
+from typing import List, Optional, Set, Tuple
+
+from fastapi_fastkit.backend.main import (
+    _parse_setup_dependencies,
+    find_template_core_modules,
+)
+from fastapi_fastkit.backend.package_managers.poetry_manager import (
+    _parse_pip_requirement,
+)
+from fastapi_fastkit.utils.logging import debug_log
+
+from .context import InspectionContext
+
+ALWAYS_REQUIRED_PATHS = ["tests", "README.md-tpl"]
+METADATA_CANDIDATES = ["pyproject.toml-tpl", "setup.py-tpl"]
+
+
+def extract_pyproject_dependency_names(
+    pyproject_path: Path,
+) -> Tuple[Set[str], Optional[str]]:
+    """Parse a pyproject file 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[str] = set()
+    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 parse_requirements_names(requirements_path: Path) -> Set[str]:
+    """Return the lowercased package names declared in a requirements file."""
+    with open(requirements_path, encoding="utf-8") as f:
+        lines = f.read().splitlines()
+    return {
+        _parse_pip_requirement(line)[0].lower()
+        for line in lines
+        if line.strip() and not line.strip().startswith("#")
+    }
+
+
+def check_file_structure(ctx: InspectionContext) -> bool:
+    """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``.
+    """
+    missing_required = [
+        path
+        for path in ALWAYS_REQUIRED_PATHS
+        if not (ctx.template_path / path).exists()
+    ]
+    has_metadata = any(
+        (ctx.template_path / name).exists() for name in METADATA_CANDIDATES
+    )
+
+    for path in missing_required:
+        ctx.add_error(f"Missing required path: {path}")
+    if not has_metadata:
+        ctx.add_error(
+            "Missing metadata file: expected pyproject.toml-tpl "
+            "(preferred) or setup.py-tpl"
+        )
+
+    if missing_required or not has_metadata:
+        return False
+
+    debug_log("File structure check passed", "info")
+    return True
+
+
+def check_file_extensions(ctx: InspectionContext) -> bool:
+    """Check all Python files in the template carry the .py-tpl extension."""
+    for path in ctx.template_path.rglob("*"):
+        if path.is_file() and path.suffix == ".py":
+            ctx.add_error(f"Found .py file instead of .py-tpl: {path}")
+            return False
+
+    debug_log("File extension check passed", "info")
+    return True
+
+
+def check_dependencies(ctx: InspectionContext) -> bool:
+    """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.
+    """
+    req_path = ctx.template_path / "requirements.txt-tpl"
+    pyproject_path = ctx.template_path / "pyproject.toml-tpl"
+    setup_path = ctx.template_path / "setup.py-tpl"
+
+    sources_checked: List[str] = []
+    fastapi_declared = False
+
+    if req_path.exists():
+        sources_checked.append("requirements.txt-tpl")
+        try:
+            package_names = parse_requirements_names(req_path)
+        except (OSError, UnicodeDecodeError) as e:
+            ctx.add_error(f"Error reading requirements.txt-tpl: {e}")
+            return False
+        debug_log(
+            f"requirements.txt-tpl dependencies: {sorted(package_names)}", "debug"
+        )
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if pyproject_path.exists():
+        sources_checked.append("pyproject.toml-tpl")
+        package_names, parse_error = extract_pyproject_dependency_names(pyproject_path)
+        if parse_error is not None:
+            ctx.add_error(parse_error)
+            return False
+        debug_log(f"pyproject.toml-tpl dependencies: {sorted(package_names)}", "debug")
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if setup_path.exists():
+        sources_checked.append("setup.py-tpl")
+        try:
+            with open(setup_path, encoding="utf-8") as f:
+                content = f.read()
+        except (OSError, UnicodeDecodeError) as e:
+            ctx.add_error(f"Error reading setup.py-tpl: {e}")
+            return False
+        package_names = {
+            _parse_pip_requirement(dep)[0].lower()
+            for dep in _parse_setup_dependencies(content)
+            if dep
+        }
+        debug_log(f"setup.py-tpl dependencies: {sorted(package_names)}", "debug")
+        fastapi_declared = fastapi_declared or "fastapi" in package_names
+
+    if not sources_checked:
+        ctx.add_error(
+            "No dependency source found: expected one of requirements.txt-tpl, "
+            "pyproject.toml-tpl, or setup.py-tpl"
+        )
+        return False
+
+    if not fastapi_declared:
+        ctx.add_error(
+            "FastAPI dependency not found in any source ("
+            + ", ".join(sources_checked)
+            + ")"
+        )
+        return False
+
+    debug_log(
+        f"Dependencies check passed (sources: {', '.join(sources_checked)})", "info"
+    )
+    return True
+
+
+def _module_defines_fastapi_app(source: str) -> bool:
+    """Return True when ``source`` assigns a ``FastAPI(...)`` instance."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return False
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Assign, ast.AnnAssign)):
+            continue
+        value = node.value
+        if not isinstance(value, ast.Call):
+            continue
+        func = value.func
+        name = ""
+        if isinstance(func, ast.Name):
+            name = func.id
+        elif isinstance(func, ast.Attribute):
+            name = func.attr
+        if name == "FastAPI":
+            return True
+    return False
+
+
+def check_fastapi_implementation(ctx: InspectionContext) -> bool:
+    """Check the generated project really instantiates a FastAPI application.
+
+    This is a static (AST) guard so a broken main module is reported before
+    the far more expensive smoke test boots a server.
+    """
+    try:
+        core_modules = find_template_core_modules(ctx.temp_dir)
+        debug_log(f"Found core modules: {core_modules}", "debug")
+
+        if not core_modules["main"]:
+            ctx.add_error("main.py not found in template")
+            return False
+
+        with open(core_modules["main"], encoding="utf-8") as f:
+            content = f.read()
+    except (OSError, UnicodeDecodeError) as e:
+        ctx.add_error(f"Error checking FastAPI implementation: {e}")
+        return False
+
+    if not _module_defines_fastapi_app(content):
+        ctx.add_error("FastAPI app creation not found in main.py")
+        debug_log(f"main.py content preview: {content[:200]}...", "debug")
+        return False
+
+    debug_log("FastAPI implementation check passed", "info")
+    return True
+
+
+def check_tests_present(ctx: InspectionContext) -> bool:
+    """A template must ship at least one test module.
+
+    Previously a missing ``tests/`` directory only produced a warning; an
+    untested template is now a hard failure.
+    """
+    tests_dir = ctx.template_path / "tests"
+    if not tests_dir.is_dir():
+        ctx.add_error("Missing required path: tests (templates must ship tests)")
+        return False
+
+    test_files = [
+        path
+        for path in tests_dir.rglob("*")
+        if path.is_file()
+        and path.name.startswith("test_")
+        and path.name.endswith((".py-tpl", ".py"))
+    ]
+    if not test_files:
+        ctx.add_error(
+            "No test module found under tests/: at least one test_*.py-tpl file "
+            "is required"
+        )
+        return False
+
+    debug_log(f"Test suite check passed ({len(test_files)} test files)", "info")
+    return True
+
+
+def check_no_junk_files(ctx: InspectionContext) -> bool:
+    """Reject OS/editor artifacts and build leftovers committed to a template."""
+    junk_names = {".DS_Store", "Thumbs.db", "desktop.ini", ".AppleDouble"}
+    junk_dirs = {"__pycache__", ".pytest_cache", ".mypy_cache", ".venv"}
+    found: List[str] = []
+
+    for path in ctx.template_path.rglob("*"):
+        rel = path.relative_to(ctx.template_path)
+        if path.is_dir():
+            if path.name in junk_dirs:
+                found.append(str(rel))
+        elif path.name in junk_names or path.suffix in {".pyc", ".pyo"}:
+            found.append(str(rel))
+
+    if found:
+        for item in sorted(found):
+            ctx.add_error(f"Junk file committed to template: {item}")
+        return False
+
+    debug_log("Junk file check passed", "info")
+    return True
+
+
+def check_no_placeholder_residue(ctx: InspectionContext) -> bool:
+    """Every ``<placeholder>`` must be substituted during project generation.
+
+    The inspection generates a real project from the template (copy +
+    metadata injection), so any surviving placeholder token means the
+    template declares a variable the generator does not know how to fill.
+    """
+    placeholders = [
+        "<project_name>",
+        "<author>",
+        "<author_email>",
+        "<description>",
+    ]
+    text_suffixes = {
+        ".py",
+        ".toml",
+        ".cfg",
+        ".txt",
+        ".md",
+        ".yml",
+        ".yaml",
+        ".json",
+        ".sh",
+        ".env",
+        ".ini",
+    }
+    residue: List[str] = []
+
+    for root, dirs, files in os.walk(ctx.temp_dir):
+        dirs[:] = [d for d in dirs if d not in {".venv", "venv", "__pycache__", ".git"}]
+        for file_name in files:
+            file_path = os.path.join(root, file_name)
+            suffix = Path(file_name).suffix
+            if suffix and suffix not in text_suffixes:
+                continue
+            try:
+                with open(file_path, encoding="utf-8") as f:
+                    content = f.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            hits = [token for token in placeholders if token in content]
+            if hits:
+                rel = os.path.relpath(file_path, ctx.temp_dir)
+                residue.append(f"{rel}: {', '.join(hits)}")
+
+    if residue:
+        for item in sorted(residue):
+            ctx.add_error(f"Unsubstituted placeholder in generated project: {item}")
+        return False
+
+    debug_log("Placeholder substitution check passed", "info")
+    return True

fastapi_fastkit/backend/inspection/consistency.py

@@ -0,0 +1,125 @@
+# --------------------------------------------------------------------------
+# Configuration consistency checks for a template's metadata files.
+#
+# FastAPI-fastkit pins generated projects to Python 3.12, so every tool that
+# carries a Python version must agree. The dependency drift check keeps
+# ``pyproject.toml-tpl`` and ``requirements.txt-tpl`` from diverging, and the
+# self-dependency check keeps fastkit itself out of generated runtimes.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import tomllib
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi_fastkit.utils.logging import debug_log
+
+from .checks import extract_pyproject_dependency_names, parse_requirements_names
+from .context import InspectionContext
+
+TARGET_PYTHON = "3.12"
+TARGET_PYTHON_TAG = "py312"
+#: fastkit is a scaffolding tool - a generated project must not depend on it.
+SELF_PACKAGE_NAME = "fastapi-fastkit"
+
+
+def _load_pyproject(pyproject_path: Path) -> Optional[Dict[str, Any]]:
+    """Load a pyproject template file, returning ``None`` when unreadable."""
+    try:
+        with open(pyproject_path, "rb") as f:
+            data: Dict[str, Any] = tomllib.load(f)
+        return data
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as e:
+        debug_log(f"Failed to parse {pyproject_path}: {e}", "warning")
+        return None
+
+
+def _check_python_versions(ctx: InspectionContext, data: Dict[str, Any]) -> bool:
+    """requires-python / black target-version / mypy python_version must be 3.12."""
+    passed = True
+    tools = data.get("tool", {})
+
+    requires_python = data.get("project", {}).get("requires-python")
+    if requires_python is None:
+        ctx.add_error("pyproject.toml-tpl is missing [project].requires-python")
+        passed = False
+    elif TARGET_PYTHON not in str(requires_python):
+        ctx.add_error(
+            f"requires-python must target Python {TARGET_PYTHON}, "
+            f"found {requires_python!r}"
+        )
+        passed = False
+
+    black_target = tools.get("black", {}).get("target-version")
+    if black_target is not None:
+        targets = black_target if isinstance(black_target, list) else [black_target]
+        if TARGET_PYTHON_TAG not in targets:
+            ctx.add_error(
+                f"[tool.black].target-version must include {TARGET_PYTHON_TAG!r}, "
+                f"found {black_target!r}"
+            )
+            passed = False
+
+    mypy_version = tools.get("mypy", {}).get("python_version")
+    if mypy_version is not None and str(mypy_version) != TARGET_PYTHON:
+        ctx.add_error(
+            f"[tool.mypy].python_version must be {TARGET_PYTHON!r}, "
+            f"found {mypy_version!r}"
+        )
+        passed = False
+
+    return passed
+
+
+def _check_self_dependency(ctx: InspectionContext, names: set[str]) -> bool:
+    """Generated projects must not ship FastAPI-fastkit as a runtime dependency."""
+    if SELF_PACKAGE_NAME in {name.lower() for name in names}:
+        ctx.add_error(
+            "FastAPI-fastkit must not be a runtime dependency of a generated "
+            "project (remove it from the template's dependency list)"
+        )
+        return False
+    return True
+
+
+def check_configuration_consistency(ctx: InspectionContext) -> bool:
+    """Validate Python-version pins, dependency drift and self-dependency."""
+    pyproject_path = ctx.template_path / "pyproject.toml-tpl"
+    requirements_path = ctx.template_path / "requirements.txt-tpl"
+    passed = True
+
+    pyproject_deps: set[str] = set()
+    if pyproject_path.exists():
+        data = _load_pyproject(pyproject_path)
+        if data is None:
+            ctx.add_error("Invalid pyproject.toml-tpl: could not be parsed")
+            return False
+        passed = _check_python_versions(ctx, data) and passed
+
+        pyproject_deps, parse_error = extract_pyproject_dependency_names(pyproject_path)
+        if parse_error is not None:
+            ctx.add_error(parse_error)
+            return False
+        passed = _check_self_dependency(ctx, pyproject_deps) and passed
+
+    requirement_names: set[str] = set()
+    if requirements_path.exists():
+        try:
+            requirement_names = parse_requirements_names(requirements_path)
+        except (OSError, UnicodeDecodeError) as e:
+            ctx.add_error(f"Error reading requirements.txt-tpl: {e}")
+            return False
+        passed = _check_self_dependency(ctx, requirement_names) and passed
+
+    if pyproject_deps and requirement_names:
+        missing: List[str] = sorted(pyproject_deps - requirement_names)
+        if missing:
+            ctx.add_error(
+                "Dependency drift: declared in pyproject.toml-tpl but absent from "
+                "requirements.txt-tpl: " + ", ".join(missing)
+            )
+            passed = False
+
+    if passed:
+        debug_log("Configuration consistency check passed", "info")
+    return passed

fastapi_fastkit/backend/inspection/context.py

@@ -0,0 +1,71 @@
+# --------------------------------------------------------------------------
+# Shared state for the template inspection pipeline.
+#
+# Every check and test strategy operates on an ``InspectionContext``: it owns
+# the template source path, the temporary generated-project path, the loaded
+# template configuration and the accumulated errors/warnings.
+#
+# @author bnbong
+# --------------------------------------------------------------------------
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi_fastkit.utils.logging import debug_log
+
+
+@dataclass
+class InspectionOptions:
+    """Tunable switches for a single inspection run."""
+
+    #: Skip every network access (dependency freshness lookups).
+    offline: bool = False
+    #: Boot the generated project with uvicorn and probe its HTTP endpoints.
+    run_smoke_test: bool = True
+    #: Run ``mypy`` inside the generated project (opt-in, slow).
+    run_mypy: bool = False
+    #: Run the template's own test suite.
+    run_template_tests: bool = True
+    #: Seconds to wait for the smoke-test server to answer.
+    smoke_timeout: int = 60
+
+
+@dataclass
+class InspectionContext:
+    """Mutable state shared by all inspection steps."""
+
+    template_path: Path
+    temp_dir: str
+    options: InspectionOptions = field(default_factory=InspectionOptions)
+    template_config: Optional[Dict[str, Any]] = None
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    #: Populated by a test strategy so later checks can reuse the environment.
+    venv_path: Optional[str] = None
+    #: Populated when a test strategy already exercised the app's HTTP surface
+    #: (the Docker strategy probes the running container), so the Smoke Test
+    #: step reuses that verdict instead of booting a second server.
+    smoke_result: Optional[bool] = None
+
+    def add_error(self, message: str) -> None:
+        """Record a fatal finding."""
+        self.errors.append(message)
+        debug_log(f"Inspection error: {message}", "error")
+
+    def add_warning(self, message: str) -> None:
+        """Record a non-fatal finding."""
+        self.warnings.append(message)
+        debug_log(f"Inspection warning: {message}", "warning")
+
+    def temp_path(self, *parts: str) -> str:
+        """Join ``parts`` onto the generated project directory."""
+        return os.path.join(self.temp_dir, *parts)
+
+    def python_executable(self) -> Optional[str]:
+        """Return the interpreter of the inspection venv, if one was created."""
+        if not self.venv_path:
+            return None
+        if os.name == "nt":  # pragma: no cover - Windows-only branch
+            return os.path.join(self.venv_path, "Scripts", "python")
+        return os.path.join(self.venv_path, "bin", "python")