instant-python 0.20.0__py3-none-any.whl

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,32 @@
+import time
+
+from fastapi import Request, Response, FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+
+from {{ general.source_name }}{{ "shared.infra.logger.file_logger" | resolve_import_path(template.name) }} 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/lifespan.py

@@ -0,0 +1,13 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from {{ general.source_name }}{{ "shared.infra.alembic_migrator" | resolve_import_path(template.name) }} import AlembicMigrator
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncGenerator[None, None]:
+	migrator = AlembicMigrator()
+	await migrator.migrate()
+	yield

instant_python/templates/boilerplate/fastapi/success_response.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+from fastapi.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

@@ -0,0 +1,35 @@
+name: Install Python and setup environment
+
+inputs:
+  python-version:
+    description: 'The version of Python to use'
+    required: false
+    default: {{ general.python_version }}
+outputs: {}
+runs:
+  using: composite
+  steps:
+    - name: 🐍 Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: {% raw %}${{ inputs.python-version }}{% endraw %}
+
+    - 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 %}
+        {% 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?

instant_python/templates/boilerplate/github/ci.yml

@@ -0,0 +1,199 @@
+name: Testing and Code analysis
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: {% raw %}${{ github.head_ref }}{% endraw %}
+
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🧐 Check linting
+        run: make check-lint
+
+  format:
+    name: format
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: {% raw %}${{ github.head_ref }}{% endraw %}
+
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🧐 Check code format
+        run: make check-format
+
+  typing:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: {% raw %}${{ github.head_ref }}{% endraw %}
+
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🧐 Check static types
+        run: make check-typing
+
+  analyze-code-quality:
+    name: analyze-code-quality
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: {% raw %}${{ github.head_ref }}{% endraw %}
+
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: ▶️ CodeQL Initialization
+        uses: github/codeql-action/init@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2
+        with:
+          languages: python
+          build-mode: none
+          queries: +security-extended,security-and-quality
+      #          config-file: ./codeql-config.yml
+
+      - name: 🧐 CodeQL Analysis
+        uses: github/codeql-action/analyze@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2
+        with:
+          category: '/language:python'
+
+  {% if "precommit_hooks" in template.built_in_features %}
+  secrets:
+    name: secrets-scan
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+      pull-requests: write
+
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🏃 Run secrets scanner
+        run: make secrets
+  {% endif %}
+
+  audit:
+    name: audit-dependencies
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🏃 Run audit
+        run: make audit
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 📦 Install test dependencies
+        run: {{ general.dependency_manager }} add pytest pytest-cov
+
+      - name: 🏃 Run tests
+        run: {{ general.dependency_manager }} run pytest --cov --cov-report=xml --cov-branch test -ra -s
+
+      - name: 📥 Upload coverage report to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          flags: unittests
+          name: codecov-coverage
+          token: {% raw %}${{ secrets.CODECOV_TOKEN }}{% endraw %}
+
+          slug: {{ git.username }}/{{ general.slug }}

instant_python/templates/boilerplate/github/feature_request.yml

@@ -0,0 +1,21 @@
+name: 🚀 Feature Request
+description: Suggest a new idea for {{ general.slug }}.
+labels:
+  - enhancement
+  - pending
+
+body:
+  - type: textarea
+    id: description
+    validations:
+      required: true
+    attributes:
+      label: ✏️ Description
+      description: |
+        Please give as much detail as possible about the feature you would like to suggest.
+
+        You might like to add:
+        * A clear and concise description of the idea that should be implemented
+        * An example of how the feature should work
+        * Any relevant links or resources that can help understand the feature better
+        * A list of scenarios or validations that the feature should cover as well as any restrictions or limitations that should be considered

instant_python/templates/boilerplate/github/release.yml

@@ -0,0 +1,94 @@
+# To be able to use this GitHub workflow, you need to follow these steps:
+# Prerequisites:
+# 1. Generate a SSH key pair for signing releases: ssh-keygen -t ed25519 -C "<your-email>" -f ~/.ssh/github_actions
+# Configuration:
+# 1. In your GitHub repository, go to Settings > Secrets and variables > Actions.
+# 2. In the _Secrets_ tab, create a new repository secret named `SSH_PRIVATE_SIGNING_KEY` and paste the contents of your private key file (e.g., `cat ~/.ssh/github_actions`).
+# 3. In the _Variables_ tab, create the following repository variables:
+#    - `GIT_COMMITTER_EMAIL`: The email address you want to use for committing changes (e.g., `github-actions[bot]@users.noreply.github.com`).
+#    - `GIT_COMMITTER_NAME`: The name you want to use for committing changes (e.g., `github-actions[bot]`).
+#    - `SSH_PUBLIC_SIGNING_KEY`: The contents of your public key file (e.g., `cat ~/.ssh/github_actions.pub`).
+name: Release and Publish
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: {% raw %}${{ steps.released.outputs.released }}{% endraw %}
+
+      tag: {% raw %}${{ steps.released.outputs.tag }}{% endraw %}
+
+
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: 🔖 Create release
+        id: released
+        uses: python-semantic-release/python-semantic-release@2896129e02bb7809d2cf0c1b8e9e795ee27acbcf # v10.0.2
+        with:
+          build: true
+          push: true
+          changelog: true
+          commit: true
+          tag: true
+          vcs_release: true
+          config_file: pyproject.toml
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+
+          git_committer_email: {% raw %}${{ vars.GIT_COMMITTER_EMAIL }}{% endraw %}
+
+          git_committer_name: {% raw %}${{ vars.GIT_COMMITTER_NAME }}{% endraw %}
+
+          ssh_public_signing_key: {% raw %}${{ vars.SSH_PUBLIC_SIGNING_KEY }}{% endraw %}
+
+          ssh_private_signing_key: {% raw %}${{ secrets.SSH_PRIVATE_SIGNING_KEY }}{% endraw %}
+
+
+  build-and-publish:
+    name: Publish to PyPI
+    needs:
+      - release
+    if: {% raw %}needs.release.outputs.released == 'true'{% endraw %}
+
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - name: 🛡️ Harden runner
+        uses: step-security/harden-runner@6c439dc8bdf85cadbbce9ed30d1c7b959517bc49 # v2.12.2
+        with:
+          egress-policy: audit
+
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: refs/tags/{% raw %}${{ needs.release.outputs.tag }}{% endraw %}
+
+
+      - name: 🛠️ Setup environment
+        uses: ./.github/actions/python_setup
+
+      - name: 🏃 Build package
+        run: {{ general.dependency_manager }} build
+
+      - name: 🚀 Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

instant_python/templates/boilerplate/logger/file_logger.py

@@ -0,0 +1,55 @@
+import logging
+
+from {{ general.source_name }}{{ "shared.infra.logger.file_rotating_handler" | resolve_import_path(template.name) }} import TimeRotatingFileHandler
+
+
+class FileLogger:
+	def __init__(self, name: str, handlers: list[logging.Handler]) -> None:
+		self._logger = logging.getLogger(name)
+		self._logger.setLevel(logging.DEBUG)
+
+		if not self._logger.hasHandlers():
+			self._logger.handlers.extend(handlers)
+
+	def debug(self, message: str, details: dict) -> None:
+		self._logger.debug(
+			msg=message,
+			extra={"details": details},
+		)
+
+	def info(self, message: str, details: dict) -> None:
+		self._logger.info(
+			msg=message,
+			extra={"details": details},
+		)
+
+	def warning(self, message: str, details: dict) -> None:
+		raise NotImplementedError
+
+	def error(self, message: str, details: dict) -> None:
+		self._logger.error(
+			msg=message,
+			extra={"details": details},
+		)
+
+	def critical(self, message: str, details: dict) -> None:
+		self._logger.critical(
+			msg=message,
+			extra={"details": details},
+		)
+
+
+def create_file_logger(name: str) -> FileLogger:
+	return FileLogger(
+		name=name,
+		handlers=[
+			TimeRotatingFileHandler.create(
+				file_name="production",
+				level_to_record=logging.ERROR,
+			),
+			TimeRotatingFileHandler.create(
+				file_name="dev",
+				level_to_record=logging.DEBUG,
+			),
+		],
+	)

instant_python/templates/boilerplate/logger/file_rotating_handler.py

@@ -0,0 +1,36 @@
+import logging
+from collections.abc import Sequence
+from datetime import date
+from logging.handlers import TimedRotatingFileHandler
+from pathlib import Path
+from typing import Self
+
+from {{ general.source_name }}{{ "shared.infra.logger.json_formatter" | resolve_import_path(template.name) }} import JSONFormatter
+
+
+class TimeRotatingFileHandler(logging.Handler):
+	@classmethod
+	def create(cls, file_name: str, level_to_record: int) -> Self:
+		root_project_path = cls.find_project_root(markers=["pyproject.toml"])
+		log_folder = root_project_path / "logs"
+		log_folder.mkdir(parents=True, exist_ok=True)
+
+		handler = TimedRotatingFileHandler(
+			filename=f"{log_folder}/{file_name}_{date.today().isoformat()}.log",
+			when="midnight",
+			interval=1,
+			backupCount=7,
+			encoding="utf-8",
+		)
+		handler.setFormatter(JSONFormatter())
+		handler.setLevel(level_to_record)
+
+		return handler
+
+	@classmethod
+	def find_project_root(cls, markers: Sequence[str]) -> Path:
+		start = Path(__file__).resolve()
+		for parent in (start, *start.parents):
+			if any((parent / marker).exists() for marker in markers):
+				return parent
+		raise FileNotFoundError(f"Could not find project root (markers: {markers}).")

instant_python/templates/boilerplate/logger/json_formatter.py

@@ -0,0 +1,16 @@
+import json
+import logging
+
+
+class JSONFormatter(logging.Formatter):
+	def format(self, record: logging.LogRecord) -> str:
+		log_record = {
+			"time": self.formatTime(record, self.datefmt),
+			"level": record.levelname,
+			"name": record.name,
+			"message": record.getMessage(),
+		}
+		if hasattr(record, "details"):
+			log_record["details"] = record.details
+
+		return json.dumps(log_record)

instant_python/templates/boilerplate/mypy.ini

@@ -0,0 +1,41 @@
+[mypy]
+files = src, tests
+python_version = {{ general.python_version }}
+mypy_path = .
+disable_error_code = override,attr-defined
+check_untyped_defs = true
+disallow_any_explicit = false
+
+# None and Optional handling
+no_implicit_optional = true
+
+# Configuring warnings
+warn_redundant_casts = true
+warn_unused_ignores = false
+warn_no_return = true
+warn_return_any = true
+warn_unreachable = true
+
+# Miscellaneous strictness flags
+implicit_reexport = true
+strict_equality = true
+
+# Configuring error messages
+show_error_context = true
+show_column_numbers = true
+show_error_codes = true
+pretty = true
+show_absolute_path = false
+
+disallow_untyped_defs = true
+
+[mypy-expects.*]
+ignore_missing_imports = True
+[mypy-doublex.*]
+ignore_missing_imports = True
+[mypy-src.*]
+ignore_missing_imports = True
+[mypy-tests.*]
+disallow_untyped_defs = False
+[mypy-doublex_expects.*]
+ignore_missing_imports = True

instant_python/templates/boilerplate/persistence/alembic_migrator.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from {{ general.source_name }}{{ "shared.infra.persistence.postgres_settings" | resolve_import_path(template.name) }} import PostgresSettings
+from alembic import command
+from alembic.config import Config
+
+
+class AlembicMigrator:
+	def __init__(self) -> None:
+		self._settings = PostgresSettings()  # type: ignore
+		self._alembic_config = Config()
+
+	async def migrate(self) -> None:
+		self._alembic_config.set_main_option(
+			"sqlalchemy.url", self._settings.postgres_url
+		)
+		self._alembic_config.set_main_option("script_location", "migrations")
+		loop = asyncio.get_event_loop()
+		await loop.run_in_executor(None, command.upgrade, self._alembic_config, "head")  # type: ignore

instant_python/templates/boilerplate/persistence/async/README.md

@@ -0,0 +1 @@
+Generic single-database configuration with an async dbapi.