pyTooling/Actions
1
0
Fork 0
mirror of https://github.com/pyTooling/Actions.git synced 2026-02-12 02:56:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Reworked Parameters.

Browse Source
This commit is contained in:
Patrick Lehmann
2025-08-23 15:09:26 +02:00
parent 13e42615b2
commit 99c3752847
5 changed files with 600 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/JobTemplate/AllInOne/CompletePipeline.rst
View File

@@ -401,7 +401,8 @@ unittest_python_version_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``'3.9 3.10 3.11 3.12 3.13'`` :Default Value: ``'3.9 3.10 3.11 3.12 3.13'``
:Possible Values: A space separated list of valid Python versions conforming to the pattern ``major.minor``. :Possible Values: A space separated list of valid Python versions conforming to the pattern ``<major>.<minor>`` or
``pypy-<major>.<minor>``.
:Description: The list of space-separated Python versions used for unit testing. :Description: The list of space-separated Python versions used for unit testing.
.. include:: ../PythonVersionList.rst .. include:: ../PythonVersionList.rst
@@ -429,7 +430,7 @@ unittest_include_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:
@@ -441,7 +442,7 @@ unittest_exclude_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:
@@ -453,7 +454,7 @@ unittest_disable_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:
@@ -483,7 +484,8 @@ apptest_python_version_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of valid Python versions conforming to the pattern ``major.minor``. :Possible Values: A space separated list of valid Python versions conforming to the pattern ``<major>.<minor>`` or
``pypy-<major>.<minor>```.
:Description: The list of space-separated Python versions used for application testing. :Description: The list of space-separated Python versions used for application testing.
As this list is empty by default, the value is derived from As this list is empty by default, the value is derived from
@@ -514,7 +516,7 @@ apptest_include_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:
@@ -526,7 +528,7 @@ apptest_exclude_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:
@@ -538,7 +540,7 @@ apptest_disable_list
:Type: string :Type: string
:Required: no :Required: no
:Default Value: ``''`` :Default Value: ``''``
:Possible Values: A space separated list of ``system:python_version`` tuples. :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
:Description: :Description:

3
doc/JobTemplate/Setup/ExtractConfiguration.rst
View File

@@ -10,7 +10,8 @@ The ``ExtractConfiguration`` job template is a .....
.. topic:: Features .. topic:: Features
* Concatenate :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` and :ref:`JOBTMPL/ExtractConfiguration/Input/package_name` * Concatenate :ref:`JOBTMPL/ExtractConfiguration/Input/package_namespace` and :ref:`JOBTMPL/ExtractConfiguration/Input/package_name`
to :ref:`JOBTMPL/ExtractConfiguration/Output/package_fullname` and :ref:`JOBTMPL/ExtractConfiguration/Output/package_directory`. to :ref:`JOBTMPL/ExtractConfiguration/Output/package_fullname` (with dot) and :ref:`JOBTMPL/ExtractConfiguration/Output/package_directory`
(with slash).
* Provide commands to prepare the source code directory structure suitable for mypy. * Provide commands to prepare the source code directory structure suitable for mypy.
* Extract the unittest XML report file (pytest JUnit XML) as directory name, filename and full path from :file:`pyproject.toml`. * Extract the unittest XML report file (pytest JUnit XML) as directory name, filename and full path from :file:`pyproject.toml`.
* Extract the merged unittest XML report file as directory name, filename and full path from :file:`pyproject.toml`. * Extract the merged unittest XML report file as directory name, filename and full path from :file:`pyproject.toml`.

708
doc/JobTemplate/Setup/Parameters.rst
View File

@@ -4,17 +4,27 @@ Parameters
########## ##########
The ``Parameters`` job template is a workaround for the limitations of GitHub Actions to handle global variables in The ``Parameters`` job template is a workaround for the limitations of GitHub Actions to handle global variables in
GitHub Actions workflows (see `actions/runner#480 <https://github.com/actions/runner/issues/480>`__. GitHub Actions workflows (see `actions/runner#480 <https://github.com/actions/runner/issues/480>`__).
It generates output parameters with artifact names and a job matrix to be used in later running jobs. It generates output parameters with artifact names and a job matrix to be used in later running jobs.
**Behavior:** .. topic:: Features
.. todo:: Parameters:Behavior Needs documentation. * Generate names for various artifacts.
* Generate a matrix of job combinations made from systems, Python versions and environments as a JSON string.
* Provide a (default) Python version for other jobs.
**Dependencies:** .. topic:: Job Execution
*None* .. image:: ../../_static/pyTooling-Actions-Parameters.png
:width: 1000px
.. topic:: Dependencies
* Python from base-system.
.. _JOBTMPL/Parameters/Instantiation:
Instantiation Instantiation
************* *************
@@ -22,10 +32,18 @@ Instantiation
Simple Example Simple Example
============== ==============
The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only .. grid:: 2
requires a `name` parameter to create the artifact names.
.. code-block:: yaml .. grid-item::
:columns: 5
The following instantiation example creates a job ``Params`` derived from job template ``Parameters`` version
``@r5``. It only requires a :ref:`JOBTMPL/Parameters/Input/package_name` parameter to create the artifact names.
.. grid-item::
:columns: 7
.. code-block:: yaml
name: Pipeline name: Pipeline
@@ -37,208 +55,500 @@ requires a `name` parameter to create the artifact names.
Params: Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with: with:
name: pyTooling package_name: myPackage
UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- Params
with:
jobs: ${{ needs.Params.outputs.python_jobs }}
Complex Example Complex Example
=============== ===============
The following instantiation example creates 3 jobs from the same template, but with differing input parameters. The .. grid:: 2
first job `UnitTestingParams` might be used to create a job matrix of unit tests. It creates the cross of default
systems (Windows, Ubuntu, macOS, MinGW64, UCRT64) and the given list of Python versions including some mypy versions. In
addition a list of excludes (marked as :deletion:`deletions`) and includes (marked as :addition:`additions`) is handed
over resulting in the following combinations:
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ .. grid-item::
| Version | 3.8 🔴 | 3.9 🟠 | 3.10 🟡 | 3.11 🟢 | 3.12 🟢 | 3.13.a1 🟣 | pypy-3.8 🔴 | pypy-3.9 🟠 | pypy-3.10 🟡 | :columns: 5
+============+=============+=============+==============+==============+=========================+============+=============+==============================+===============================+
| Windows 🧊 | windows:3.8 | windows:3.9 | windows:3.10 | windows:3.11 | | | | :deletion:`windows:pypy-3.9` | :deletion:`windows:pypy-3.10` |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| Ubuntu 🐧 | ubuntu:3.8 | ubuntu:3.9 | ubuntu:3.10 | ubuntu:3.11 | :addition:`ubuntu:3.12` | | | ubuntu:pypy-3.9 | ubuntu:pypy-3.10 |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| macOS 🍎 | macos:3.8 | macos:3.9 | macos:3.10 | macos:3.11 | :addition:`macos:3.12` | | | macos:pypy-3.9 | macos:pypy-3.10 |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| MSYS 🟪 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| MinGW32 ⬛ | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| MinGW64 🟦 | | | | mingw64:3.11 | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| Clang32 🟫 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| Clang64 🟧 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| UCRT64 🟨 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
The following instantiation example creates 3 jobs from the same template, but with differing input parameters.
.. code-block:: yaml The first job ``UnitTestingParams`` might be used to create a job matrix of unit tests. It creates the cross of
default systems (Windows, Ubuntu, macOS, macOS-ARM, MinGW64, UCRT64) and the given list of Python versions
including some mypy versions. In addition a list of excludes (marked as :deletion:`deletions`) and includes
(marked as :addition:`additions`) is handed over resulting in the following combinations.
name: Pipeline The second job ``PerformanceTestingParams`` might be used to create a job matrix for performance tests. Here a
pipeline might be limited to the latest two Python versions on a selected list of platforms.
on: The third job ``PlatformTestingParams`` might be used to create a job matrix for platform compatibility tests.
push: Here a pipeline might be limited to the latest Python version, but all available platforms.
workflow_dispatch:
.. grid-item::
:columns: 7
.. code-block:: yaml
jobs: jobs:
UnitTestingParams: UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with: with:
name: pyTooling package_namespace: myFramework
python_version_list: "3.8 3.9 3.10 3.11 pypy-3.9 pypy-3.10" package_name: Extension
include_list: "ubuntu:3.12 macos:3.12" python_version_list: '3.9 3.10 3.11 3.12 pypy-3.10 pypy-3.11'
exclude_list: "windows:pypy-3.9 windows:pypy-3.10" system_list: 'ubuntu windows macos macos-arm mingw64 ucrt64'
include_list: 'ubuntu:3.13 macos:3.13 macos-arm:3.13'
exclude_list: 'windows:pypy-3.10 windows:pypy-3.11'
PerformanceTestingParams: PerformanceTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with: with:
name: pyTooling package_namespace: myFramework
python_version_list: "3.11 3.12" package_name: Extension
system_list: "ubuntu windows macos" python_version_list: '3.12 3.13'
system_list: 'ubuntu windows macos macos-arm'
PlatformTestingParams: PlatformTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with: with:
name: pyTooling package_namespace: myFramework
python_version_list: "3.12" package_name: Extension
system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64" python_version_list: '3.13'
system_list: 'ubuntu windows macos macos-arm mingw32 mingw64 clang64 ucrt64'
Parameters +--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
********** | Version | 3.9 🔴 | 3.10 🟠 | 3.11 🟡 | 3.12 🟢 | 3.13 🟢 | 3.14.b1 🟣 | pypy-3.9 🔴 | pypy-3.10 🟠 | pypy-3.11 🟡 |
+================================+================+=================+=================+=================+============================+============+=============+===============================+===============================+
| Ubuntu 🐧 | ubuntu:3.9 | ubuntu:3.10 | ubuntu:3.11 | ubuntu:3.12 | :addition:`ubuntu:3.13` | | | ubuntu:pypy-3.10 | ubuntu:pypy-3.11 |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| macOS (x86-64) 🍎 | macos:3.9 | macos:3.10 | macos:3.11 | macos:3.12 | :addition:`macos:3.13` | | | macos:pypy-3.10 | macos:pypy-3.11 |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| macOS (aarch64) 🍏 | macos-arm:3.9 | macos-arm:3.10 | macos-arm:3.11 | macos-arm:3.12 | :addition:`macos-arm:3.13` | | | macos:pypy-3.10 | macos:pypy-3.11 |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 | windows:3.9 | windows:3.10 | windows:3.11 | windows:3.12 | | | | :deletion:`windows:pypy-3.10` | :deletion:`windows:pypy-3.11` |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + MSYS 🟪 | | | | | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + MinGW32 ⬛ | | | | | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + MinGW64 🟦 | | | | mingw64:3.12 | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + Clang32 🟫 | | | | | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + Clang64 🟧 | | | | | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| Windows Server 🪟 + UCRT64 🟨 | | | | ucrt64:3.12 | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
.. _JOBTMPL/Parameters/Parameters:
Parameter Summary
*****************
.. rubric:: Goto :ref:`input parameters <JOBTMPL/Parameters/Inputs>`
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| Parameter Name | Required | Type | Default |
+=====================================================================+==========+==========+===================================================================+
| :ref:`JOBTMPL/Parameters/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/name` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/package_namespace` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/package_name` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/python_version` | no | string | ``'3.13'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/python_version_list` | no | string | ``'3.9 3.10 3.11 3.12 3.13'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/system_list` | no | string | ``'ubuntu windows macos macos-arm mingw64 ucrt64'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/include_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/exclude_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/disable_list` | no | string | ``''`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/ubuntu_image` | no | string | ``'ubuntu-24.04'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/ubuntu_arm_image` | no | string | ``'ubuntu-24.04-arm'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/windows_image` | no | string | ``'windows-2025'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/windows_arm_image` | no | string | ``'windows-11-arm'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/macos_intel_image` | no | string | ``'macos-13'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/macos_arm_image` | no | string | ``'macos-14'`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Input/pipeline-delay` | no | number | ``0`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
.. rubric:: Goto Goto :ref:`secrets <JOBTMPL/Parameters/Secrets>`
This job template needs no secrets.
.. rubric:: Goto Goto :ref:`output parameters <JOBTMPL/Parameters/Outputs>`
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| Result Name | Type | Description |
+=====================================================================+==========+===================================================================+
| :ref:`JOBTMPL/Parameters/Output/python_version` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/python_jobs` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/artifact_names` | string | |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
| :ref:`JOBTMPL/Parameters/Output/params` | string | **deprecated** |
+---------------------------------------------------------------------+----------+-------------------------------------------------------------------+
.. _JOBTMPL/Parameters/Inputs:
Input Parameters
****************
.. _JOBTMPL/Parameters/Input/ubuntu_image_version:
ubuntu_image_version
====================
:Type: string
:Required: no
:Default Value: ``'24.04'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
for available Ubuntu image versions.
:Description: Version of the Ubuntu image used to run this job.
.. note::
Unfortunately, GitHub Actions has only a `limited set of functions <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#functions>`__,
thus, the usual Ubuntu image name like ``'ubuntu-24.04'`` can't be split into image name and image
version.
.. _JOBTMPL/Parameters/Input/name:
name name
==== ====
+----------------+----------+----------+--------------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+==============+ :Default Value: ``''``
| name | yes | string | — — — — | :Possible Values: Any valid artifact name.
+----------------+----------+----------+--------------+ :Description: Prefix used to generate artifact names. Usually, the name of the Python package. |br|
In case this parameter is n empty string, the artifact prefix is derived from :ref:`JOBTMPL/Parameters/Input/package_name`
if the package is a simple Python package, **or** from :ref:`JOBTMPL/Parameters/Input/package_namespace`
and :ref:`JOBTMPL/Parameters/Input/package_name`, if the package is a Python namespace package.
The name of the library or package.
It's used to create artifact names. .. _JOBTMPL/Parameters/Input/package_namespace:
package_namespace
=================
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid Python namespace.
:Description: In case the package is a Python namespace package, the name of the library's or package's namespace
needs to be specified using this parameter. |br|
In case of a simple Python package, this parameter must be specified as an empty string (``''``),
which is the default. |br|
This parameter is used to derive :ref:`JOBTMPL/Parameters/Input/name`, if it's an empty string.
:Example:
.. grid:: 2
.. grid-item::
:columns: 5
.. rubric:: Example Instantiation
.. code-block:: yaml
name: Pipeline
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_namespace: myFramework
package_name: Extension
.. grid-item::
:columns: 4
.. rubric:: Example Directory Structure
.. code-block::
📂ProjectRoot/
📂myFramework/
📂Extension/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. _JOBTMPL/Parameters/Input/package_name:
package_name
============
:Type: string
:Required: no
:Default Value: ``''``
:Possible Values: Any valid Python package name.
:Description: In case of a simple Python package, this package's name is specified using this parameter. |br|
In case the package is a Python namespace package, the parameter
:ref:`JOBTMPL/Parameters/Input/package_namespace` must be specified, too. |br|
This parameter is used to derive :ref:`JOBTMPL/Parameters/Input/name`, if it's an empty string.
:Example:
.. grid:: 2
.. grid-item::
:columns: 5
.. rubric:: Example Instantiation
.. code-block:: yaml
name: Pipeline
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
.. grid-item::
:columns: 4
.. rubric:: Example Directory Structure
.. code-block::
📂ProjectRoot/
📂myFramework/
📦SubPackage/
🐍__init__.py
🐍SubModuleA.py
🐍__init__.py
🐍ModuleB.py
.. _JOBTMPL/Parameters/Input/python_version:
python_version python_version
============== ==============
+----------------+----------+----------+----------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+==========+ :Default Value: ``'3.13'``
| python_version | optional | string | ``3.12`` | :Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``. |br|
+----------------+----------+----------+----------+ See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
:Description: Python version used as default for other jobs requiring a single Python version. |br|
In case :ref:`JOBTMPL/Parameters/Input/python_version_list` is an empty string, this version is used
to populate the version list.
Python version to be used for all jobs requiring a single Python version.
.. _JOBTMPL/Parameters/Input/python_version_list:
python_version_list python_version_list
=================== ===================
+----------------------+----------+----------+----------------------------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+======================+==========+==========+============================+ :Default Value: ``'3.9 3.10 3.11 3.12 3.13'``
| python_version_list | optional | string | ``3.8 3.9 3.10 3.11 3.12`` | :Possible Values: A space separated list of valid Python versions conforming to the pattern ``<major>.<minor>`` or
+----------------------+----------+----------+----------------------------+ ``pypy-<major>.<minor>``. |br|
See `actions/python-versions - available Python versions <https://github.com/actions/python-versions>`__
and `actions/setup-python - configurable Python versions <https://github.com/actions/setup-python>`__.
:Description: The list of space-separated Python versions used for Python variation testing.
Space separated list of CPython versions and/or mypy version to run tests with. .. include:: ../PythonVersionList.rst
.. include:: ../PythonVersionList.rst
.. _JOBTMPL/Parameters/Input/system_list:
system_list system_list
=========== ===========
+----------------+----------+----------+-----------------------------------------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+=========================================+ :Default Value: ``'ubuntu windows macos macos-arm mingw64 ucrt64'``
| system_list | optional | string | ``ubuntu windows macos mingw64 ucrt64`` | :Possible Values: A space separated list of system names.
+----------------+----------+----------+-----------------------------------------+ :Description: The list of space-separated systems used for application testing.
Space separated list of systems to run tests on. .. include:: ../SystemList.rst
.. include:: ../SystemList.rst
.. _JOBTMPL/Parameters/Input/include_list:
include_list include_list
============ ============
+----------------+----------+----------+----------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+==========+ :Default Value: ``''``
| include_list | optional | string | ``""`` | :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
+----------------+----------+----------+----------+ :Description: List of space-separated ``<system>:<python_version>`` tuples to be included into the list of test
variants.
Space separated list of ``system:python`` items to be included into the list of test. :Example:
.. code-block:: yaml
**Example:**
.. code-block:: yaml
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
include_list: "ubuntu:3.11 macos:3.11" include_list: "ubuntu:3.11 macos:3.11"
.. _JOBTMPL/Parameters/Input/exclude_list:
exclude_list exclude_list
============ ============
+----------------+----------+----------+----------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+==========+ :Default Value: ``''``
| exclude_list | optional | string | ``""`` | :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
+----------------+----------+----------+----------+ :Description: List of space-separated ``<system>:<python_version>`` tuples to be excluded from the list of test
variants.
Space separated list of ``system:python`` items to be excluded from the list of test. :Example:
.. code-block:: yaml
**Example:**
.. code-block:: yaml
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
exclude_list: "windows:pypy-3.8 windows:pypy-3.9" exclude_list: "windows:pypy-3.8 windows:pypy-3.9"
.. _JOBTMPL/Parameters/Input/disable_list:
disable_list disable_list
============ ============
+----------------+----------+----------+----------+ :Type: string
| Parameter Name | Required | Type | Default | :Required: no
+================+==========+==========+==========+ :Default Value: ``''``
| disable_list | optional | string | ``""`` | :Possible Values: A space separated list of ``<system>:<python_version>`` tuples.
+----------------+----------+----------+----------+ :Description: List of space-separated ``<system>:<python_version>`` tuples to be temporarily disabled from the list
of test variants. |br|
Space separated list of ``system:python`` items to be temporarily disabled from the list of test. Each disabled item creates a warning in the workflow log:
:Example:
Each disabled item creates a warning in the workflow log: .. code-block:: yaml
.. image:: /_static/GH_Workflow_DisabledJobsWarnings.png
:scale: 80 %
**Example:**
.. code-block:: yaml
jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
disable_list: "windows:3.10 windows:3.11" disable_list: "windows:3.10 windows:3.11"
.. image:: ../../_static/GH_Workflow_DisabledJobsWarnings.png
:width: 400px
.. _JOBTMPL/Parameters/Input/ubuntu_image:
ubuntu_image
============
:Type: string
:Required: no
:Default Value: ``'ubuntu-24.04'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
:Description: Name of the Ubuntu x86-64 image and version used to run a Ubuntu jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
.. _JOBTMPL/Parameters/Input/windows_image:
windows_image
=============
:Type: string
:Required: no
:Default Value: ``'windows-2025'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
:Description: Name of the Windows Server x86-64 image and version used to run a Widnows jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
.. _JOBTMPL/Parameters/Input/macos_intel_image:
macos_intel_image
=================
:Type: string
:Required: no
:Default Value: ``'macos-13'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
:Description: Name of the macOS x86-64 image and version used to run a macOS Intel jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
.. _JOBTMPL/Parameters/Input/macos_arm_image:
macos_arm_image
===============
:Type: string
:Required: no
:Default Value: ``'macos-15'``
:Possible Values: See `actions/runner-images - Available Images <https://github.com/actions/runner-images?tab=readme-ov-file#available-images>`__
:Description: Name of the macOS aarch64 image and version used to run a macOS ARM jobs when selected via :ref:`JOBTMPL/Parameters/Input/system_list`.
.. _JOBTMPL/Parameters/Input/pipeline-delay:
pipeline-delay
==============
:Type: number
:Required: no
:Default Value: ``0``
:Possible Values: Any integer number.
:Description: Slow down this job, to delay the startup of the GitHub Action pipline.
.. _JOBTMPL/Parameters/Secrets:
Secrets Secrets
******* *******
This job template needs no secrets. This job template needs no secrets.
Results
.. _JOBTMPL/Parameters/Outputs:
Outputs
******* *******
.. _JOBTMPL/Parameters/Output/python_version:
python_version python_version
============== ==============
A single string parameter representing the default Python version that should be used across multiple jobs in the same :Type: string
pipeline. :Default Value: ``'3.13'``
:Possible Values: Any valid Python version conforming to the pattern ``<major>.<minor>`` or ``pypy-<major>.<minor>``.
:Description: Returns
Such a parameter is needed as a workaround, because GitHub Actions doesn't support proper handling of global pipeline A single string parameter representing the default Python version that should be used across multiple jobs in the same
variables. Thus, this job is used to compute an output parameter that can be reused in other jobs. pipeline.
**Usage Example:** Such a parameter is needed as a workaround, because GitHub Actions doesn't support proper handling of global pipeline
variables. Thus, this job is used to compute an output parameter that can be reused in other jobs.
.. code-block:: yaml :Example:
.. code-block:: yaml
jobs: jobs:
Params: Params:
@@ -253,84 +563,129 @@ variables. Thus, this job is used to compute an output parameter that can be reu
with: with:
python_version: ${{ needs.Params.outputs.python_version }} python_version: ${{ needs.Params.outputs.python_version }}
.. _JOBTMPL/Parameters/Output/python_jobs:
python_jobs python_jobs
=========== ===========
A list of dictionaries containing a job description. :Type: string (JSON)
:Description: Returns a JSON array of job descriptions, wherein each job description is a dictionary providing the
following key-value pairs:
A job description contains the following key-value pairs: * ``sysicon`` - icon to display
* ``system`` - name of the system
* ``sysicon`` - icon to display * ``runs-on`` - virtual machine image and base operating system
* ``system`` - name of the system * ``runtime`` - name of the runtime environment if not running natively on the VM image
* ``runs-on`` - virtual machine image and base operating system * ``shell`` - name of the shell
* ``runtime`` - name of the runtime environment if not running natively on the VM image * ``pyicon`` - icon for CPython or pypy
* ``shell`` - name of the shell * ``python`` - Python version
* ``pyicon`` - icon for CPython or pypy * ``envname`` - full name of the selected environment
* ``python`` - Python version :Example:
* ``envname`` - full name of the selected environment .. code-block:: yaml
**Usage Example:**
.. code-block:: yaml
jobs: jobs:
Params: Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with: with:
name: pyTooling name: pyDummy
UnitTesting: UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs: needs:
- Params - Params
with: with:
jobs: ${{ needs.Params.outputs.python_jobs }} jobs: ${{ needs.Params.outputs.python_jobs }}
:Usage: The generated JSON array can be unpacked using the ``fromJson(...)`` function in a job's matrix
``strategy:matrix:include`` like this:
This list can be unpacked with ``fromJson(...)`` in a job ``strategy:matrix:include``: .. code-block:: yaml
.. code-block:: yaml name: Unit Testing (Matrix)
on:
workflow_call:
inputs:
jobs:
required: true
type: string
jobs:
UnitTesting: UnitTesting:
name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }} name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }}
runs-on: ${{ matrix.runs-on }} runs-on: ${{ matrix.runs-on }}
strategy: strategy:
matrix: matrix:
include: ${{ fromJson(inputs.jobs) }} include: ${{ fromJson(inputs.jobs) }}
defaults: defaults:
run: run:
shell: ${{ matrix.shell }} shell: ${{ matrix.shell }}
steps: steps:
- name: 🐍 Setup Python ${{ matrix.python }} - name: 🐍 Setup Python ${{ matrix.python }}
if: matrix.system != 'msys2' if: matrix.system != 'msys2'
uses: actions/setup-python@v4 uses: actions/setup-python@v4
with: with:
python-version: ${{ matrix.python }} python-version: ${{ matrix.python }}
:Debugging: The job prints debugging information like system |times| Python version |times| environment
combinations as well as the generated JSON array in the job's log.
.. code-block:: json
[
{"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🔴", "python": "3.9", "envname": "Linux (x86-64)" },
{"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟠", "python": "3.10", "envname": "Linux (x86-64)" },
{"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟡", "python": "3.11", "envname": "Linux (x86-64)" },
{"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.12", "envname": "Linux (x86-64)" },
{"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.13", "envname": "Linux (x86-64)" },
{"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🔴", "python": "3.9", "envname": "Windows (x86-64)" },
{"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟠", "python": "3.10", "envname": "Windows (x86-64)" },
{"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟡", "python": "3.11", "envname": "Windows (x86-64)" },
{"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟢", "python": "3.12", "envname": "Windows (x86-64)" },
{"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟢", "python": "3.13", "envname": "Windows (x86-64)" },
{"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🔴", "python": "3.9", "envname": "macOS (x86-64)" },
{"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟠", "python": "3.10", "envname": "macOS (x86-64)" },
{"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟡", "python": "3.11", "envname": "macOS (x86-64)" },
{"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.12", "envname": "macOS (x86-64)" },
{"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.13", "envname": "macOS (x86-64)" },
{"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🔴", "python": "3.9", "envname": "macOS (aarch64)" },
{"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🟠", "python": "3.10", "envname": "macOS (aarch64)" },
{"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🟡", "python": "3.11", "envname": "macOS (aarch64)" },
{"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.12", "envname": "macOS (aarch64)" },
{"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.13", "envname": "macOS (aarch64)" },
{"sysicon": "🪟🟦", "system": "msys2", "runs-on": "windows-2025", "runtime": "MINGW64", "shell": "msys2 {0}", "pyicon": "🟢", "python": "3.12", "envname": "Windows+MSYS2 (x86-64) - MinGW64"},
{"sysicon": "🪟🟨", "system": "msys2", "runs-on": "windows-2025", "runtime": "UCRT64", "shell": "msys2 {0}", "pyicon": "🟢", "python": "3.12", "envname": "Windows+MSYS2 (x86-64) - UCRT64" }
]
.. _JOBTMPL/Parameters/Output/artifact_names:
artifact_names artifact_names
============== ==============
A dictionary of artifact names sharing a common prefix. :Type: string (JSON)
:Description: Returns a JSON dictionary of artifact names sharing a common prefix (see :ref:`JOBTMPL/Parameters/Input/name`). |br|
As artifacts are handed from jo to job, a consistent nameing scheme is advised to avoid duplications
and naming artifacts by hand. This technique solves again the problem of global variables in GitHub
Action YAMl files and the need for assigning the same value (here artifact name) to multiple jobs
templates.
The supported artifacts are: The supported artifacts are:
* ``unittesting_xml`` - UnitTesting XML summary report * ``unittesting_xml`` - UnitTesting XML summary report
* ``unittesting_html`` - UnitTesting HTML summary report * ``unittesting_html`` - UnitTesting HTML summary report
* ``codecoverage_sqlite`` - Code Coverage internal database (SQLite) * ``perftesting_xml`` - PerformanceTesting XML summary report
* ``codecoverage_json`` - Code Coverage JSON report * ``benchtesting_xml`` - Benchmarking XML summary report
* ``codecoverage_xml`` - Code Coverage XML report * ``apptesting_xml`` - ApplicationTesting XML summary report
* ``codecoverage_html`` - Code Coverage HTML report * ``codecoverage_sqlite`` - Code Coverage internal database (SQLite)
* ``statictyping_html`` - Static Type Checking HTML report * ``codecoverage_xml`` - Code Coverage XML report
* ``package_all`` - Packaged Python project (multiple formats) * ``codecoverage_json`` - Code Coverage JSON report
* ``documentation_pdf`` - Documentation in PDF format * ``codecoverage_html`` - Code Coverage HTML report
* ``documentation_html`` - Documentation in HTML format * ``statictyping_html`` - Static Type Checking HTML report
* ``package_all`` - Packaged Python project (multiple formats)
**Usage Example:** * ``documentation_html`` - Documentation in HTML format
* ``documentation_latex`` - Documentation in LaTeX format
.. code-block:: yaml * ``documentation_pdf`` - Documentation in PDF format
:Example:
.. code-block:: yaml
jobs: jobs:
Params: Params:
@@ -339,20 +694,25 @@ The supported artifacts are:
name: pyTooling name: pyTooling
Coverage: Coverage:
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs: needs:
- Params - Params
with: with:
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}
Params .. _JOBTMPL/Parameters/Output/params:
params
====== ======
.. attention:: ``Params`` is deprecated. .. attention:: ``params`` is deprecated.
* ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']`` :Type: string (JSON)
* ``params['coverage']`` |rarr| ``artifact_names['codecoverage_xml']`` :Description: Returns a JSON dictionary of artifact names. |br|
* ``params['typing']`` |rarr| ``artifact_names['statictyping_html']`` Use :ref:`JOBTMPL/Parameters/Output/artifact_names` as a more powerful replacement.
* ``params['package']`` |rarr| ``artifact_names['package_all']`` :Replacements: * ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']``
* ``params['doc']`` |rarr| ``artifact_names['documentation_html']`` * ``params['coverage']`` |rarr| ``artifact_names['codecoverage_xml']``
* ``params['typing']`` |rarr| ``artifact_names['statictyping_html']``
* ``params['package']`` |rarr| ``artifact_names['package_all']``
* ``params['doc']`` |rarr| ``artifact_names['documentation_html']``

2
doc/JobTemplate/SystemList.rst
View File

@@ -6,7 +6,7 @@
+------+-----------+------------------------------+-----------------------------------------------------------------+ +------+-----------+------------------------------+-----------------------------------------------------------------+
| Icon | System | Used version | Comments | | Icon | System | Used version | Comments |
+======+===========+==============================+=================================================================+ +======+===========+==============================+=================================================================+
| 🧊 | Windows | Windows Server 2025 (latest) | | | 🪟 | Windows | Windows Server 2025 (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+ +------+-----------+------------------------------+-----------------------------------------------------------------+
| 🐧 | Ubuntu | Ubuntu 24.04 (LTS) (latest) | | | 🐧 | Ubuntu | Ubuntu 24.04 (LTS) (latest) | |
+------+-----------+------------------------------+-----------------------------------------------------------------+ +------+-----------+------------------------------+-----------------------------------------------------------------+

BIN
doc/_static/pyTooling-Actions-Parameters.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 631 KiB