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`.

814
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,337 +32,687 @@ 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
name: Pipeline 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.
on: .. grid-item::
push: :columns: 7
workflow_dispatch:
jobs: .. code-block:: yaml
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 name: Pipeline
with:
name: pyTooling on:
push:
workflow_dispatch:
jobs:
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
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` | The following instantiation example creates 3 jobs from the same template, but with differing input parameters.
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| 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 | 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
| 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 | 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.
| MSYS 🟪 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ The second job ``PerformanceTestingParams`` might be used to create a job matrix for performance tests. Here a
| MinGW32 ⬛ | | | | | | | | | | pipeline might be limited to the latest two Python versions on a selected list of platforms.
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| MinGW64 🟦 | | | | mingw64:3.11 | | | | | | The third job ``PlatformTestingParams`` might be used to create a job matrix for platform compatibility tests.
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ Here a pipeline might be limited to the latest Python version, but all available platforms.
| Clang32 🟫 | | | | | | | | | |
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ .. grid-item::
| Clang64 🟧 | | | | | | | | | | :columns: 7
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
| UCRT64 🟨 | | | | | | | | | | .. code-block:: yaml
+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+
jobs:
UnitTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_namespace: myFramework
package_name: Extension
python_version_list: '3.9 3.10 3.11 3.12 pypy-3.10 pypy-3.11'
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:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_namespace: myFramework
package_name: Extension
python_version_list: '3.12 3.13'
system_list: 'ubuntu windows macos macos-arm'
PlatformTestingParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_namespace: myFramework
package_name: Extension
python_version_list: '3.13'
system_list: 'ubuntu windows macos macos-arm mingw32 mingw64 clang64 ucrt64'
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
| 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 | | | | | |
+--------------------------------+----------------+-----------------+-----------------+-----------------+----------------------------+------------+-------------+-------------------------------+-------------------------------+
.. code-block:: yaml .. _JOBTMPL/Parameters/Parameters:
name: Pipeline Parameter Summary
*****************
on: .. rubric:: Goto :ref:`input parameters <JOBTMPL/Parameters/Inputs>`
push:
workflow_dispatch:
jobs: +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
UnitTestingParams: | Parameter Name | Required | Type | Default |
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 +=====================================================================+==========+==========+===================================================================+
with: | :ref:`JOBTMPL/Parameters/Input/ubuntu_image_version` | no | string | ``'24.04'`` |
name: pyTooling +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
python_version_list: "3.8 3.9 3.10 3.11 pypy-3.9 pypy-3.10" | :ref:`JOBTMPL/Parameters/Input/name` | no | string | ``''`` |
include_list: "ubuntu:3.12 macos:3.12" +---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
exclude_list: "windows:pypy-3.9 windows:pypy-3.10" | :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`` |
+---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+
PerformanceTestingParams: .. rubric:: Goto Goto :ref:`secrets <JOBTMPL/Parameters/Secrets>`
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
python_version_list: "3.11 3.12"
system_list: "ubuntu windows macos"
PlatformTestingParams: This job template needs no secrets.
uses: pyTooling/Actions/.github/workflows/Parameters.yml@dev
with:
name: pyTooling
python_version_list: "3.12"
system_list: "ubuntu windows macos mingw32 mingw64 clang64 ucrt64"
Parameters .. 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.
:Example:
.. code-block:: yaml
Space separated list of ``system:python`` items to be included into the list of test. jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
include_list: "ubuntu:3.11 macos:3.11"
**Example:**
.. code-block:: yaml
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.
:Example:
.. code-block:: yaml
Space separated list of ``system:python`` items to be excluded from the list of test. jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
exclude_list: "windows:pypy-3.8 windows:pypy-3.9"
**Example:**
.. code-block:: yaml
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|
Each disabled item creates a warning in the workflow log:
:Example:
.. code-block:: yaml
Space separated list of ``system:python`` items to be temporarily disabled from the list of test. jobs:
ConfigParams:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
package_name: myPackage
disable_list: "windows:3.10 windows:3.11"
Each disabled item creates a warning in the workflow log: .. image:: ../../_static/GH_Workflow_DisabledJobsWarnings.png
:width: 400px
.. image:: /_static/GH_Workflow_DisabledJobsWarnings.png
:scale: 80 %
**Example:** .. _JOBTMPL/Parameters/Input/ubuntu_image:
.. code-block:: yaml ubuntu_image
============
disable_list: "windows:3.10 windows:3.11" :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.
:Example:
.. code-block:: yaml
.. code-block:: yaml jobs:
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
jobs: CodeCoverage:
Params: uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 needs:
with: - Params
name: pyTooling with:
python_version: ${{ needs.Params.outputs.python_version }}
CodeCoverage:
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5 .. _JOBTMPL/Parameters/Output/python_jobs:
needs:
- Params
with:
python_version: ${{ needs.Params.outputs.python_version }}
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
* ``runs-on`` - virtual machine image and base operating system
* ``runtime`` - name of the runtime environment if not running natively on the VM image
* ``shell`` - name of the shell
* ``pyicon`` - icon for CPython or pypy
* ``python`` - Python version
* ``envname`` - full name of the selected environment
:Example:
.. code-block:: yaml
* ``sysicon`` - icon to display jobs:
* ``system`` - name of the system Params:
* ``runs-on`` - virtual machine image and base operating system uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
* ``runtime`` - name of the runtime environment if not running natively on the VM image with:
* ``shell`` - name of the shell name: pyDummy
* ``pyicon`` - icon for CPython or pypy
* ``python`` - Python version
* ``envname`` - full name of the selected environment
**Usage Example:** UnitTesting:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
needs:
- Params
with:
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:
.. code-block:: yaml .. code-block:: yaml
jobs: name: Unit Testing (Matrix)
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
UnitTesting: on:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev workflow_call:
needs: inputs:
- Params jobs:
with: required: true
jobs: ${{ needs.Params.outputs.python_jobs }} type: string
This list can be unpacked with ``fromJson(...)`` in a job ``strategy:matrix:include``: jobs:
UnitTesting:
name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }}
runs-on: ${{ matrix.runs-on }}
strategy:
matrix:
include: ${{ fromJson(inputs.jobs) }}
defaults:
run:
shell: ${{ matrix.shell }}
steps:
- name: 🐍 Setup Python ${{ matrix.python }}
if: matrix.system != 'msys2'
uses: actions/setup-python@v4
with:
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:: yaml .. code-block:: json
UnitTesting: [
name: ${{ matrix.sysicon }} ${{ matrix.pyicon }} Unit Tests using Python ${{ matrix.python }} {"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🔴", "python": "3.9", "envname": "Linux (x86-64)" },
runs-on: ${{ matrix.runs-on }} {"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)" },
strategy: {"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.12", "envname": "Linux (x86-64)" },
matrix: {"sysicon": "🐧", "system": "ubuntu", "runs-on": "ubuntu-24.04", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.13", "envname": "Linux (x86-64)" },
include: ${{ fromJson(inputs.jobs) }} {"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)" },
defaults: {"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟡", "python": "3.11", "envname": "Windows (x86-64)" },
run: {"sysicon": "🪟", "system": "windows", "runs-on": "windows-2025", "runtime": "native", "shell": "pwsh", "pyicon": "🟢", "python": "3.12", "envname": "Windows (x86-64)" },
shell: ${{ matrix.shell }} {"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)" },
steps: {"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟠", "python": "3.10", "envname": "macOS (x86-64)" },
- name: 🐍 Setup Python ${{ matrix.python }} {"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟡", "python": "3.11", "envname": "macOS (x86-64)" },
if: matrix.system != 'msys2' {"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.12", "envname": "macOS (x86-64)" },
uses: actions/setup-python@v4 {"sysicon": "🍎", "system": "macos", "runs-on": "macos-13", "runtime": "native", "shell": "bash", "pyicon": "🟢", "python": "3.13", "envname": "macOS (x86-64)" },
with: {"sysicon": "🍏", "system": "macos-arm", "runs-on": "macos-14", "runtime": "native", "shell": "bash", "pyicon": "🔴", "python": "3.9", "envname": "macOS (aarch64)" },
python-version: ${{ matrix.python }} {"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)
* ``documentation_html`` - Documentation in HTML format
* ``documentation_latex`` - Documentation in LaTeX format
* ``documentation_pdf`` - Documentation in PDF format
:Example:
.. code-block:: yaml
**Usage Example:** jobs:
Params:
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5
with:
name: pyTooling
.. code-block:: yaml Coverage:
uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5
jobs: needs:
Params: - Params
uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 with:
with: unittest_xml_artifact: ${{ fromJson(needs.Params.outputs.artifact_names).unittesting_xml }}
name: pyTooling
Coverage:
uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev
needs:
- Params
with:
artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
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