instant-python 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

instant_python/shared/supported_built_in_features.py

@@ -4,12 +4,16 @@ from enum import Enum
 class SupportedBuiltInFeatures(str, Enum):
     VALUE_OBJECTS = "value_objects"
     GITHUB_ACTIONS = "github_actions"
+    GITHUB_ISSUES_TEMPLATE = "github_issues_template"
     MAKEFILE = "makefile"
     LOGGER = "logger"
     EVENT_BUS = "event_bus"
     ASYNC_SQLALCHEMY = "async_sqlalchemy"
     ASYNC_ALEMBIC = "async_alembic"
     FASTAPI = "fastapi_application"
+    PRECOMMIT = "precommit_hook"
+    CITATION = "citation_file"
+    SECURITY = "security_file"
 
     @classmethod
     def get_supported_built_in_features(cls) -> list[str]:

instant_python/templates/boilerplate/.pre-commit-config.yml

@@ -1,33 +1,71 @@
+fail_fast: true
+
+default_language_version:
+  python: {{ general.python_version }}
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b # v5.0.0
     hooks:
       - id: check-added-large-files
-      - id: check-ast
+        name: 📦 Large Files Checker
+        args:
+          - --maxkb=100
+        stages:
+          - pre-commit
+
       - id: check-case-conflict
+        name: 🔠 Case Conflict Checker
+        stages:
+          - pre-commit
+
+      - id: check-toml
+        name: 📄 TOML Files Checker
+        files: '.*\.toml'
+        stages:
+          - pre-commit
+
+      - id: check-yaml
+        name: 📄 YAML Files Checker
+        files: '.*\.ya?ml'
+        args:
+          - --unsafe
+        stages:
+          - pre-commit
       - id: check-merge-conflict
+        name: 🔀 Merge Conflict Checker
+        stages:
+          - pre-commit
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: 782f3104786efdce0f809bce8a9ff31f2fa1c9ed # v8.27.0
+    hooks:
+      - id: gitleaks
+        name: 🔍 Secrets Checker
+        entry: gitleaks detect --no-git --redact --verbose
+        stages:
+          - pre-commit
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: a0cc4901b0faaced74c713a9e355555fc4de0880 # v4.7.1
+    hooks:
+      - id: commitizen
+        name: 📝 Conventional Commit Message Checker
+        stages:
+          - commit-msg
 
   - repo: local
     hooks:
-      - id: type-check
-        name: check typing
-        entry: make check-typing
-        language: system
       - id: lint
-        name: check for lint
-        entry: make lint
+        name: 🧹 Code Linter
+        entry: make check-lint
         language: system
+        stages:
+          - pre-push
+
       - id: format
-        name: check for code format
-        entry: make format
-        language: system
-      - id: unit-test
-        name: run all unit test
-        entry: make all-unit
-        language: system
-      - id: pre-push
-        name: run integration and acceptance test
-        entry: make pre-push
+        name: 🎨 Code Formatter
+        entry: make check-format
         language: system
         stages:
           - pre-push

instant_python/templates/boilerplate/CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+title: {{ general.slug }}
+message: If you use this software, please cite it using the metadata below.
+type: software
+authors:
+  - given-names: {{ general.author }}
+repository-code: https://github.com/{{ git.username }}/{{ general.slug }}/
+url: https://pypi.org/project/{{ general.slug }}/
+abstract: >
+    {{ general.description }}
+keywords:
+  - python
+license: {{ general.license }}

instant_python/templates/boilerplate/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+Thank you for helping keep **{{ general.slug }}** package and its users safe.
+We take security issues seriously and appreciate responsible disclosures.
+
+## Reporting a Vulnerability
+
+> [!NOTE]
+> **Please do NOT open public issues for security reports.**
+> Use one of the private channels below so we can coordinate a safe disclosure.
+
+| Channel                      | How it works                                                                                                                  |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **GitHub Security Advisory** | 1. Navigate to the repository's **“Security → Advisories”** tab<br>2. Click **“Report a vulnerability”** and fill in the form |
+
+Include the following, if possible:
+
+1. A **concise description** of the issue and its impact.
+2. **Reproduction steps** or a proof-of-concept script.
+3. Any **mitigation** ideas you've identified.
+
+## Our Disclosure Process
+
+1. **Acknowledge** report within 24–48 hours.
+2. **Triage & validate** the issue; request additional info if needed.
+3. **Fix & prepare**: develop a patch and regression tests.
+4. **Coordinate release**:
+    - Agree on a disclosure date with the reporter (usually ≤ 30 days).
+    - Publish a CVE (if applicable) and a new PyPI release.
+    - Post a security advisory and update CHANGELOG.
+5. **Credit** the reporter (optional & with consent).
+
+## Responsible Disclosure
+
+We kindly ask you to:
+
+- Allow us reasonable time to remediate before any public disclosure.
+- Avoid violating user privacy, destroying data, or disrupting production services while researching.
+- Test only on your own instances or in minimal, isolated cases.
+
+We are committed to keeping this project and its users safe and will strive to resolve all legitimate reports swiftly and transparently.
+
+_Thank you for keeping the **{{ general.slug }}** package community secure!_

instant_python/templates/boilerplate/event_bus/{aggregate_root.py → event_aggregate.py}

@@ -1,8 +1,9 @@
 {% set template_domain_import = "shared.domain"|compute_base_path(template.name) %}
 from {{ general.source_name }}.{{ template_domain_import }}.event.domain_event import DomainEvent
+from {{ general.source_name }}.{{ template_domain_import }}.value_objects.aggregate import Aggregate
 
 
-class AggregateRoot:
+class EventAggregate(Aggregate):
     _domain_events: list[DomainEvent]
 
     def __init__(self) -> None:

instant_python/templates/boilerplate/exceptions/domain_error.py

@@ -1,22 +1,6 @@
-from abc import ABC
+{% set template_domain_import = "shared.domain"|compute_base_path(template.name) %}
+from {{ general.source_name }}.{{ template_domain_import }}.exceptions.error import Error
 
+class DomainError(Error):
+    ...
 
-class DomainError(Exception, ABC):
-    def __init__(self, message: str, error_type: str) -> None:
-        self._message = message
-        self._type = error_type
-        super().__init__(self._message)
-
-    @property
-    def type(self) -> str:
-        return self._type
-
-    @property
-    def message(self) -> str:
-        return self._message
-
-    def to_primitives(self) -> dict[str, str]:
-        return {
-            "type": self.type,
-            "message": self.message,
-        }

instant_python/templates/boilerplate/exceptions/error.py

@@ -0,0 +1,24 @@
+from abc import ABC
+
+
+class BaseError(Exception, ABC):
+	"""Base class for all controlled errors in the application."""
+
+	def __init__(self, message: str, error_type: str) -> None:
+		self._message = message
+		self._type = error_type
+		super().__init__(self._message)
+
+	@property
+	def type(self) -> str:
+		return self._type
+
+	@property
+	def message(self) -> str:
+		return self._message
+
+	def to_primitives(self) -> dict[str, str]:
+		return {
+			"type": self.type,
+			"message": self.message,
+		}

instant_python/templates/boilerplate/fastapi/application.py

@@ -1,7 +1,37 @@
 {% set template_domain_import = "shared.domain"|compute_base_path(template.name) %}
 {% set template_infra_import = "shared.infra"|compute_base_path(template.name) %}
-from fastapi import FastAPI, Request
-from fastapi.responses import JSONResponse
+from fastapi import FastAPI
+{% if "logger" in template.built_in_features %}
+from fastapi.exceptions import RequestValidationError
+{% endif %}
+
+{% if template.name == template_types.STANDARD %}
+{% if "logger" in template.built_in_features %}
+from {{ general.source_name }}.api.handlers.error_handlers import (
+	unexpected_exception_handler,
+	domain_error_handler,
+	validation_error_handler,
+)
+{% else %}
+from {{ general.source_name }}.api.handlers.error_handlers import (
+	unexpected_exception_handler,
+	domain_error_handler,
+)
+{% endif %}
+{% else %}
+{% if "logger" in template.built_in_features %}
+from {{ general.source_name }}.delivery.api.handlers.error_handlers import (
+	unexpected_exception_handler,
+	domain_error_handler,
+	validation_error_handler,
+)
+{% else %}
+from {{ general.source_name }}.delivery.api.handlers.error_handlers import (
+	unexpected_exception_handler,
+	domain_error_handler,
+)
+{% endif %}
+{% endif %}
 
 {% if ["async_alembic"] | is_in(template.built_in_features) %}
 {% if template.name == template_types.STANDARD %}
@@ -10,9 +40,15 @@ from {{ general.source_name }}.api.lifespan import lifespan
 from {{ general.source_name }}.delivery.api.lifespan import lifespan
 {% endif %}
 {% endif %}
-from {{ general.source_name }}.{{ template_infra_import }}.http.http_response import HttpResponse
-from {{ general.source_name }}.{{ template_infra_import }}.http.status_code import StatusCode
 from {{ general.source_name }}.{{ template_domain_import }}.exceptions.domain_error import DomainError
+{% if "logger" in template.built_in_features %}
+from {{ general.source_name }}.{{ template_infra_import }}.logger.file_logger import create_file_logger
+{% if template.name == template_types.STANDARD %}
+from {{ general.source_name }}.api.middleare.fast_api_log_middleware import FastapiLogMiddleware
+{% else %}
+from {{ general.source_name }}.delivery.api.middleare.fast_api_log_middleware import FastapiLogMiddleware
+{% endif %}
+{% endif %}
 
 
 {% if ["async_alembic"] | is_in(template.built_in_features) %}
@@ -21,11 +57,12 @@ app = FastAPI(lifespan=lifespan)
 app = FastAPI()
 {% endif %}
 
-@app.exception_handler(Exception)
-async def unexpected_exception_handler(_: Request, exc: Exception) -> JSONResponse:
-	return HttpResponse.internal_error(exc)
+{% if "logger" in template.built_in_features %}
+logger = create_file_logger(name="{{ general.slug }}")
 
+app.add_middleware(FastapiLogMiddleware, logger=logger)
+app.add_exception_handler(RequestValidationError, validation_error_handler)
+{% endif %}
+app.add_exception_handler(Exception, unexpected_exception_handler)
+app.add_exception_handler(DomainError, domain_error_handler)
 
-@app.exception_handler(DomainError)
-async def domain_error_handler(_: Request, exc: DomainError) -> JSONResponse:
-	return HttpResponse.domain_error(exc, status_code=StatusCode.BAD_REQUEST)

instant_python/templates/boilerplate/fastapi/error_handlers.py

@@ -0,0 +1,64 @@
+{% set template_domain_import = "shared.domain"|compute_base_path(template.name) %}
+{% set template_infra_import = "shared.infra"|compute_base_path(template.name) %}
+from fastapi import Request
+from fastapi.responses import JSONResponse
+{% if "logger" in template.built_in_features %}
+from fastapi.exceptions import RequestValidationError
+from fastapi.exception_handlers import request_validation_exception_handler
+from {{ general.source_name }}.{{ template_infra_import }}.logger.file_logger import create_file_logger
+{% endif %}
+from {{ general.source_name }}.{{ template_infra_import }}.http.error_response import InternalServerError, UnprocessableEntityError
+from {{ general.source_name }}.{{ template_domain_import }}.exceptions.domain_error import DomainError
+
+
+{% if "logger" in template.built_in_features %}
+logger = create_file_logger(name="{{ general.slug }}")
+
+async def unexpected_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+	logger.error(
+		message=f"error - {request.url.path}",
+		details={
+			"error": {
+				"message": str(exc),
+				"type": "unexpected_error",
+			},
+			"method": request.method,
+			"source": request.url.path,
+		},
+	)
+	return InternalServerError().as_json()
+
+
+async def domain_error_handler(request: Request, exc: DomainError) -> JSONResponse:
+	logger.error(
+		message=f"error - {request.url.path}",
+		details={
+			"error": exc.to_primitives(),
+			"method": request.method,
+			"source": request.url.path,
+		},
+	)
+	return UnprocessableEntityError().as_json()
+
+
+async def validation_error_handler(
+		request: Request,
+		exc: RequestValidationError,
+) -> JSONResponse:
+	logger.error(
+		message=f"error - {request.url.path}",
+		details={
+			"error": {"message": str(exc), "type": "validation_error"},
+			"method": request.method,
+			"source": request.url.path,
+		},
+	)
+	return await request_validation_exception_handler(request, exc)
+{% else %}
+async def unexpected_exception_handler(_: Request, __: Exception) -> JSONResponse:
+	return InternalServerError().as_json()
+
+
+async def domain_error_handler(_: Request, __: DomainError) -> JSONResponse:
+	return UnprocessableEntityError().as_json()
+{% endif %}

instant_python/templates/boilerplate/fastapi/error_response.py

@@ -0,0 +1,31 @@
+from abc import ABC
+
+from fastapi import status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(ABC, BaseModel):
+	status_code: int
+	detail: str
+
+	def as_json(self) -> JSONResponse:
+		return JSONResponse(
+			content={"detail": self.detail},
+			status_code=self.status_code,
+		)
+
+
+class UnprocessableEntityError(ErrorResponse):
+	status_code: int = Field(default=status.HTTP_422_UNPROCESSABLE_ENTITY)
+	detail: str = Field(default="Unprocessable Entity")
+
+
+class ResourceNotFoundError(ErrorResponse):
+	status_code: int = Field(default=status.HTTP_404_NOT_FOUND)
+	detail: str = Field(default="Not Found")
+
+
+class InternalServerError(ErrorResponse):
+	status_code: int = Field(default=status.HTTP_500_INTERNAL_SERVER_ERROR)
+	detail: str = Field(default="An unexpected error occurred.")

instant_python/templates/boilerplate/fastapi/fastapi_log_middleware.py

@@ -0,0 +1,33 @@
+{% set template_infra_import = "shared.infra"|compute_base_path(template.name) %}
+import time
+
+from fastapi import Request, Response, FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+
+from {{ general.source_name }}.{{ template_infra_import }}.logger.file_logger import FileLogger
+
+
+class FastapiLogMiddleware(BaseHTTPMiddleware):
+	def __init__(self, app: FastAPI, logger: FileLogger) -> None:
+		super().__init__(app)
+		self._logger = logger
+
+	async def dispatch(
+			self, request: Request, call_next: RequestResponseEndpoint
+	) -> Response:
+		start_time = time.perf_counter()
+		response = await call_next(request)
+		process_time = time.perf_counter() - start_time
+
+		if response.status_code < 400:
+			self._logger.info(
+				message=f"success - {request.url.path}",
+				details={
+					"method": request.method,
+					"source": request.url.path,
+					"process_time": process_time,
+					"status_code": response.status_code,
+				},
+			)
+
+		return response

instant_python/templates/boilerplate/fastapi/success_response.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+
+class SuccessResponse(BaseModel):
+	status_code: int
+	data: dict
+
+	def as_json(self) -> JSONResponse:
+		return JSONResponse(
+			content=self.data,
+			status_code=self.status_code,
+		)

instant_python/templates/boilerplate/github/action.yml

@@ -9,14 +9,27 @@ outputs: {}
 runs:
   using: composite
   steps:
-    - uses: actions/setup-python@v5
+    - name: 🐍 Setup Python
+      uses: actions/setup-python@v5
       with:
         python-version: {% raw %}${{ inputs.python-version }}{% endraw %}
 
-    - name: Install dependency manager
+    - name: 🔨 Install dependency manager
       run: python -m pip install {{ general.dependency_manager }}
       shell: bash
-    - name: Install dependencies
-      run: {% if general.dependency_manager == "uv" %}uv sync --all-groups{% elif general.dependency_manager == "pdm" %}pdm install {% endif %}
 
+    - name: 📦 Install dependencies
+      run: |
+        {% if general.dependency_manager == "uv" %}
+        uv sync --all-groups
+        {% elif general.dependency_manager == "pdm" %}
+        pdm install
+        {% endif %}
+        {% if "precommit_hook" in template.built_in_features %}
+        {% if general.dependency_manager == "uv" %}
+        uv run -m pre_commit install
+        {% elif general.dependency_manager == "pdm" %}
+        pdm run pre-commit install
+        {% endif %}
+        {% endif %}
       shell: bash

instant_python/templates/boilerplate/github/bug_report.yml

@@ -0,0 +1,60 @@
+name: 🐛 Bug Report
+description: Create a report to help us improve.
+labels:
+  - bug
+  - pending
+
+body:
+  - type: textarea
+    id: description
+    validations:
+      required: true
+    attributes:
+      label: ✏️ Description
+      description: |
+        Please provide a clear and concise description of the bug you are experiencing.
+        
+        Specify what is the expected behavior and what is actually happening. You can add
+        screenshots to help illustrate the issue.
+
+        Please provide as much detail as possible to make understanding and solving your problem as quick as possible. 🙏
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label:  ✅ Steps To Reproduce
+      render: Python
+      description: >
+        Please list the steps needed to reproduce the bug you are experiencing.
+
+        If applicable, please add a self-contained,
+        [minimal, reproducible, example](https://stackoverflow.com/help/minimal-reproducible-example)
+        demonstrating the bug.\
+
+      placeholder: >
+        # 1. Install the package using pip
+        # 2. Run the script with the following command:
+        #    python script.py
+        # 3. Observe the output\
+
+  - type: dropdown
+    id: python-version
+    attributes:
+      label: 🐍  Which version of Python are you using?
+      options:
+        - 3.8
+        - 3.9
+        - 3.10
+        - 3.11
+        - 3.12
+        - 3.13
+        - other
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    validations:
+      required: true
+    attributes:
+      label: 🖥️  Which operating system are you using?