v0.4.7

Append EOL after value in GITHUB_STATE

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  # Maintain GitHub Action runners
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: dev
+    commit-message:
+      prefix: "[Dependabot]"
+    labels:
+      - Dependencies
+    assignees:
+      - Paebbels
+      - Umarcor
+    reviewers:
+      - Paebbels
+      - Umarcor
+    schedule:
+      interval: "daily"    # Checks on Monday trough Friday.

.github/pull_request_template.md

@@ -1,8 +1,16 @@
 # New Features
+ 
 * tbd
 
 # Changes
+
 * tbd
 
 # Bug Fixes
+
+* tbd
+
+----------
+# Related PRs:
+
 * tbd

.github/workflows/ArtifactCleanUp.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -45,12 +45,12 @@ jobs:
 
       - name: 🗑️ Delete package Artifacts
         if: ${{ ! startsWith(github.ref, 'refs/tags') }}
-        uses: geekyeggo/delete-artifact@v1
+        uses: geekyeggo/delete-artifact@v2
         with:
           name: ${{ inputs.package }}
 
       - name: 🗑️ Delete remaining Artifacts
         if: ${{ inputs.remaining != '' }}
-        uses: geekyeggo/delete-artifact@v1
+        uses: geekyeggo/delete-artifact@v2
         with:
           name: ${{ inputs.remaining }}

.github/workflows/BuildTheDocs.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -38,7 +38,7 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 🛳️ Build documentation
         uses: buildthedocs/btd@v0
@@ -46,7 +46,7 @@ jobs:
           skip-deploy: true
 
       - name: 📤 Upload 'documentation' artifacts
-        uses: actions/upload-artifact@master
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ inputs.artifact }}
           path: doc/_build/html

.github/workflows/CoverageCollection.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -35,6 +35,16 @@ on:
         required: false
         default: '-r tests/requirements.txt'
         type: string
+      unittest_directory:
+        description: 'Path to the directory containing unit tests.'
+        required: false
+        default: 'tests/unit'
+        type: string
+      coverage_config:
+        description: 'Path to the .coveragerc file. Use pyproject.toml by default.'
+        required: false
+        default: 'pyproject.toml'
+        type: string
       artifact:
         description: 'Name of the coverage artifact.'
         required: true
@@ -52,45 +62,90 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 🐍 Setup Python ${{ inputs.python_version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ inputs.python_version }}
 
       - name: 🗂 Install dependencies
         run: |
           python -m pip install -U pip
+          python -m pip install tomli
           python -m pip install ${{ inputs.requirements }}
 
+      - name: 🔁 Extract configurations from pyproject.toml
+        id: getVariables
+        shell: python
+        run: |
+          from os import environ
+          from pathlib import Path
+          from tomli   import load as tomli_load
+
+          htmlDirectory = 'htmlcov'
+          xmlFile = './coverage.xml'
+          coverageRC = "${{ inputs.coverage_config }}".strip()
+
+          # Read output paths from 'pyproject.toml' file
+          if coverageRC == "pyproject.toml":
+              pyProjectFile =  Path("pyproject.toml")
+              if pyProjectFile.exists():
+                  with pyProjectFile.open("rb") as file:
+                      pyProjectSettings = tomli_load(file)
+
+                  htmlDirectory = pyProjectSettings["tool"]["coverage"]["html"]["directory"]
+                  xmlFile       = pyProjectSettings["tool"]["coverage"]["xml"]["output"]
+              else:
+                  print(f"File '{pyProjectFile}' not found and no ' .coveragerc' file specified.")
+
+          # Read output paths from '.coveragerc' file
+          elif len(coverageRC) > 0:
+              coverageRCFile = Path(coverageRC)
+              if coverageRCFile.exists():
+                  with coverageRCFile.open("rb") as file:
+                      coverageRCSettings = tomli_load(file)
+
+                  htmlDirectory = coverageRCSettings["html"]["directory"]
+                  xmlFile       = coverageRCSettings["xml"]["output"]
+              else:
+                  print(f"File '{coverageRCFile}' not found.")
+
+          with open(environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as gho:
+              gho.write(f"""\
+          coverage_report_html_directory={htmlDirectory}
+          coverage_report_xml={xmlFile}
+          """)
+          print(f"DEBUG:\n  html={htmlDirectory}\n  xml={xmlFile}")
+
       - name: Collect coverage
         continue-on-error: true
         run: |
-          python -m pytest -rA --cov=.. --cov-config=tests/.coveragerc tests/unit --color=yes
+          [ 'x${{ inputs.coverage_config }}' != 'x' ] && PYCOV_ARGS='--cov-config=${{ inputs.coverage_config }}' || unset PYCOV_ARGS
+          python -m pytest -rA --cov=. $PYCOV_ARGS ${{ inputs.unittest_directory }} --color=yes
 
       - name: Convert to cobertura format
         run: coverage xml
 
       - name: Convert to HTML format
         run: |
-          coverage html
-          rm htmlcov/.gitignore
+          coverage html -d ${{ steps.getVariables.outputs.coverage_report_html_directory }}
+          rm ${{ steps.getVariables.outputs.coverage_report_html_directory }}/.gitignore
 
       - name: 📤 Upload 'Coverage Report' artifact
         continue-on-error: true
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ inputs.artifact }}
-          path: htmlcov
+          path: ${{ steps.getVariables.outputs.coverage_report_html_directory }}
           if-no-files-found: error
           retention-days: 1
 
       - name: 📊 Publish coverage at CodeCov
         continue-on-error: true
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v3
         with:
-          file: ./coverage.xml
+          files: ${{ steps.getVariables.outputs.coverage_report_xml }}
           flags: unittests
           env_vars: PYTHON
 
@@ -99,4 +154,4 @@ jobs:
         uses: codacy/codacy-coverage-reporter-action@master
         with:
           project-token: ${{ secrets.codacy_token }}
-          coverage-reports: ./coverage.xml
+          coverage-reports: ${{ steps.getVariables.outputs.coverage_report_xml }}

.github/workflows/Package.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -48,10 +48,10 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 🐍 Setup Python ${{ inputs.python_version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ inputs.python_version }}
 
@@ -72,23 +72,37 @@ jobs:
         if: inputs.requirements == ''
         run: python -m build --wheel
 
+      # build (not isolated)
+
+      - name: 🔧 [build] Install dependencies for packaging and release
+        if: inputs.requirements == 'no-isolation'
+        run: python -m pip install build
+
+      - name: 🔨 [build] Build Python package (source distribution)
+        if: inputs.requirements == 'no-isolation'
+        run: python -m build --no-isolation --sdist
+
+      - name: 🔨 [build] Build Python package (binary distribution - wheel)
+        if: inputs.requirements == 'no-isolation'
+        run: python -m build --no-isolation --wheel
+
       # setuptools
 
       - name: 🔧 [setuptools] Install dependencies for packaging and release
-        if: inputs.requirements != ''
+        if: inputs.requirements != '' && inputs.requirements != 'no-isolation'
         run: python -m pip install ${{ inputs.requirements }}
 
       - name: 🔨 [setuptools] Build Python package (source distribution)
-        if: inputs.requirements != ''
+        if: inputs.requirements != '' && inputs.requirements != 'no-isolation'
         run: python setup.py sdist
 
       - name: 🔨 [setuptools] Build Python package (binary distribution - wheel)
-        if: inputs.requirements != ''
+        if: inputs.requirements != '' && inputs.requirements != 'no-isolation'
         run: python setup.py bdist_wheel
 
 
       - name: 📤 Upload wheel artifact
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ inputs.artifact }}
           path: dist/

.github/workflows/Parameters.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -33,7 +33,12 @@ on:
       python_version_list:
         description: 'Space separated list of Python versions to run tests with.'
         required: false
-        default: '3.6 3.7 3.8 3.9 3.10'
+        default: '3.7 3.8 3.9 3.10'
+        type: string
+      system_list:
+        description: 'Space separated list of systems to run tests on.'
+        required: false
+        default: 'ubuntu windows msys2 macos'
         type: string
       name:
         description: 'Name of the tool.'
@@ -60,6 +65,8 @@ jobs:
         id: params
         shell: python
         run: |
+          from os import environ
+
           name = '${{ inputs.name }}'
           params = {
             'python_version': '${{ inputs.python_version }}',
@@ -71,21 +78,47 @@ jobs:
               'doc': f'{name}-doc',
             }
           }
-          print(f'::set-output name=params::{params!s}')
+
+          with open(environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as gho:
+              gho.write(f"params={params!s}\n")
           print("Parameters:")
           print(params)
 
+          systems = '${{ inputs.system_list }}'.split(' ')
+          versions = '${{ inputs.python_version_list }}'.split(' ')
+          if '3.6' in versions:
+              print("::warning title=Deprecated::Support for Python 3.6 ended in 2021.12.23.")
+          if '3.11' in versions:
+              print(f"::notice title=Experimental::Python 3.11 (3.11.0-alpha3) is a pre-release.")
           data = {
-             '3.6': { 'icon': '🔴', 'until': '23.12.2021' },
-             '3.7': { 'icon': '🟠', 'until': '27.06.2023' },
-             '3.8': { 'icon': '🟡', 'until': 'Oct. 2024' },
-             '3.9': { 'icon': '🟢', 'until': 'Oct. 2025' },
-            '3.10': { 'icon': '🟢', 'until': 'Oct. 2026' },
+              'python': {
+                  '3.6':  { 'icon': '⚫', 'until': '2021.12.23' },
+                  '3.7':  { 'icon': '🔴', 'until': '2023.06.27' },
+                  '3.8':  { 'icon': '🟠', 'until': '2024.10' },
+                  '3.9':  { 'icon': '🟡', 'until': '2025.10' },
+                  '3.10': { 'icon': '🟢', 'until': '2026.10' },
+                  '3.11': { 'icon': '🟣', 'until': '2027.10' },
+              },
+              'sys': {
+                  'ubuntu':  { 'icon': '🐧', 'runs-on': 'ubuntu-latest',  'shell': 'bash' },
+                  'windows': { 'icon': '🧊', 'runs-on': 'windows-latest', 'shell': 'pwsh' },
+                  'msys2':   { 'icon': '🟦', 'runs-on': 'windows-latest', 'shell': 'msys2 {0}' },
+                  'macos':   { 'icon': '🍎', 'runs-on': 'macos-latest',   'shell': 'bash' }
+              }
           }
           jobs = [
-              {'python': version, 'icon': data[version]['icon']}
-              for version in '${{ inputs.python_version_list }}'.split(' ')
+              {
+                  'sysicon': data['sys'][system]['icon'],
+                  'system': system,
+                  'runs-on': data['sys'][system]['runs-on'],
+                  'shell': data['sys'][system]['shell'],
+                  'pyicon': data['python'][version]['icon'],
+                  'python': '3.11.0-alpha.3' if version == '3.11' else version
+              }
+              for system in systems
+              for version in (versions if system != 'msys2' else ['3.10'])
           ]
-          print(f'::set-output name=python_jobs::{jobs!s}')
+          with open(environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as gho:
+              gho.write(f"python_jobs={jobs!s}\n")
           print("Python jobs:")
           print(jobs)

.github/workflows/PublishOnPyPI.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -52,13 +52,13 @@ jobs:
 
     steps:
       - name: 📥 Download artifacts '${{ inputs.artifact }}' from 'Package' job
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v3
         with:
           name: ${{ inputs.artifact }}
           path: dist/
 
       - name: 🐍 Setup Python ${{ inputs.python_version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ inputs.python_version }}
 

.github/workflows/PublishTestResults.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -39,10 +39,10 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Download Artifacts
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v3
         with:
           path: artifacts
 

.github/workflows/PublishToGitHubPages.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -48,24 +48,24 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 📥 Download artifacts '${{ inputs.doc }}' from 'BuildTheDocs' job
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v3
         with:
           name: ${{ inputs.doc }}
           path: public
 
       - name: 📥 Download artifacts '${{ inputs.coverage }}' from 'Coverage' job
         if: ${{ inputs.coverage != '' }}
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v3
         with:
           name: ${{ inputs.coverage }}
           path: public/coverage
 
       - name: 📥 Download artifacts '${{ inputs.typing }}' from 'StaticTypeCheck' job
         if: ${{ inputs.typing != '' }}
-        uses: actions/download-artifact@v2
+        uses: actions/download-artifact@v3
         with:
           name: ${{ inputs.typing }}
           path: public/typing

.github/workflows/Release.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -39,9 +39,11 @@ jobs:
           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}
+          cat >> "$GITHUB_OUTPUT" << EOF
+          gitTag=${GIT_TAG}
+          version=${RELEASE_VERSION}
+          datetime=${RELEASE_DATETIME}
+          EOF
 
       - name: 📑 Create Release Page
         id: createReleasePage

.github/workflows/StaticTypeCheck.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -57,10 +57,10 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 🐍 Setup Python ${{ inputs.python_version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ inputs.python_version }}
 
@@ -76,7 +76,7 @@ jobs:
       - name: 📤 Upload 'Static Typing Report' artifact
         if: ${{ inputs.artifact != '' }}
         continue-on-error: true
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: ${{ inputs.artifact }}
           path: ${{ inputs.report }}

.github/workflows/TestReleaser.yml

@@ -3,7 +3,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -45,7 +45,7 @@ jobs:
     env:
       DOCKER_BUILDKIT: 1
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - name: Build container image
       run: docker build -t ghcr.io/pytooling/releaser -f releaser/Dockerfile releaser
@@ -62,7 +62,7 @@ jobs:
   Composite:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - run: echo "Build some tool and generate some (versioned) artifacts" > artifact-$(date -u +"%Y-%m-%dT%H-%M-%SZ").txt
 
@@ -122,7 +122,7 @@ jobs:
       - Composite
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - run: echo "Build some tool and generate some (versioned) artifacts" > artifact-$(date -u +"%Y-%m-%dT%H-%M-%SZ").txt
 

.github/workflows/UnitTesting.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -26,7 +26,7 @@ on:
   workflow_call:
     inputs:
       jobs:
-        description: 'JSON list with field <python>, telling the versions to run tests with.'
+        description: 'JSON list with environment fields, telling the system and Python versions to run tests with.'
         required: true
         type: string
       requirements:
@@ -34,6 +34,25 @@ on:
         required: false
         default: '-r tests/requirements.txt'
         type: string
+      pacboy:
+        description: 'MSYS2 dependencies to be installed through pacboy (pacman).'
+        required: false
+        default: >-
+            python-pip:p
+            python-wheel:p
+            python-coverage:p
+            python-lxml:p
+        type: string
+      mingw_requirements:
+        description: 'Override Python dependencies to be installed through pip on MSYS2 (MINGW64) only.'
+        required: false
+        default: ''
+        type: string
+      unittest_directory:
+        description: 'Path to the directory containing unit tests.'
+        required: false
+        default: 'tests/unit'
+        type: string
       artifact:
         description: "Generate unit test report with junitxml and upload results as an artifact."
         required: false
@@ -43,38 +62,71 @@ on:
 jobs:
 
   UnitTesting:
-    name: ${{ matrix.icon }} Unit Tests using Python ${{ matrix.python }}
-    runs-on: ubuntu-latest
+    name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }}
+    runs-on: ${{ matrix.runs-on }}
 
     strategy:
       fail-fast: false
       matrix:
         include: ${{ fromJson(inputs.jobs) }}
 
+    defaults:
+      run:
+        shell: ${{ matrix.shell }}
+
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
+
+      - name: '🟦 Setup MSYS2'
+        if: matrix.system == 'msys2'
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          update: true
+          pacboy: ${{ inputs.pacboy }}
 
       - name: 🐍 Setup Python ${{ matrix.python }}
-        uses: actions/setup-python@v2
+        if: matrix.system != 'msys2'
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
 
-      - name: 🔧 Install dependencies
+      - name: ⚙️ Update pip
+        run: python -m pip install -U pip
+
+      - name: 🔧 Install wheel and pip dependencies
+        if: matrix.system != 'msys2'
         run: |
-          python -m pip install -U pip
+          python -m pip install -U wheel
           python -m pip install ${{ inputs.requirements }}
 
+      - name: 🔧 Install pip dependencies
+        if: matrix.system == 'msys2'
+        run: |
+          if [ 'x${{ inputs.mingw_requirements }}' != 'x' ]; then
+            python -m pip install ${{ inputs.mingw_requirements }}
+          else
+            python -m pip install ${{ inputs.requirements }}
+          fi
+
       - name: ☑ Run unit tests
+        if: matrix.system == 'windows'
+        run: |
+          $PYTEST_ARGS = if ("${{ inputs.artifact }}".length -gt 0) { "--junitxml=TestReport.xml" } else { "" }
+          python -m pytest -rA ${{ inputs.unittest_directory }} $PYTEST_ARGS --color=yes
+
+      - name: ☑ Run unit tests
+        if: matrix.system != 'windows'
         run: |
           [ 'x${{ inputs.artifact }}' != 'x' ] && PYTEST_ARGS='--junitxml=TestReport.xml' || unset PYTEST_ARGS
-          python -m pytest -rA tests/unit $PYTEST_ARGS --color=yes
+          python -m pytest -rA ${{ inputs.unittest_directory }} $PYTEST_ARGS --color=yes
 
       - name: 📤 Upload 'TestReport.xml' artifact
         if: inputs.artifact != ''
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
-          name: ${{ inputs.artifact }}-${{ matrix.python }}
+          name: ${{ inputs.artifact }}-${{ matrix.system }}-${{ matrix.python }}
           path: TestReport.xml
           if-no-files-found: error
           retention-days: 1

.github/workflows/VerifyDocs.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -39,10 +39,10 @@ jobs:
 
     steps:
       - name: ⏬ Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: 🐍 Setup Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ inputs.python_version }}
 

.idea/Actions.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/Actions.iml" filepath="$PROJECT_DIR$/.idea/Actions.iml" />
+    </modules>
+  </component>
+</project>

ExamplePipeline.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -34,6 +34,7 @@ jobs:
     with:
       name: ToolName
       # Optional
+      system_list: 'ubuntu windows msys2 macos'
       python_version: '3.10'
       python_version_list: '3.8 3.9 3.10'
 
@@ -45,6 +46,13 @@ jobs:
       jobs: ${{ needs.Params.outputs.python_jobs }}
       # Optional
       requirements: '-r tests/requirements.txt'
+      pacboy: >-
+        python-pip:p
+        python-wheel:p
+        python-coverage:p
+        python-lxml:p
+      mingw_requirements: '-r tests/requirements.mingw.txt'
+      unittest_directory: 'tests/unit'
       artifact: ${{ fromJson(needs.Params.outputs.params).artifacts.unittesting }}
 
   Coverage:
@@ -148,7 +156,7 @@ jobs:
     uses: pyTooling/Actions/.github/workflows/ArtifactCleanUp.yml@main
     needs:
       - Params
-      - UnitTesting
+      - PublishTestResults
       - Coverage
       - StaticTypeCheck
       - BuildTheDocs

README.md

@@ -7,24 +7,30 @@ 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.
 
+
 ## Context
 
-GitHub Actions supports four types of reusable code:
+GitHub Actions supports five procedures to reuse code:
 
-- JavaScript Action.
+- JavaScript Action:
   - [docs.github.com: actions/creating-actions/creating-a-javascript-action](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action)
-- Container Action.
+- Container Action:
   - [docs.github.com: actions/creating-actions/creating-a-docker-container-action](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action)
-- Composite Action.
+- Container Step:
+  - [docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-a-docker-public-registry-action](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#example-using-a-docker-public-registry-action)
+  - [docs.github.com: actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepswithargs)
+- Composite Action:
   - [docs.github.com: actions/creating-actions/creating-a-composite-action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action)
   - [github.blog/changelog: 2020-08-07-github-actions-composite-run-steps](https://github.blog/changelog/2020-08-07-github-actions-composite-run-steps/)
   - [github.blog/changelog: 2021-08-25-github-actions-reduce-duplication-with-action-compositio](https://github.blog/changelog/2021-08-25-github-actions-reduce-duplication-with-action-composition/)
-- Reusable Workflows.
+- Reusable Workflow:
   - [docs.github.com: actions/learn-github-actions/reusing-workflows](https://docs.github.com/en/actions/learn-github-actions/reusing-workflows)
   - [github.blog/changelog: 2021-10-05-github-actions-dry-your-github-actions-configuration-by-reusing-workflows](https://github.blog/changelog/2021-10-05-github-actions-dry-your-github-actions-configuration-by-reusing-workflows/)
 
-Leaving JavaScript and Container Actions aside, the main differences between Composite Actions and Reusable Workflows
-are the following:
+Container Actions and Container Steps are almost equivalent: Actions use a configuration file (`action.yml`), while
+Steps do not.
+Leaving JavaScript and Container Actions and Steps aside, the main differences between Composite Actions and Reusable
+Workflows are the following:
 
 - Composite Actions can be executed from a remote/external path or from the checked out branch, and from any location.
   However, Reusable Workflows can only be used through a remote/external path (`{owner}/{repo}/{path}/{filename}@{ref}`),
@@ -74,6 +80,7 @@ It allows using the `post` feature with scripts written in bash, python or any o
 the environment.
 See: [actions/runner#1478](https://github.com/actions/runner/issues/1478).
 
+
 ## Reusable workflows
 
 This repository provides 10+ Reusable Workflows based on the CI pipelines of the repos in this organisation,
@@ -81,20 +88,25 @@ This repository provides 10+ Reusable Workflows based on the CI pipelines of the
 By combining them, Python packages can be continuously tested and released along with Sphinx documentation sites, to GitHub Releases, GitHub Pages and PyPI.
 Optionally, coverage and static type check reports can be gathered.
 
-[![](ExamplePipeline.png)](ExamplePipeline.png)
+[![](ExamplePipeline_dark.png)](ExamplePipeline_dark.png)
 
-As shown in the screenshot above, the expected order is:
+[![](ExamplePipeline_light.png)](ExamplePipeline_light.png)
+
+As shown in the screenshots above, the expected order is:
 
 - Global:
   - [Parameters](.github/workflows/Parameters.yml): a workaround for the limitations to handle global variables in
     GitHub Actions workflows (see [actions/runner#480](https://github.com/actions/runner/issues/480)).
-    It generates outputs with artifact names and job matrices to be used in other jobs.
+    It generates outputs with artifact names and job matrices to be used in later running jobs.
 - Code testing/analysis:
   - [UnitTesting](.github/workflows/UnitTesting.yml): run unit test with `pytest` using multiple versions of Python, and
-    optionally upload results as XML reports.
-  - [CoverageCollection](.github/workflows/CoverageCollection.yml): collect coverage data with `pytest` using a single
-    version of Python, generate HTML and Cobertura (XML) reports, upload the HTML report as an artifact, and upload the
-    results to Codecov and Codacy.
+    optionally upload results as XML reports. Configuration options to `pytest` should be given via section
+   `[tool.pytest.ini_options]` in a `pyproject.toml` file.
+  - [CoverageCollection](.github/workflows/CoverageCollection.yml): collect code coverage data (incl. branch coverage)
+    with `pytest`/`pytest-cov`/`coverage.py` using a single version of Python (latest). It generates HTML and Cobertura
+    (XML)reports, upload the HTML report as an artifact, and upload the test results to Codecov and Codacy. Configuration
+    options to `pytest` and `coverage.py` should be given via section `[tool.pytest.ini_options]` and `[tool.coverage.*]`
+    in a `pyproject.toml` file.
   - [StaticTypeCheck](.github/workflows/StaticTypeCheck.yml): collect static type check result with `mypy`, and
     optionally upload results as an HTML report.
     Example `commands`:
@@ -121,7 +133,7 @@ As shown in the screenshot above, the expected order is:
         mypy --html-report ../htmlmypy -p ToolName
       ```
 
-  - [VerifyDocs](.github/workflows/VerifyDocs.yml): extract code examples from the README and test.
+  - [VerifyDocs](.github/workflows/VerifyDocs.yml): extract code examples from the README and test these code snippets.
 - Packaging and releasing:
   - [Release](.github/workflows/Release.yml): publish GitHub Release.
   - [Package](.github/workflows/Package.yml): generate source and wheel packages, and upload them as an artifact.
@@ -150,19 +162,23 @@ Find further usage cases in the following list of projects:
 - [VHDL/pyVHDLModel](https://github.com/VHDL/pyVHDLModel/tree/main/.github/workflows)
 
 
+## References
+
+- [hdl/containers#48](https://github.com/hdl/containers/issues/48)
+
+
 ## Contributors
 
 * [Patrick Lehmann](https://GitHub.com/Paebbels)
 * [Unai Martinez-Corral](https://GitHub.com/umarcor) (Maintainer)
-* [and more...](https://GitHub.com/pyTooling/Actions/graphs/contributors) 
+* [and more...](https://GitHub.com/pyTooling/Actions/graphs/contributors)
 
 
 ## License
 
-This Python package (source code) licensed under [Apache License 2.0](LICENSE.md).  
+This Python package (source code) licensed under [Apache License 2.0](LICENSE.md).
 The accompanying documentation is licensed under [Creative Commons - Attribution 4.0 (CC-BY 4.0)](doc/Doc-License.rst).
 
+---
 
--------------------------
-
-SPDX-License-Identifier: Apache-2.0
+SPDX-License-Identifier: Apache-2.0

releaser/DEVELOPMENT.md

@@ -0,0 +1,8 @@
+# Releaser Development
+
+- [pyTooling/pyAttributes](https://github.com/pyTooling/pyAttributes) or
+  [willmcgugan/rich](https://github.com/willmcgugan/rich) might be used to enhance the UX.
+
+- It might be desirable to have pyTooling.Version.SemVersion handle the regular expression from
+  [semver.org](https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string), and use
+  proper Python classes in **Releaser**.

releaser/README.md

@@ -48,6 +48,20 @@ as assets.
 In this context, one of the main use cases of **Releaser** is pushing artifacts as release assets.
 Thus, the name of the Action.
 
+GitHub provides an official CLI tool, written in golang: [cli/cli](https://github.com/cli/cli).
+When the Python version of **Releaser** was written, `cli` was evaluated as an alternative to *PyGitHub*.
+`gh release` was (and still is) not flexible enough to update the reference of a release, without deleting and
+recreating it (see [cli.github.com: manual/gh_release_create](https://cli.github.com/manual/gh_release_create)).
+Deletion and recreation is unfortunate, because it notifies all the watchers of a repository
+(see [eine/tip#111](https://github.com/eine/tip/issues/111)).
+However, [cli.github.com: manual/gh_release_upload](https://cli.github.com/manual/gh_release_upload) handles uploading
+artifacts as assets faster and with better stability for larger files than *PyGitHub*
+(see [msys2/msys2-installer#36](https://github.com/msys2/msys2-installer/pull/36)).
+Furthermore, the GitHub CLI is installed on GitHub Actions' default virtual environments.
+Although `gh` does not support login through SSH (see [cli/cli#3715](https://github.com/cli/cli/issues/3715)), on GitHub
+Actions a token is available `${{ github.token }}`.
+Therefore, **Releaser** uses `gh release upload` internally.
+
 ## Usage
 
 The following block shows a minimal YAML workflow file:

releaser/action.yml

@@ -3,7 +3,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #

releaser/composite/action.yml

@@ -3,7 +3,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -48,7 +48,7 @@ runs:
     run: pip install PyGithub --progress-bar off
 
   - shell: bash
-    run: ${{ github.action_path }}/../releaser.py
+    run: '''${{ github.action_path }}/../releaser.py'''
     env:
       INPUT_TOKEN: ${{ inputs.token }}
       INPUT_FILES: ${{ inputs.files }}

releaser/releaser.py

@@ -5,7 +5,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -52,7 +52,7 @@ def GetListOfArtifacts(argv, files):
     if len(argv) > 1:
         args += argv[1:]
     if len(args) == 1 and args[0].lower() == "none":
-        print("! Skipping 'files' because it's set to 'none")
+        print("! Skipping 'files' because it's set to 'none'.")
         return []
     elif len(args) == 0:
         stdout.flush()
@@ -63,14 +63,14 @@ def GetListOfArtifacts(argv, files):
             print(f"  glob({item!s}):")
             for fname in [fname for fname in glob(item, recursive=True) if not Path(fname).is_dir()]:
                 if Path(fname).stat().st_size == 0:
-                    print(f"  - ! Skipping empty file {fname!s}")
+                    print(f"  - ! Skipping empty file {fname!s}.")
                     continue
                 print(f"  - {fname!s}")
                 flist.append(fname)
         if len(flist) < 1:
             stdout.flush()
             raise (Exception("Empty list of files to upload/update!"))
-        return flist
+        return sorted(flist)
 
 
 def GetGitHubAPIHandler(token):
@@ -101,7 +101,7 @@ def CheckRefSemVer(gh_ref, tag, snapshots):
                     return (tag, env_tag, False)
                 elif snapshots:
                     # is semver compilant prerelease tag, thus a snapshot (we skip it)
-                    print("! Skipping snapshot prerelease")
+                    print("! Skipping snapshot prerelease.")
                     sys_exit()
 
     return (tag, env_tag, True)
@@ -179,12 +179,15 @@ if paramRM:
         asset.delete_asset()
 stdout.flush()
 
-print("· Cleanup and/or upload artifacts")
-env = environ.copy()
-env["GITHUB_TOKEN"] = paramToken
-cmd = ["gh", "release", "upload", "--repo", paramRepo, "--clobber", tag] + files
-print(f" > {' '.join(cmd)}")
-check_call(cmd, env=env)
-stdout.flush()
+if len(files) > 0:
+    print("· Upload assets")
+    env = environ.copy()
+    env["GITHUB_TOKEN"] = paramToken
+    cmd = ["gh", "release", "upload", "--repo", paramRepo, "--clobber", tag] + files
+    print(f" > {' '.join(cmd)}")
+    check_call(cmd, env=env)
+    stdout.flush()
+else:
+    print("! Skipping uploading assets because the file list is empty.")
 
 UpdateReference(gh_release, tag, paramSHA if env_tag is None else None, is_prerelease, is_draft)

with-post-step/action.yml

@@ -4,7 +4,7 @@
 #   Unai Martinez-Corral                                                                                               #
 #                                                                                                                      #
 # ==================================================================================================================== #
-# Copyright 2020-2021 The pyTooling Authors                                                                            #
+# Copyright 2020-2022 The pyTooling Authors                                                                            #
 #                                                                                                                      #
 # Licensed under the Apache License, Version 2.0 (the "License");                                                      #
 # you may not use this file except in compliance with the License.                                                     #
@@ -37,6 +37,6 @@ inputs:
     default: POST
 
 runs:
-  using: 'node12'
+  using: 'node20'
   main: 'main.js'
   post: 'main.js'

with-post-step/main.js

@@ -3,7 +3,8 @@
  *   Unai Martinez-Corral                                                                                             *
  *                                                                                                                    *
  * ================================================================================================================== *
- * Copyright 2021 Unai Martinez-Corral <unai.martinezcorral@ehu.eus>                                                  *
+ * Copyright 2021-2022 Unai Martinez-Corral <unai.martinezcorral@ehu.eus>                                             *
+ * Copyright 2022 Unai Martinez-Corral <umartinezcorral@antmicro.com>                                                 *
  *                                                                                                                    *
  * Licensed under the Apache License, Version 2.0 (the "License");                                                    *
  * you may not use this file except in compliance with the License.                                                   *
@@ -24,16 +25,14 @@
  * * https://github.com/docker/login-action/issues/72                                                                 *
  * * https://github.com/actions/runner/issues/1478                                                                    *
  * ================================================================================================================== */
-const { exec } = require("child_process");
+const { spawn } = require("child_process");
+const { appendFileSync } = require("fs");
+const { EOL } = require("os");
 
 function run(cmd) {
-  exec(cmd, (error, stdout, stderr) => {
-    if ( stdout.length !== 0 ) { console.log(`${stdout}`); }
-    if ( stderr.length !== 0 ) { console.error(`${stderr}`); }
-    if (error) {
-      process.exitCode = error.code;
-      console.error(`${error}`);
-    }
+  const subprocess = spawn(cmd, { stdio: "inherit", shell: true });
+  subprocess.on("exit", (exitCode) => {
+    process.exitCode = exitCode;
   });
 }
 
@@ -42,6 +41,6 @@ const key = process.env.INPUT_KEY.toUpperCase();
 if ( process.env[`STATE_${key}`] !== undefined ) { // Are we in the 'post' step?
   run(process.env.INPUT_POST);
 } else { // Otherwise, this is the main step
-  console.log(`::save-state name=${key}::true`);
+  appendFileSync(process.env.GITHUB_STATE, `${key}=true${EOL}`);
   run(process.env.INPUT_MAIN);
 }