CI-templates/README-python-code-quality.md

Python Code Quality Pipeline Template

A reusable Gitea Actions workflow for Python code quality checks including type checking, linting, and formatting.

Features

• Type checking with mypy
• Linting with ruff
• Code formatting with ruff
• Python version upgrades with pyupgrade
• Flexible configuration with optional steps and customizable inputs

Usage

To use this reusable workflow in your repository, create a workflow file (e.g., .gitea/workflows/python/code-quality.yml) in your target repository:

Basic Usage

name: Code Quality

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  code-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0

Advanced Usage with Custom Inputs

name: Code Quality

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  code-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0
    with:
      python-version: "3.11"
      working-directory: "./backend"
      uv-extras: "dev,test"

Available Inputs

Input	Description	Required	Default	Type
python-version	Python version to use (e.g., "3.12")	No	"3.12"	string
working-directory	Working directory for the project	No	"."	string
skip-mypy	Skip mypy type checking	No	false	boolean
skip-pyupgrade	Skip pyupgrade check	No	false	boolean
uv-extras	UV extras to install (e.g., "dev,test")	No	"all-extras"	string

Requirements

Your Python project should have:

1. A pyproject.toml file with uv dependency management
2. Properly configured tools:
   • mypy for type checking (if not skipped)
   • ruff for linting and formatting
   • pyupgrade for Python version upgrades (if not skipped)
3. Optional: prettier configuration for non-Python files (if not skipped)

Examples

Skip mypy for a project without type hints

jobs:
  code-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0
    with:
      skip-mypy: true

Use specific Python version and extras

jobs:
  code-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0
    with:
      python-version: "3.11"
      uv-extras: "dev,lint"

Monorepo with specific working directory

jobs:
  backend-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0
    with:
      working-directory: "./backend"
      
  ml-service-quality:
    uses: gitea.gt-proj.com/brian/CI-templates/.gitea/workflows/python/code-quality.yml@v1.0.0
    with:
      working-directory: "./ml-service"
      python-version: "3.11"

Repository Structure

For this template to work properly, ensure your repository has the workflow file in the correct location:

.gitea/
  workflows/
    python/
      code-quality.yml  # This reusable workflow

Contributing

To update this template, modify the workflow file and ensure all changes are backward compatible or properly versioned using git tags.