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

fastapi_fastkit/backend/package_managers/base.py

@@ -3,11 +3,32 @@
 #
 # @author bnbong bbbong9@gmail.com
 # --------------------------------------------------------------------------
+import os
 import subprocess
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from fastapi_fastkit.core.exceptions import BackendExceptions
+from fastapi_fastkit.core.settings import settings
+from fastapi_fastkit.utils.logging import debug_log
+from fastapi_fastkit.utils.main import console, handle_exception, print_error
+
+
+def _with_stderr_tail(message: str, stderr: str, max_lines: int = 5) -> str:
+    """Append the last few non-empty stderr lines to an error message.
+
+    :param message: Base error message
+    :param stderr: Captured stderr of the failed command
+    :param max_lines: Maximum number of trailing stderr lines to include
+    :return: ``message`` unchanged when stderr carries nothing useful
+    """
+    lines = [line.strip() for line in (stderr or "").splitlines()]
+    lines = [line for line in lines if line]
+    if not lines:
+        return message
+    return f"{message}: " + " | ".join(lines[-max_lines:])
+
 
 class BasePackageManager(ABC):
     """
@@ -130,11 +151,162 @@ class BasePackageManager(ABC):
             "capture_output": True,
             "text": True,
             "cwd": str(self.project_dir),
+            "timeout": settings.get_subprocess_timeout(),
         }
         default_kwargs.update(kwargs)
 
         return subprocess.run(command, **default_kwargs)
 
+    def _check_command_available(self, command: List[str]) -> bool:
+        """
+        Check whether a command can be executed on the current system.
+
+        :param command: Version probe command (e.g. ``["uv", "--version"]``)
+        :return: True if the command executed successfully
+        """
+        try:
+            subprocess.run(
+                command,
+                check=True,
+                capture_output=True,
+                text=True,
+                timeout=settings.get_subprocess_timeout("check"),
+            )
+            return True
+        except (
+            subprocess.CalledProcessError,
+            subprocess.TimeoutExpired,
+            FileNotFoundError,
+            OSError,
+        ):
+            return False
+
+    def _run_checked(
+        self,
+        command: List[str],
+        status_msg: str,
+        error_prefix: str,
+        cwd: Optional[str] = None,
+        timeout: Optional[int] = None,
+        summarize_output: bool = False,
+    ) -> subprocess.CompletedProcess[str]:
+        """
+        Run a command with a status spinner and uniform error handling.
+
+        :param command: Command to run as list of strings
+        :param status_msg: Message shown while the command runs
+        :param error_prefix: Message used for the raised ``BackendExceptions``
+        :param cwd: Working directory (defaults to the project directory)
+        :param timeout: Timeout in seconds (defaults to the general timeout)
+        :param summarize_output: Print the tail of the command output on success
+        :return: CompletedProcess instance
+        :raises BackendExceptions: if the command fails, times out or cannot run
+        """
+        timeout = timeout if timeout is not None else settings.get_subprocess_timeout()
+
+        try:
+            with console.status(f"[bold green]{status_msg}"):
+                result: subprocess.CompletedProcess[str] = subprocess.run(
+                    command,
+                    cwd=cwd if cwd is not None else str(self.project_dir),
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout,
+                )
+
+            if summarize_output:
+                self._print_output_summary(result)
+
+            return result
+
+        except subprocess.TimeoutExpired as e:
+            message = (
+                f"{error_prefix}: command timed out after {timeout}s "
+                f"({' '.join(command)}). "
+                f"Set {settings.SUBPROCESS_TIMEOUT_ENV_VAR} to raise the limit."
+            )
+            debug_log(message, "error")
+            handle_exception(e, message)
+            raise BackendExceptions(message)
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr if isinstance(e.stderr, str) else ""
+            debug_log(f"{error_prefix}: {stderr or e}", "error")
+            handle_exception(e, f"{error_prefix}: {str(e)}")
+            if stderr:
+                print_error(f"Error details: {stderr}")
+            # Carry the tail of stderr into the exception message: the raised
+            # BackendExceptions is what callers (and the CLI) surface, and a
+            # bare prefix leaves "why did it fail?" unanswerable from a log.
+            raise BackendExceptions(_with_stderr_tail(error_prefix, stderr))
+        except OSError as e:
+            debug_log(f"{error_prefix}: {e}", "error")
+            handle_exception(e, f"{error_prefix}: {str(e)}")
+            raise BackendExceptions(f"{error_prefix}: {str(e)}")
+
+    @staticmethod
+    def _print_output_summary(
+        result: subprocess.CompletedProcess[str], max_lines: int = 5
+    ) -> None:
+        """
+        Print the tail of a completed command's output.
+
+        Keeps the user informed about long running installs without dumping the
+        whole log. Silently does nothing when there is no textual output.
+
+        :param result: Completed process whose output should be summarized
+        :param max_lines: Maximum number of trailing lines to print
+        """
+        chunks = [
+            chunk
+            for chunk in (
+                getattr(result, "stdout", None),
+                getattr(result, "stderr", None),
+            )
+            if isinstance(chunk, str)
+        ]
+        lines = [line.strip() for chunk in chunks for line in chunk.splitlines()]
+        lines = [line for line in lines if line]
+        if not lines:
+            return
+
+        for line in lines[-max_lines:]:
+            console.print(f"[dim]  {line}[/dim]")
+
+    def _ensure_venv(self, venv_path: str) -> str:
+        """
+        Make sure a virtual environment exists, creating it when missing.
+
+        :param venv_path: Path to the virtual environment
+        :return: Path to an existing virtual environment
+        :raises BackendExceptions: if the virtual environment cannot be created
+        """
+        if os.path.exists(venv_path):
+            return venv_path
+
+        debug_log("Virtual environment does not exist. Creating it first.", "warning")
+        print_error("Virtual environment does not exist. Creating it first.")
+        created = self.create_virtual_environment()
+        if not created:
+            raise BackendExceptions("Failed to create venv")
+        return created
+
+    def _require_dependency_file(self, error_message: Optional[str] = None) -> Path:
+        """
+        Return the dependency file path, failing when it is missing.
+
+        :param error_message: Message used for the raised exception
+        :return: Path to the dependency file
+        :raises BackendExceptions: if the dependency file does not exist
+        """
+        dependency_path = self.get_dependency_file_path()
+        if not dependency_path.exists():
+            file_name = self.get_dependency_file_name()
+            debug_log(f"{file_name} file not found at {dependency_path}", "error")
+            print_error(f"{file_name} file not found at {dependency_path}")
+            raise BackendExceptions(error_message or f"{file_name} file not found")
+        return dependency_path
+
     def get_dependency_file_path(self) -> Path:
         """
         Get the full path to the dependency file.

fastapi_fastkit/backend/package_managers/factory.py

@@ -20,6 +20,10 @@ logger = get_logger(__name__)
 class PackageManagerFactory:
     """Factory for creating package manager instances."""
 
+    # Auto-detection priority. ``uv`` wins whenever it is installed and ``pip``
+    # is only the last-resort fallback; explicit selection bypasses this order.
+    DETECTION_ORDER: List[str] = ["uv", "pdm", "poetry", "pip"]
+
     # Registry of available package managers
     _managers: Dict[str, Type[BasePackageManager]] = {
         "pip": PipManager,
@@ -86,10 +90,7 @@ class PackageManagerFactory:
         """
         exclude = exclude or []
 
-        # Priority order for auto-detection
-        detection_order = ["uv", "pdm", "poetry", "pip"]
-
-        for manager_type in detection_order:
+        for manager_type in self.DETECTION_ORDER:
             if manager_type in exclude:
                 continue
 

fastapi_fastkit/backend/package_managers/pdm_manager.py

@@ -3,19 +3,14 @@
 #
 # @author bnbong bbbong9@gmail.com
 # --------------------------------------------------------------------------
-import os
 import subprocess
 import sys
 from typing import List
 
 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 (
-    console,
-    handle_exception,
-    print_error,
-    print_success,
-)
+from fastapi_fastkit.utils.main import print_success
 
 from .base import BasePackageManager
 
@@ -27,16 +22,7 @@ class PdmManager(BasePackageManager):
 
     def is_available(self) -> bool:
         """Check if PDM is available on the system."""
-        try:
-            subprocess.run(
-                ["pdm", "--version"],
-                check=True,
-                capture_output=True,
-                text=True,
-            )
-            return True
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            return False
+        return self._check_command_available(["pdm", "--version"])
 
     def get_dependency_file_name(self) -> str:
         """Get the dependency file name for PDM."""
@@ -51,29 +37,16 @@ class PdmManager(BasePackageManager):
         """
         venv_path = str(self.project_dir / ".venv")
 
-        try:
-            with console.status("[bold green]Creating virtual environment with PDM..."):
-                # PDM can create virtual environment in specific location
-                subprocess.run(
-                    ["pdm", "venv", "create", "--name", ".venv", sys.executable],
-                    cwd=str(self.project_dir),
-                    check=True,
-                    capture_output=True,
-                    text=True,
-                )
-
-            debug_log(f"Virtual environment created at {venv_path}", "info")
-            print_success("Virtual environment created successfully with PDM")
-            return venv_path
-
-        except subprocess.CalledProcessError as e:
-            debug_log(f"Error creating virtual environment: {e.stderr}", "error")
-            handle_exception(e, f"Error creating virtual environment: {str(e)}")
-            raise BackendExceptions("Failed to create venv with PDM")
-        except OSError as e:
-            debug_log(f"System error creating virtual environment: {e}", "error")
-            handle_exception(e, f"Error creating virtual environment: {str(e)}")
-            raise BackendExceptions(f"Failed to create venv with PDM: {str(e)}")
+        self._run_checked(
+            ["pdm", "venv", "create", "--name", ".venv", sys.executable],
+            status_msg="Creating virtual environment with PDM...",
+            error_prefix="Failed to create venv with PDM",
+            timeout=settings.get_subprocess_timeout("venv"),
+        )
+
+        debug_log(f"Virtual environment created at {venv_path}", "info")
+        print_success("Virtual environment created successfully with PDM")
+        return venv_path
 
     def install_dependencies(self, venv_path: str) -> None:
         """
@@ -82,47 +55,19 @@ class PdmManager(BasePackageManager):
         :param venv_path: Path to the virtual environment
         :raises: BackendExceptions if dependency installation fails
         """
-        try:
-            if not os.path.exists(venv_path):
-                debug_log(
-                    "Virtual environment does not exist. Creating it first.", "warning"
-                )
-                print_error("Virtual environment does not exist. Creating it first.")
-                venv_path = self.create_virtual_environment()
-                if not venv_path:
-                    raise BackendExceptions("Failed to create venv")
+        venv_path = self._ensure_venv(venv_path)
+        self._require_dependency_file()
 
-            pyproject_path = self.get_dependency_file_path()
-            if not pyproject_path.exists():
-                debug_log(f"pyproject.toml file not found at {pyproject_path}", "error")
-                print_error(f"pyproject.toml file not found at {pyproject_path}")
-                raise BackendExceptions("pyproject.toml file not found")
-
-            # Install dependencies using PDM
-            with console.status("[bold green]Installing dependencies with PDM..."):
-                subprocess.run(
-                    ["pdm", "install"],
-                    cwd=str(self.project_dir),
-                    check=True,
-                    capture_output=True,
-                    text=True,
-                )
-
-            debug_log("Dependencies installed successfully with PDM", "info")
-            print_success("Dependencies installed successfully with PDM")
-
-        except subprocess.CalledProcessError as e:
-            debug_log(f"Error during dependency installation: {e.stderr}", "error")
-            handle_exception(e, f"Error during dependency installation: {str(e)}")
-            if hasattr(e, "stderr"):
-                print_error(f"Error details: {e.stderr}")
-            raise BackendExceptions("Failed to install dependencies with PDM")
-        except OSError as e:
-            debug_log(f"System error during dependency installation: {e}", "error")
-            handle_exception(e, f"Error during dependency installation: {str(e)}")
-            raise BackendExceptions(
-                f"Failed to install dependencies with PDM: {str(e)}"
-            )
+        self._run_checked(
+            ["pdm", "install"],
+            status_msg="Installing dependencies with PDM...",
+            error_prefix="Failed to install dependencies with PDM",
+            timeout=settings.get_subprocess_timeout("install"),
+            summarize_output=True,
+        )
+
+        debug_log("Dependencies installed successfully with PDM", "info")
+        print_success("Dependencies installed successfully with PDM")
 
     def generate_dependency_file(
         self,
@@ -205,6 +150,7 @@ packages = ["src"]
                 check=True,
                 capture_output=True,
                 text=True,
+                timeout=settings.get_subprocess_timeout("install"),
             )
 
             debug_log(
@@ -212,7 +158,7 @@ packages = ["src"]
                 "info",
             )
 
-        except subprocess.CalledProcessError as e:
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
             debug_log(f"Error adding dependency with PDM: {e}", "error")
             raise BackendExceptions(f"Failed to add dependency with PDM: {str(e)}")
         except OSError as e:
@@ -238,6 +184,7 @@ packages = ["src"]
                 check=True,
                 capture_output=True,
                 text=True,
+                timeout=settings.get_subprocess_timeout(),
             )
 
             # Create or update pyproject.toml with provided metadata
@@ -271,7 +218,7 @@ packages = ["src"]
 
             debug_log(f"Initialized PDM project: {project_name}", "info")
 
-        except subprocess.CalledProcessError as e:
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
             debug_log(f"Error initializing PDM project: {e}", "error")
             raise BackendExceptions(f"Failed to initialize PDM project: {str(e)}")
         except (OSError, UnicodeEncodeError) as e:

fastapi_fastkit/backend/package_managers/pip_manager.py

@@ -3,19 +3,13 @@
 #
 # @author bnbong bbbong9@gmail.com
 # --------------------------------------------------------------------------
-import os
-import subprocess
 import sys
 from typing import List
 
 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 (
-    console,
-    handle_exception,
-    print_error,
-    print_success,
-)
+from fastapi_fastkit.utils.main import print_success
 
 from .base import BasePackageManager
 
@@ -27,16 +21,7 @@ class PipManager(BasePackageManager):
 
     def is_available(self) -> bool:
         """Check if pip is available on the system."""
-        try:
-            subprocess.run(
-                [sys.executable, "-m", "pip", "--version"],
-                check=True,
-                capture_output=True,
-                text=True,
-            )
-            return True
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            return False
+        return self._check_command_available([sys.executable, "-m", "pip", "--version"])
 
     def get_dependency_file_name(self) -> str:
         """Get the dependency file name for pip."""
@@ -51,87 +36,48 @@ class PipManager(BasePackageManager):
         """
         venv_path = str(self.project_dir / ".venv")
 
-        try:
-            with console.status("[bold green]Creating virtual environment..."):
-                subprocess.run(
-                    [sys.executable, "-m", "venv", venv_path],
-                    check=True,
-                    capture_output=True,
-                    text=True,
-                )
-
-            debug_log(f"Virtual environment created at {venv_path}", "info")
-            print_success("Virtual environment created successfully")
-            return venv_path
+        self._run_checked(
+            [sys.executable, "-m", "venv", venv_path],
+            status_msg="Creating virtual environment...",
+            error_prefix="Failed to create venv",
+            timeout=settings.get_subprocess_timeout("venv"),
+        )
 
-        except subprocess.CalledProcessError as e:
-            debug_log(f"Error creating virtual environment: {e.stderr}", "error")
-            handle_exception(e, f"Error creating virtual environment: {str(e)}")
-            raise BackendExceptions("Failed to create venv")
-        except OSError as e:
-            debug_log(f"System error creating virtual environment: {e}", "error")
-            handle_exception(e, f"Error creating virtual environment: {str(e)}")
-            raise BackendExceptions(f"Failed to create venv: {str(e)}")
+        debug_log(f"Virtual environment created at {venv_path}", "info")
+        print_success("Virtual environment created successfully")
+        return venv_path
 
-    def install_dependencies(self, venv_path: str) -> None:
+    def install_dependencies(self, venv_path: str, upgrade_pip: bool = False) -> None:
         """
         Install dependencies using pip in the virtual environment.
 
         :param venv_path: Path to the virtual environment
+        :param upgrade_pip: Upgrade pip inside the venv before installing
         :raises: BackendExceptions if dependency installation fails
         """
-        try:
-            if not os.path.exists(venv_path):
-                debug_log(
-                    "Virtual environment does not exist. Creating it first.", "warning"
-                )
-                print_error("Virtual environment does not exist. Creating it first.")
-                venv_path = self.create_virtual_environment()
-                if not venv_path:
-                    raise BackendExceptions("Failed to create venv")
-
-            requirements_path = self.get_dependency_file_path()
-            if not requirements_path.exists():
-                debug_log(
-                    f"Requirements file not found at {requirements_path}", "error"
-                )
-                print_error(f"Requirements file not found at {requirements_path}")
-                raise BackendExceptions("Requirements file not found")
+        venv_path = self._ensure_venv(venv_path)
+        requirements_path = self._require_dependency_file("Requirements file not found")
 
-            # Get pip path
-            pip_path = self.get_executable_path("pip", venv_path)
+        pip_path = self.get_executable_path("pip", venv_path)
 
-            # Upgrade pip first
-            subprocess.run(
+        if upgrade_pip:
+            self._run_checked(
                 [pip_path, "install", "--upgrade", "pip"],
-                check=True,
-                capture_output=True,
-                text=True,
+                status_msg="Upgrading pip...",
+                error_prefix="Failed to upgrade pip",
+                timeout=settings.get_subprocess_timeout("install"),
             )
 
-            # Install dependencies
-            with console.status("[bold green]Installing dependencies..."):
-                subprocess.run(
-                    [pip_path, "install", "-r", str(requirements_path.name)],
-                    cwd=str(self.project_dir),
-                    check=True,
-                    capture_output=True,
-                    text=True,
-                )
+        self._run_checked(
+            [pip_path, "install", "-r", str(requirements_path.name)],
+            status_msg="Installing dependencies...",
+            error_prefix="Failed to install dependencies",
+            timeout=settings.get_subprocess_timeout("install"),
+            summarize_output=True,
+        )
 
-            debug_log("Dependencies installed successfully", "info")
-            print_success("Dependencies installed successfully")
-
-        except subprocess.CalledProcessError as e:
-            debug_log(f"Error during dependency installation: {e.stderr}", "error")
-            handle_exception(e, f"Error during dependency installation: {str(e)}")
-            if hasattr(e, "stderr"):
-                print_error(f"Error details: {e.stderr}")
-            raise BackendExceptions("Failed to install dependencies")
-        except OSError as e:
-            debug_log(f"System error during dependency installation: {e}", "error")
-            handle_exception(e, f"Error during dependency installation: {str(e)}")
-            raise BackendExceptions(f"Failed to install dependencies: {str(e)}")
+        debug_log("Dependencies installed successfully", "info")
+        print_success("Dependencies installed successfully")
 
     def generate_dependency_file(
         self,