PythonTemplateIt

Category	Status and Links
General
CD/CI
PyPI
GitHub

Short description

PythonTemplateIt is a reusable template for Python projects with standardized packaging, linting, testing, environment bootstrapping, and GitHub workflow automation.

Module Overview

Key Features

• Poetry-based project packaging and dependency management.
• Published package layout rooted under src/pti/ for template imports such as import pti.pythontemplateit.
• Pre-configured quality tooling (black, isort, flake8, pytest, pre-commit).
• PowerShell and shell scripts for Python setup, optional React setup, private repository access, and Docker-assisted database provisioning.
• Dependabot automation for Poetry dependencies, GitHub Actions workflows, and Docker image updates.
• Local Docker workflows provision MySQL and Redis services with health checks for template-based projects that need backing services.
• Reusable CI/CD workflows for pull request validation and post-merge release/publish handling.
• Release note and versioning conventions aligned to SemVer.

Project Structure

• src/pti/: Template Python package source used by the published distribution.
• src/: Application modules and package source code.
• tests/: Unit and functional test suites with fixtures and test data.
• scripts/: SQL/bootstrap assets.
• docker-compose.yaml: Local MySQL and Redis service definitions for development and end-to-end environments.
• legacy/: Archived or excluded legacy resources.
• *.ps1: Setup and automation scripts for environment and toolchain tasks.

Getting Started

Prerequisites

• Python 3.12+
• Poetry
• Docker (optional, for local MySQL and Redis services)
• GitHub access token(s) for private package sources when needed

Setup

# 1) Generate .env from the SetupDotEnv script
.\SetupDotEnv.ps1

# 2) Configure private repository access for Poetry
.\SetupPrivateRepoAccess.ps1

# 3) Install Python tooling and project dependencies
.\InstallPy.ps1

# 4) Optional: configure GitHub CLI access
.\SetupGitHubAccess.ps1

# 5) Refresh development dependencies directly when needed
.\InstallDevEnv.ps1

# 6) Optional: start the local service stack
.\SetUpDocker.ps1
# or
# docker compose up -d db

# 7) Run tests
poetry run pytest

Optional Frontend Bootstrap

# Use these only in repos that also contain a Node/React app
.\InstallReact.ps1
# or
bash ./install_react.sh

Common Commands

poetry install
poetry run pytest
poetry run pytest --cov=src --cov=tests --cov-report=term-missing
poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run pre-commit run --all-files

Automation Scripts

• InstallPy.ps1: Bootstraps Poetry tooling, updates the repository remote when credentials are available, and installs Python dependencies.
• InstallDevEnv.ps1: Installs development dependencies and configures pre-commit tooling.
• InstallReact.ps1: Installs Node dependencies for React projects on Windows and configures pre-commit when available.
• install_react.sh: Bash equivalent of the React installer for non-PowerShell environments.
• SetupDotEnv.ps1: Generates .env values from environment variables.
• SetupPrivateRepoAccess.ps1: Configures private package source credentials.
• SetupGitHubAccess.ps1: Configures GitHub authentication for local automation.
• SetUpDocker.ps1: Recreates the local compose stack in detached mode and is intended for workflows where resetting local database state is acceptable.
• CreateDbSqlScript.ps1: Generates SQL bootstrap scripts for MySQL setup.

Active Workflows

• .github/workflows/py-temp-pr-pub-no_docker-def.yaml: Pull request validation workflow.
• .github/workflows/py-temp-publish-pub-build_release_notify_after_merge-def.yaml: Release build, publish, and notification workflow after merge to master, excluding Dependabot-triggered merges.
• .github/dependabot.yaml: Automated dependency update checks for Poetry packages, GitHub Actions workflows, and Docker assets.