add reusable workflows

.github/workflows/BuildTheDocs.yml

@@ -0,0 +1,31 @@
+name: Documentation
+
+on:
+  workflow_call:
+    inputs:
+      artifact:
+        description: 'Name of the documentation artifact.'
+        required: true
+        type: string
+
+jobs:
+
+  BuildTheDocs:
+    name: 📓 Run BuildTheDocs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🛳️ Build documentation
+        uses: buildthedocs/btd@v0
+        with:
+          skip-deploy: true
+
+      - name: 📤 Upload 'documentation' artifacts
+        uses: actions/upload-artifact@master
+        with:
+          name: ${{ inputs.artifact }}
+          path: doc/_build/html
+          retention-days: 7

.github/workflows/CoverageCollection.yml

@@ -0,0 +1,75 @@
+name: Coverage Collection
+
+on:
+  workflow_call:
+    inputs:
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+      artifact:
+        description: 'Name of the coverage artifact.'
+        required: true
+        type: string
+    secrets:
+      codacy_token:
+        description: 'Token to push result to codacy.'
+        required: true
+
+jobs:
+
+  Coverage:
+    name: 📈 Collect Coverage Data using Python ${{ inputs.pyver }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⏬ Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🐍 Setup Python ${{ inputs.pyver }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ inputs.pyver }}
+
+      - name: 🗂 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/requirements.txt
+
+      - name: Collect coverage
+        continue-on-error: true
+        run: |
+          python -m pytest -rA --cov=.. --cov-config=tests/.coveragerc tests/unit --color=yes
+
+      - name: Convert to cobertura format
+        run: coverage xml
+
+      - name: Convert to HTML format
+        run: |
+          coverage html
+          rm htmlcov/.gitignore
+
+      - name: 📤 Upload 'Coverage Report' artifact
+        continue-on-error: true
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ inputs.artifact }}
+          path: htmlcov
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: 📊 Publish coverage at CodeCov
+        continue-on-error: true
+        uses: codecov/codecov-action@v1
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          env_vars: PYTHON
+
+      - name: 📉 Publish coverage at Codacy
+        continue-on-error: true
+        uses: codacy/codacy-coverage-reporter-action@master
+        with:
+          project-token: ${{ secrets.codacy_token }}
+          coverage-reports: ./coverage.xml

.github/workflows/Package.yml

@@ -0,0 +1,48 @@
+name: Package
+
+on:
+  workflow_call:
+    inputs:
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+      artifact:
+        description: 'Name of the wheel artifact.'
+        required: true
+        type: string
+
+jobs:
+
+  Package:
+    name: 📦 Package in Wheel Format
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🐍 Setup Python ${{ inputs.pyver }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ inputs.pyver }}
+
+      - name: 🔧 Install dependencies for packaging and release
+        run: |
+          python -m pip install --upgrade pip
+          pip install wheel
+
+      - name: 🔨 Build Python package (source distribution)
+        run: python setup.py sdist
+
+      - name: 🔨 Build Python package (binary distribution - wheel)
+        run: python setup.py bdist_wheel
+
+      - name: 📤 Upload wheel artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ inputs.artifact }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1

.github/workflows/Params.yml

@@ -0,0 +1,42 @@
+name: Params
+
+on:
+  workflow_call:
+    inputs:
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+      name:
+        description: 'Name of the tool.'
+        required: true
+        type: string
+    outputs:
+      params:
+        description: "Parameters to be used in other jobs."
+        value: ${{ jobs.Params.outputs.params }}
+
+jobs:
+
+  Params:
+    runs-on: ubuntu-latest
+    outputs:
+      params: ${{ steps.params.outputs.params }}
+    steps:
+
+      - id: params
+        shell: python
+        run: |
+          name = '${{ inputs.name }}'
+          params = {
+            'package': name,
+            'pyver': '${{ inputs.pyver }}',
+            'artifacts': {
+              'coverage': f'{name}-coverage',
+              'typing': f'{name}-typing',
+              'wheel': f'{name}-wheel',
+              'doc': f'{name}-doc',
+            }
+          }
+          print(f'::set-output name=params::{params!s}')

.github/workflows/PublishOnPyPI.yml

@@ -0,0 +1,53 @@
+name: Publish on PyPI
+
+on:
+  workflow_call:
+    inputs:
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+      artifact:
+        description: 'Name of the wheel artifact.'
+        required: true
+        type: string
+    secrets:
+      PYPI_TOKEN:
+        description: "Token for pushing releases to PyPI"
+        required: false
+
+jobs:
+
+  PublishOnPyPI:
+    name: 🚀 Publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Download artifacts '${{ inputs.artifact }}' from 'Package' job
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ inputs.artifact }}
+          path: dist/
+
+      - name: 🐍 Setup Python ${{ inputs.pyver }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ inputs.pyver }}
+
+      - name: ⚙ Install dependencies for packaging and release
+        run: |
+          python -m pip install --upgrade pip
+          pip install wheel twine
+
+      - name: ⤴ Release Python package to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          twine upload dist/*
+
+      - name: 🗑️ Delete packaging Artifacts
+        uses: geekyeggo/delete-artifact@v1
+        with:
+          name: ${{ inputs.artifact }}

.github/workflows/PublishToGitHubPages.yml

@@ -0,0 +1,62 @@
+name: Publish to GitHub Pages
+
+on:
+  workflow_call:
+    inputs:
+      doc:
+        description: 'Name of the documentation artifact.'
+        required: true
+        type: string
+      coverage:
+        description: 'Name of the coverage artifact.'
+        required: false
+        default: ''
+        type: string
+      typing:
+        description: 'Name of the typing artifact.'
+        required: false
+        default: ''
+        type: string
+
+jobs:
+
+  PublishToGitHubPages:
+    name: 📚 Publish to GH-Pages
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 📥 Download artifacts '${{ inputs.doc }}' from 'BuildTheDocs' job
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ inputs.doc }}
+          path: public
+
+      - name: 📥 Download artifacts '${{ inputs.coverage }}' from 'Coverage' job
+        if: ${{ inputs.coverage != '' }}
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ inputs.coverage }}
+          path: public/coverage
+
+      - name: 📥 Download artifacts '${{ inputs.typing }}' from 'StaticTypeCheck' job
+        if: ${{ inputs.typing != '' }}
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ inputs.typing }}
+          path: public/typing
+
+      - name: '📓 Publish site to GitHub Pages'
+        if: github.event_name != 'pull_request'
+        run: |
+          cd public
+          touch .nojekyll
+          git init
+          cp ../.git/config ./.git/config
+          git add .
+          git config --local user.email "BuildTheDocs@GitHubActions"
+          git config --local user.name "GitHub Actions"
+          git commit -a -m "update ${{ github.sha }}"
+          git push -u origin +HEAD:gh-pages

.github/workflows/Release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  workflow_call:
+
+jobs:
+
+  Release:
+    name: 📝 Create 'Release Page' on GitHub
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 🔁 Extract Git tag from GITHUB_REF
+        id: getVariables
+        run: |
+          GIT_TAG=${GITHUB_REF#refs/*/}
+          RELEASE_VERSION=${GIT_TAG#v}
+          RELEASE_DATETIME="$(date --utc '+%d.%m.%Y - %H:%M:%S')"
+          # write to step outputs
+          echo ::set-output name=gitTag::${GIT_TAG}
+          echo ::set-output name=version::${RELEASE_VERSION}
+          echo ::set-output name=datetime::${RELEASE_DATETIME}
+
+      - name: 📑 Create Release Page
+        id: createReleasePage
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        with:
+          tag_name: ${{ steps.getVariables.outputs.gitTag }}
+#          release_name: ${{ steps.getVariables.outputs.gitTag }}
+          body: |
+            **Automated Release created on: ${{ steps.getVariables.outputs.datetime }}**
+
+            # New Features
+            * tbd
+
+            # Changes
+            * tbd
+
+            # Bug Fixes
+            * tbd
+          draft: false
+          prerelease: false

.github/workflows/StaticTypeCheck.yml

@@ -0,0 +1,53 @@
+name: Static Type Check
+
+on:
+  workflow_call:
+    inputs:
+      package:
+        description: 'Name of the Python package.'
+        required: true
+        type: string
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+      artifact:
+        description: 'Name of the coverage artifact.'
+        required: true
+        type: string
+
+jobs:
+
+  StaticTypeCheck:
+    name: 👀 Check Static Typing using Python ${{ inputs.pyver }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⏬ Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🐍 Setup Python ${{ inputs.pyver }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ inputs.pyver }}
+
+      - name: 🗂 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/requirements.txt
+
+      - name: Check Static Typing
+        continue-on-error: true
+        run: |
+          pwd
+          mypy --html-report htmlmypy -m ${{ inputs.package }}
+
+      - name: 📤 Upload 'Static Typing Report' artifact
+        continue-on-error: true
+        uses: actions/upload-artifact@v2
+        with:
+          name: ${{ inputs.artifact }}
+          path: htmlmypy
+          if-no-files-found: error
+          retention-days: 1

.github/workflows/UnitTesting.yml

@@ -0,0 +1,54 @@
+name: Unit Testing
+
+on:
+  workflow_call:
+    inputs:
+      TestReport:
+        description: "Generate unit test report with junitxml and upload results as an artifact."
+        required: false
+        default: false
+        type: string
+
+jobs:
+
+  UnitTesting:
+    name: ${{ matrix.icon }} Unit Tests using Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+#          - {python: "3.6",  icon: 🔴} # until 23.12.2021
+          - {python: "3.7",  icon: 🟠} # until 27.06.2023
+          - {python: "3.8",  icon: 🟡} # until Oct. 2024
+          - {python: "3.9",  icon: 🟢} # until Oct. 2025
+          - {python: "3.10", icon: 🟢} # until Oct. 2026
+
+    steps:
+      - name: ⏬ Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🐍 Setup Python ${{ matrix.python }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: 🔧 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/requirements.txt
+
+      - name: ☑ Run unit tests
+        run: |
+          [ '${{ inputs.TestReport }}' = 'true' ] && PYTEST_ARGS='--junitxml=TestReport.xml' || unset PYTEST_ARGS
+          python -m pytest -rA tests/unit $PYTEST_ARGS --color=yes
+
+      - name: 📤 Upload 'TestReport.xml' artifact
+        if: inputs.TestReport == 'true'
+        uses: actions/upload-artifact@v2
+        with:
+          name: TestReport-${{ matrix.python }}
+          path: TestReport.xml
+          if-no-files-found: error
+          retention-days: 1

.github/workflows/VerifyDocs.yml

@@ -0,0 +1,56 @@
+name: Verify examples
+
+on:
+  workflow_call:
+    inputs:
+      pyver:
+        description: 'Python version.'
+        required: false
+        default: '3.10'
+        type: string
+
+jobs:
+
+  VerifyDocs:
+    name: 👍 Verify example snippets using Python ${{ inputs.pyver }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⏬ Checkout repository
+        uses: actions/checkout@v2
+
+      - name: 🐍 Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ inputs.pyver }}
+
+      - name: 🐍 Install dependencies
+        run: |
+          pip3 install .
+
+      - name: ✂ Extract code snippet from README
+        shell: python
+        run: |
+          from pathlib import Path
+          import re
+
+          ROOT = Path('.')
+
+          with (ROOT / 'README.md').open('r') as rptr:
+              content = rptr.read()
+
+          m = re.search(r"```py(thon)?(?P<code>.*?)```", content, re.MULTILINE|re.DOTALL)
+
+          if m is None:
+              raise Exception("Regular expression did not find the example in the README!")
+
+          with (ROOT / 'tests/docs/example.py').open('w') as wptr:
+              wptr.write(m["code"])
+
+      - name: Print example.py
+        run: cat tests/docs/example.py
+
+      - name: ☑ Run example snippet
+        working-directory: tests/docs
+        run: |
+          python3 example.py

ExamplePipeline.yml

@@ -0,0 +1,115 @@
+name: Unit Testing, Coverage Collection, Package, Release, Documentation and Publish
+
+on:
+  workflow_dispatch:
+
+jobs:
+
+  # This job is a workaround for global variables
+  # See https://github.com/actions/runner/issues/480
+  Params:
+    uses: pyTooling/Actions/.github/workflows/Params.yml@dev
+    with:
+      name: ToolName
+
+  UnitTesting:
+    uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev
+    with:
+      TestReport: true
+
+  Coverage:
+    uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev
+    needs:
+      - Params
+    with:
+      pyver: ${{ fromJson(needs.Params.outputs.params).pyver }}
+      artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.coverage }}
+    secrets:
+      codacy_token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+
+  StaticTypeCheck:
+    uses: pyTooling/Actions/.github/workflows/StaticTypeCheck.yml@dev
+    needs:
+      - Params
+    with:
+      package: ${{ fromJson(needs.Params.outputs.params).package }}
+      pyver: ${{ fromJson(needs.Params.outputs.params).pyver }}
+      artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.typing }}
+
+  Release:
+    uses: pyTooling/Actions/.github/workflows/Release.yml@dev
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - UnitTesting
+      - Coverage
+      - StaticTypeCheck
+
+  Package:
+    uses: pyTooling/Actions/.github/workflows/Package.yml@dev
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - Params
+      - Coverage
+    with:
+      pyver: ${{ fromJson(needs.Params.outputs.params).pyver }}
+      artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.wheel }}
+
+  PublishOnPyPI:
+    uses: pyTooling/Actions/.github/workflows/PublishOnPyPI.yml@dev
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - Params
+      - Release
+      - Package
+    with:
+      pyver: ${{ fromJson(needs.Params.outputs.params).pyver }}
+      artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.wheel }}
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+
+  VerifyDocs:
+    uses: pyTooling/Actions/.github/workflows/VerifyDocs.yml@dev
+    needs:
+      - Params
+    with:
+      pyver: ${{ fromJson(needs.Params.outputs.params).pyver }}
+
+  BuildTheDocs:
+    uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@dev
+    needs:
+      - Params
+      - VerifyDocs
+    with:
+      artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.doc }}
+
+  PublishToGitHubPages:
+    uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@dev
+    needs:
+      - Params
+      - BuildTheDocs
+      - Coverage
+      - StaticTypeCheck
+    with:
+      doc: ${{ fromJson(needs.Params.outputs.params).artifacts.doc }}
+      coverage: ${{ fromJson(needs.Params.outputs.params).artifacts.coverage }}
+      typing: ${{ fromJson(needs.Params.outputs.params).artifacts.typing }}
+
+
+  ArtifactCleanUp:
+    name: 🗑️ Artifact Cleanup
+    runs-on: ubuntu-latest
+    needs:
+      - Params
+      - Coverage
+      - StaticTypeCheck
+      - BuildTheDocs
+      - PublishToGitHubPages
+
+    steps:
+      - name: 🗑️ Delete all Artifacts
+        uses: geekyeggo/delete-artifact@v1
+        with:
+          name: |
+            ${{ fromJson(needs.Params.outputs.params).artifacts.coverage }}
+            ${{ fromJson(needs.Params.outputs.params).artifacts.typing }}
+            ${{ fromJson(needs.Params.outputs.params).artifacts.doc }}