instant-python 0.3.0__tar.gz → 0.5.0__tar.gz

{instant_python-0.3.0 → instant_python-0.5.0}/.github/workflows/release.yml

@@ -4,11 +4,11 @@ on:
   workflow_dispatch:
 
 jobs:
-  bump-version:
+  bump_version:
     if: "!startsWith(github.event.head_commit.message, 'bump:')"
     runs-on: ubuntu-latest
     outputs:
-      tag: ${{ steps.bump.outputs.new_tag }}
+      tag: ${{ steps.bump.outputs.version }}
     steps:
       - name: Check out
         uses: actions/checkout@v3
@@ -17,12 +17,13 @@ jobs:
           fetch-depth: 0
 
       - name: Bump version and update changelog
+        id: bump
         uses: commitizen-tools/commitizen-action@master
         with:
           github_token: ${{ secrets.CHANGELOG_TOKEN }}
 
-  create-release:
-    needs: bump-version
+  create_release:
+    needs: bump_version
     runs-on: ubuntu-latest
     steps:
       - name: Check out
@@ -46,7 +47,7 @@ jobs:
       - name: Extract Changelog for Release
         id: extract_changelog
         run: |
-          release="${{ steps.determine_tag.outputs.release_tag }}"
+          release="${{ steps.release_tag.outputs.release_tag }}"
           echo "Extracting changelog for tag: ${release}"
           
           awk -v tag="$release" '

{instant_python-0.3.0 → instant_python-0.5.0}/CHANGELOG.md

@@ -1,3 +1,39 @@
+## 0.5.0 (2025-04-15)
+
+### ✨ Features
+
+- **cli**: create main application based on custom implementation and add error handlers
+- **cli**: implement a custom version of Typer application to be able to handle exceptions in FastAPI way using decorators
+- **errors**: add UnknownTemplateError for handling unknown template types
+- **errors**: add TemplateFileNotFoundError for missing template files and extend ErrorTypes with GENERATOR
+- **errors**: add ErrorTypes enum for categorizing error types
+- **errors**: add CommandExecutionError for handling command execution failures
+- **errors**: add UnknownDependencyManagerError for handling unknown dependency managers
+- **installer**: remove unused PYENV manager from Enum
+- **errors**: create application error to be able to capture all expected errors
+
+### 🐛 Bug Fixes
+
+- **errors**: correct typo in UnknownTemplateError message
+
+### ♻️ Code Refactoring
+
+- **project-generator**: manage when a command fails by raising custom CommandExecutionError
+- **installer**: manage when a command fails by raising custom CommandExecutionError
+- **cli**: enhance error handling with rich console output
+- **project-generator**: raise UnknownTemplateError for unknown template types
+- **project-generator**: move UnknownErrorTypeError to errors module and inherit from ApplicationError
+- **project-generator**: raise TemplateFileNotFoundError for missing template files
+- **errors**: use ErrorTypes enum for error type in CommandExecutionError and UnknownDependencyManagerError
+- **installer**: add stderr handling for subprocess calls
+- **installer**: raise UnknownDependencyManagerError for unknown user managers
+
+## 0.4.0 (2025-04-11)
+
+### ✨ Features
+
+- **template**: add README template and include in main structure
+
 ## 0.3.0 (2025-04-11)
 
 ### ✨ Features

{instant_python-0.3.0 → instant_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instant-python
-Version: 0.3.0
+Version: 0.5.0
 Summary: Instant boilerplate generation for Python projects
 Project-URL: documentation, https://dimanu-py.github.io/instant-python/
 Project-URL: repository, https://github.com/dimanu-py/instant-python/

{instant_python-0.3.0 → instant_python-0.5.0}/docs/getting-started/installation.md

@@ -1,7 +1,7 @@
 # Installation
 
 !!! important
-For the moment, `instant-python` is only supported in Unix-like systems. Windows support is coming soon.
+    For the moment, `instant-python` is only supported in Unix-like systems. Windows support is coming soon.
 
 To ensure a clean and isolated environment, we recommend installing `instant-python` using a virtual environment. At your 
 own risk, you can install it at you system Python installation, but this is not recommended.

{instant_python-0.3.0 → instant_python-0.5.0}/docs/guide/custom-templates.md

@@ -21,43 +21,60 @@ offers a Domain Driven Design, Clean Architecture and Standard templates.
 
 ## Examples
 
-???+ example 
-
-Let's imagine that you want to create a new project using a custom template with Hexagonal Architecture. 
+Let's imagine that you want to create a new project using a custom template with Cockburn-style Hexagonal Architecture,
+including a gitignore, README and mypy configuration files. 
 You can create a yaml file with the following content:
 
 ```yaml
 root:
   - name: src
     type: directory
-    python: true
-    children:
-      - name: domain
-        type: directory
-        python: true
-      - name: application
-        type: directory
-        python: true
-      - name: ports
-        type: directory
-        python: true
-      - name: adapters
-        type: directory
-        python: true
-  - name: test
-    type: directory
-    python: true
+    python: True
     children:
-      - name: domain
-        type: directory
-        python: true
-      - name: application
+      - name: driven_adapters
         type: directory
-        python: true
-      - name: ports
+        python: True
+        children:
+          - name: adapter_for_paying_spy
+            type: file
+            extension: .py
+          - name: adapter_for_obtaining_grates_stup
+            type: file
+            extension: .py
+      - name: driving_adapters
         type: directory
-        python: true
-      - name: adapters
+        python: True
+        children:
+          - name: adapter_for_checking_cars_test
+            type: file
+            extension: .py
+      - name: tax_calculator_app
         type: directory
-        python: true
+        python: True
+        children:
+          - name: driven_ports
+            type: directory
+            python: True
+            children:
+              - name: for_paying
+                type: file
+                extension: .py
+          - name: driving_ports
+            type: directory
+            python: True
+            children:
+              - name: for_checking_cars
+                type: file
+                extension: .py
+          - name: tax_calculator
+            type: directory
+            python: True
+  - name: .gitignore
+    type: file
+  - name: README
+    type: file
+    extension: .md
+  - name: mypy
+    type: file
+    extension: .ini
 ```

instant_python-0.3.0/docs/welcome.md → instant_python-0.5.0/docs/index.md

@@ -22,7 +22,6 @@ pip install instant-python
 
 ## Documentation Structure
 
-- [Welcome](./welcome.md)
 - [Getting Started](./getting-started/index.md)
     - [Installation](./getting-started/installation.md)
     - [First Steps](./getting-started/first-steps.md)

instant_python-0.5.0/instant_python/cli.py

@@ -0,0 +1,28 @@
+from rich.console import Console
+from rich.panel import Panel
+
+from instant_python import folder_cli, project_cli
+from instant_python.errors.application_error import ApplicationError
+from instant_python.intant_python_typer import InstantPythonTyper
+
+app = InstantPythonTyper()
+console = Console()
+
+app.add_typer(folder_cli.app, name="folder", help="Generate only the folder structure for a new project")
+app.add_typer(project_cli.app, name="project", help="Generate a full project ready to be used")
+
+
+@app.error_handler(ApplicationError)
+def handle_application_error(exc: ApplicationError) -> None:
+    error_panel = Panel(exc.message, title="Error", border_style="red")
+    console.print(error_panel)
+
+
+@app.error_handler(Exception)
+def handle_unexpected_error(exc: Exception) -> None:
+    error_panel = Panel(f"An unexpected error occurred: {exc}", title="Error", border_style="red")
+    console.print(error_panel)
+
+
+if __name__ == "__main__":
+    app()

instant_python-0.5.0/instant_python/errors/application_error.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+
+class ApplicationError(Exception, ABC):
+    @property
+    @abstractmethod
+    def type(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def message(self) -> str: ...

instant_python-0.5.0/instant_python/errors/command_execution_error.py

@@ -0,0 +1,20 @@
+from instant_python.errors.application_error import ApplicationError
+from instant_python.errors.error_types import ErrorTypes
+
+
+class CommandExecutionError(ApplicationError):
+    def __init__(self, exit_code: int, stderr_output=None):
+        self._message = (
+            f"Unexpected error when executing a command, exit code {exit_code}"
+        )
+        if stderr_output:
+            self._message += f": {stderr_output.decode('utf-8').strip()}"
+        super().__init__(self._message)
+
+    @property
+    def type(self) -> str:
+        return ErrorTypes.INSTALLER.value
+
+    @property
+    def message(self) -> str:
+        return self._message

instant_python-0.5.0/instant_python/errors/error_types.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class ErrorTypes(str, Enum):
+	INSTALLER = "installer_error"
+	GENERATOR = "project_generator_error"

instant_python-0.5.0/instant_python/errors/template_file_not_found_error.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from instant_python.errors.application_error import ApplicationError
+from instant_python.errors.error_types import ErrorTypes
+
+
+class TemplateFileNotFoundError(ApplicationError):
+    def __init__(self, template_path: str | Path) -> None:
+        self._message = f"Could not find YAML file at: {template_path}"
+        super().__init__(self._message)
+
+    @property
+    def type(self) -> str:
+        return ErrorTypes.GENERATOR.value
+
+    @property
+    def message(self) -> str:
+        return self._message

instant_python-0.5.0/instant_python/errors/unknown_dependency_manager_error.py

@@ -0,0 +1,18 @@
+from instant_python.errors.application_error import ApplicationError
+from instant_python.errors.error_types import ErrorTypes
+
+
+class UnknownDependencyManagerError(ApplicationError):
+    def __init__(self, manager: str) -> None:
+        self._message = (
+            f"Unknown dependency manager: {manager}. Please use 'pdm' or 'uv'."
+        )
+        super().__init__(self._message)
+
+    @property
+    def type(self) -> str:
+        return ErrorTypes.INSTALLER.value
+
+    @property
+    def message(self) -> str:
+        return self._message

instant_python-0.5.0/instant_python/errors/unknown_node_typer_error.py

@@ -0,0 +1,16 @@
+from instant_python.errors.application_error import ApplicationError
+from instant_python.errors.error_types import ErrorTypes
+
+
+class UnknownNodeTypeError(ApplicationError):
+    def __init__(self, node_type: str) -> None:
+        self._message = f"Unknown node type: {node_type}"
+        super().__init__(self._message)
+
+    @property
+    def type(self) -> str:
+        return ErrorTypes.GENERATOR.value
+
+    @property
+    def message(self) -> str:
+        return self._message

instant_python-0.5.0/instant_python/errors/unknown_template_error.py

@@ -0,0 +1,16 @@
+from instant_python.errors.application_error import ApplicationError
+from instant_python.errors.error_types import ErrorTypes
+
+
+class UnknownTemplateError(ApplicationError):
+    def __init__(self, template_name: str) -> None:
+        self._message = f"Unknown template type: {template_name}"
+        super().__init__(self._message)
+
+    @property
+    def type(self) -> str:
+        return ErrorTypes.GENERATOR.value
+
+    @property
+    def message(self) -> str:
+        return self._message

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/installer/dependency_manager_factory.py

@@ -1,3 +1,4 @@
+from instant_python.errors.unknown_dependency_manager_error import UnknownDependencyManagerError
 from instant_python.installer.dependency_manager import DependencyManager
 from instant_python.installer.managers import Managers
 from instant_python.installer.pdm_manager import PdmManager
@@ -11,4 +12,7 @@ class DependencyManagerFactory:
             Managers.UV: UvManager,
             Managers.PDM: PdmManager,
         }
-        return managers[Managers(user_manager)](project_path)
+        try:
+            return managers[Managers(user_manager)](project_path)
+        except KeyError:
+            raise UnknownDependencyManagerError(user_manager)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/installer/git_configurer.py

@@ -21,6 +21,7 @@ class GitConfigurer:
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(">>> Git repository initialized successfully")
 
@@ -32,6 +33,7 @@ class GitConfigurer:
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(">>> Git user and email configured successfully")
 
@@ -43,5 +45,6 @@ class GitConfigurer:
 	        check=True,
 	        cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(">>> Initial commit made successfully")

instant_python-0.5.0/instant_python/installer/installer.py

@@ -0,0 +1,24 @@
+import subprocess
+
+from instant_python.errors.command_execution_error import CommandExecutionError
+from instant_python.installer.dependency_manager import DependencyManager
+
+
+class Installer:
+    _dependency_manager: DependencyManager
+
+    def __init__(
+        self,
+        dependency_manager: DependencyManager,
+    ) -> None:
+        self._dependency_manager = dependency_manager
+
+    def perform_installation(
+        self, python_version: str, dependencies: list[str]
+    ) -> None:
+        try:
+            self._dependency_manager.install()
+            self._dependency_manager.install_python(python_version)
+            self._dependency_manager.install_dependencies(dependencies)
+        except subprocess.CalledProcessError as error:
+            raise CommandExecutionError(exit_code=error.returncode, stderr_output=error.stderr)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/installer/managers.py

@@ -2,6 +2,5 @@ from enum import Enum
 
 
 class Managers(str, Enum):
-    PYENV = "pyenv"
     UV = "uv"
     PDM = "pdm"

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/installer/pdm_manager.py

@@ -16,6 +16,8 @@ class PdmManager(DependencyManager):
             "curl -sSL https://pdm-project.org/install-pdm.py | python3 -",
             shell=True,
             check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(">>> pdm installed successfully")
 
@@ -27,6 +29,8 @@ class PdmManager(DependencyManager):
             shell=True,
             check=True,
             cwd=self._project_directory,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(f">>> Python {version} installed successfully")
 
@@ -55,6 +59,8 @@ class PdmManager(DependencyManager):
             shell=True,
             check=True,
             cwd=self._project_directory,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
 
     @staticmethod
@@ -76,4 +82,5 @@ class PdmManager(DependencyManager):
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/installer/uv_manager.py

@@ -17,6 +17,7 @@ class UvManager(DependencyManager):
             shell=True,
             check=True,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(">>> uv installed successfully")
 
@@ -29,6 +30,7 @@ class UvManager(DependencyManager):
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(f">>> Python {version} installed successfully")
 
@@ -58,6 +60,7 @@ class UvManager(DependencyManager):
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )
         print(f">>> {dependency_name} installed successfully")
 
@@ -81,4 +84,5 @@ class UvManager(DependencyManager):
             check=True,
             cwd=self._project_directory,
             stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
         )

instant_python-0.5.0/instant_python/intant_python_typer.py

@@ -0,0 +1,30 @@
+from collections.abc import Callable
+
+import typer
+
+ExceptionType = type[Exception]
+ErrorHandlingCallback = Callable[[Exception], None]
+
+
+class InstantPythonTyper(typer.Typer):
+    error_handlers: dict[ExceptionType, ErrorHandlingCallback] = {}
+
+    def error_handler(self, exc: ExceptionType):
+        """Registers a callback function to be called when 'exc' (the given exception) is raised."""
+
+        def decorator(func: ErrorHandlingCallback):
+            self.error_handlers[exc] = func
+            return func
+
+        return decorator
+
+    def __call__(self, *args, **kwargs):
+        """Overrides Typer.__call__ so that when we run the CLI,
+        we can catch any exception that's raised and see if there's
+        a matching error handler for it.
+        """
+        try:
+            super().__call__(*args, **kwargs)
+        except Exception as error:
+            callback = self.error_handlers.get(error.__class__.__base__)
+            callback(error)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/project_generator/custom_template_manager.py

@@ -2,6 +2,7 @@ from pathlib import Path
 
 import yaml
 
+from instant_python.errors.template_file_not_found_error import TemplateFileNotFoundError
 from instant_python.project_generator.template_manager import TemplateManager
 
 
@@ -11,8 +12,6 @@ class CustomTemplateManager(TemplateManager):
 
     def get_project(self, template_name: str) -> dict[str, str]:
         if not self._template_path.is_file():
-            raise FileNotFoundError(
-                f"Could not find YAML file at: {self._template_path}"
-            )
+            raise TemplateFileNotFoundError(self._template_path)
         with open(self._template_path, "r", encoding="utf-8") as f:
             return yaml.safe_load(f)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/project_generator/folder_tree.py

@@ -1,17 +1,12 @@
 from pathlib import Path
 
-from instant_python.project_generator.directory import Directory
+from instant_python.errors.unknown_node_typer_error import UnknownNodeTypeError
 from instant_python.project_generator.boilerplate_file import BoilerplateFile
+from instant_python.project_generator.directory import Directory
 from instant_python.project_generator.file import File
 from instant_python.project_generator.node import Node, NodeType
 
 
-class UnknownNodeType(ValueError):
-    def __init__(self, node_type: str) -> None:
-        self._message = f"Unknown node type: {node_type}"
-        super().__init__(self._message)
-
-
 class FolderTree:
     def __init__(self, project_directory: str) -> None:
         self._project_directory = Path(project_directory)
@@ -41,4 +36,4 @@ class FolderTree:
             extension = node.get("extension", "")
             return File(name=name, extension=extension)
         else:
-            raise UnknownNodeType(node_type)
+            raise UnknownNodeTypeError(node_type)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/project_generator/jinja_custom_filters.py

@@ -1,3 +1,4 @@
+from instant_python.errors.unknown_template_error import UnknownTemplateError
 from instant_python.question_prompter.template_types import TemplateTypes
 
 
@@ -15,4 +16,4 @@ def compute_base_path(initial_path: str, template_type: str) -> str:
     elif template_type == TemplateTypes.STANDARD:
         return ".".join(path_components[2:])
     else:
-        raise ValueError(f"Unknown template type: {template_type}")
+        raise UnknownTemplateError(template_type)

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/project_generator/project_generator.py

@@ -1,5 +1,6 @@
 import subprocess
 
+from instant_python.errors.command_execution_error import CommandExecutionError
 from instant_python.project_generator.folder_tree import FolderTree
 from instant_python.project_generator.jinja_template_manager import TemplateManager
 
@@ -18,13 +19,17 @@ class ProjectGenerator:
         self._format_project_files()
 
     def _format_project_files(self) -> None:
-        subprocess.run(
-            "uvx ruff format",
-            shell=True,
-            check=True,
-            cwd=self._folder_tree.project_directory,
-            stdout=subprocess.DEVNULL,
-        )
+        try:
+            subprocess.run(
+                "uvx ruff format",
+                shell=True,
+                check=True,
+                cwd=self._folder_tree.project_directory,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+            )
+        except subprocess.CalledProcessError as error:
+            raise CommandExecutionError(exit_code=error.returncode, stderr_output=error.stderr)
 
     @property
     def path(self) -> str:

instant_python-0.5.0/instant_python/templates/boilerplate/README.md

@@ -0,0 +1,5 @@
+# {{ project-slug }}
+
+## Description
+
+{{ description }}

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/templates/project_structure/clean_architecture/main_structure.yml.j2

@@ -11,6 +11,7 @@ root:
   {{ macros.include_and_indent("project_structure/pyproject.yml.j2", 2) }}
   {% if git %}
   {{ macros.include_and_indent("project_structure/gitignore.yml.j2", 2) }}
+  {{ macros.include_and_indent("project_structure/readme.yml.j2", 2) }}
   {% endif %}
   {{ macros.include_and_indent("project_structure/python_version.yml.j2", 2) }}
   {% if "pytest" in dependencies %}

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/templates/project_structure/domain_driven_design/main_structure.yml.j2

@@ -11,6 +11,7 @@ root:
   {{ macros.include_and_indent("project_structure/pyproject.yml.j2", 2) }}
   {% if git %}
   {{ macros.include_and_indent("project_structure/gitignore.yml.j2", 2) }}
+  {{ macros.include_and_indent("project_structure/readme.yml.j2", 2) }}
   {% endif %}
   {{ macros.include_and_indent("project_structure/python_version.yml.j2", 2) }}
   {% if "pytest" in dependencies %}

instant_python-0.5.0/instant_python/templates/project_structure/readme.yml.j2

@@ -0,0 +1,3 @@
+- name: README
+  type: boilerplate_file
+  extension: .md

{instant_python-0.3.0 → instant_python-0.5.0}/instant_python/templates/project_structure/standard_project/main_structure.yml.j2

@@ -11,6 +11,7 @@ root:
   {{ macros.include_and_indent("project_structure/pyproject.yml.j2", 2) }}
   {% if git %}
   {{ macros.include_and_indent("project_structure/gitignore.yml.j2", 2) }}
+  {{ macros.include_and_indent("project_structure/readme.yml.j2", 2) }}
   {%  endif %}
   {{ macros.include_and_indent("project_structure/python_version.yml.j2", 2) }}
   {% if "pytest" in dependencies %}

{instant_python-0.3.0 → instant_python-0.5.0}/mkdocs.yml

@@ -55,8 +55,7 @@ theme:
       primary: '#B4BEFE'
       accent: '#FAB387'
 nav:
-  - Home:
-      - welcome.md
+  - index.md
   - Getting Started:
       - getting-started/index.md
       - Installation: getting-started/installation.md

{instant_python-0.3.0 → instant_python-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "instant-python"
-version = "0.3.0"
+version = "0.5.0"
 description = "Instant boilerplate generation for Python projects"
 readme = "README.md"
 license = { file = "LICENSE" }