pyTooling Actions Documentation

pyTooling Actions are reusable steps and workflows for GitHub Actions easing the creation and maintenance of workflows for Python projects on GitHub.

Introduction

GitHub Actions workflows, actions and documentation are mostly focused on JavaScript/TypeScript as the scripting language for writing reusable CI code. However, Python being equally popular and capable, usage of JS/TS might be bypassed, with some caveats. This repository gathers reusable CI tooling for testing, packaging and distributing Python projects and documentation.

GitHub Actions

Post-Processing

with-post-step

Deprecated

Releaser

GitHub Action Job Templates

The following list categorizes all pre-defined job templates, which can be instantiated in a pipeline (GitHub Action Workflow):

All-In-One

CompletePipeline

Pipeline Setup

Documentation

Unit Tests, Code Coverage

Code Quality

StaticTypeCheck
code formatting (planned)
coding style (planned)
code linting (planned)

Build and Packaging

Publishing

Releasing

Cleanup

Deprecated

Example Pipelines

ExamplePipeline.yml is an example Workflow which uses all of the Reusable Workflows. Python package/tool developers can copy it into their repos, in order to use al the reusable workflows straightaway. Minimal required modifications are the following:

Set the name input of job Parameters.
Specify the commands input of job StaticTypeCheck.

Behavior

Infer information from ${{ github.ref }} variable.
Extract Python project settings from pyproject.toml.
Compute job matrix based on system, Python version, environment, … for job variants.
Run unit tests using pytest and collect code coverage.
Run platform tests using pytest and collect code coverage.
Run application tests using pytest.
Package code as wheel.
Check documentation coverage using docstr_coverage and interrogate.
Verify type annotation using static typing analysis using mypy.
Merge unit test results and code coverage results.
Generate HTML and LaTeX documentations using Sphinx.
Translate LaTeX documentation to PDF using MikTeX.
Publish unit test and code coverage results to cloud services.
Publish documentation to GitHub Pages.
Publish wheel to PyPI.
Create a GitHub release page and upload release assets.

Directory Structure

<RepositoryRoot>/
  .github/
    workflows/
      Pipeline.yml
  dist/
    requirements.txt
  docs/
    conf.py
    index.rst
    requirements.txt
  myPackage/
    ModuleA.py
    __init__.py
    py.typed
  tests/
    unit/
      TestA.py
      requirements.txt
    requirements.txt
  .editorconfig
  .gitignore
  LICENSE.md
  pyproject.toml
  README.md
  requirements.txt
  setup.py

Simple Package

name: Pipeline

on:
  push:
  workflow_dispatch:
  schedule:
# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
    - cron: '0 22 * * 5'

jobs:
  SimplePackage:
    uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
    with:
      package_name: myPackage
      codecov:      true
      codacy:       true
      dorny:        true
    secrets:
      PYPI_TOKEN:    ${{ secrets.PYPI_TOKEN }}
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
      CODACY_TOKEN:  ${{ secrets.CODACY_TOKEN }}

Namespace Package

name: Pipeline

on:
  push:
  workflow_dispatch:
  schedule:
# Every Friday at 22:00 - rerun pipeline to check for dependency-based issues
    - cron: '0 22 * * 5'

jobs:
  NamespacePackage:
    uses: pyTooling/Actions/.github/workflows/CompletePipeline.yml@r5
    with:
      package_namespace: myFramework
      package_name:      Extension
      codecov:           true
      codacy:            true
      dorny:             true
    secrets:
      PYPI_TOKEN:    ${{ secrets.PYPI_TOKEN }}
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
      CODACY_TOKEN:  ${{ secrets.CODACY_TOKEN }}

pyproject.toml

[build-system]
requires = ["setuptools >= 80.0", "wheel ~= 0.45", "pyTooling ~= 8.5"]
build-backend = "setuptools.build_meta"

[tool.mypy]
packages = ["myPackage"]
python_version = "3.13"
strict = true
pretty = true
show_error_context = true
show_error_codes = true
namespace_packages = true
html_report = "report/typing"

[tool.pytest]
junit_xml = "report/unit/UnittestReportSummary.xml"

[tool.pyedaa-reports]
junit_xml = "report/unit/unittest.xml"

[tool.pytest.ini_options]
addopts = "--tb=native"
python_files = "*"
python_functions = "test_*"
filterwarnings = ["error::DeprecationWarning", "error::PendingDeprecationWarning"]
junit_logging = "all"

[tool.interrogate]
color = true
verbose = 1             # possible values: 0 (minimal output), 1 (-v), 2 (-vv)
fail-under = 59
ignore-setters = true

[tool.coverage.run]
branch = true
relative_files = true
omit = ["*site-packages*", "setup.py", "tests/unit/*"]

[tool.coverage.report]
skip_covered = false
skip_empty = true
exclude_lines = ["pragma: no cover", "raise NotImplementedError"]
omit = ["tests/*"]

[tool.coverage.xml]
output = "report/coverage/coverage.xml"

[tool.coverage.json]
output = "report/coverage/coverage.json"

[tool.coverage.html]
directory = "report/coverage/html"
title="Code Coverage of myPackage"

_images/pyTooling-Actions-SimplePackage.png

References

hdl/containers#48

Contributors

License

This Python package (source code) is licensed under Apache License 2.0.
The accompanying documentation is licensed under Creative Commons - Attribution 4.0 (CC-BY 4.0).