diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index cb6bc90..c47d7c2 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -401,7 +401,8 @@ unittest_python_version_list :Type: string :Required: no :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 ``.`` or + ``pypy-.``. :Description: The list of space-separated Python versions used for unit testing. .. include:: ../PythonVersionList.rst @@ -429,7 +430,7 @@ unittest_include_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: @@ -441,7 +442,7 @@ unittest_exclude_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: @@ -453,7 +454,7 @@ unittest_disable_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: @@ -483,7 +484,8 @@ apptest_python_version_list :Type: string :Required: no :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 ``.`` or + ``pypy-.```. :Description: The list of space-separated Python versions used for application testing. As this list is empty by default, the value is derived from @@ -514,7 +516,7 @@ apptest_include_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: @@ -526,7 +528,7 @@ apptest_exclude_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: @@ -538,7 +540,7 @@ apptest_disable_list :Type: string :Required: no :Default Value: ``''`` -:Possible Values: A space separated list of ``system:python_version`` tuples. +:Possible Values: A space separated list of ``:`` tuples. :Description: diff --git a/doc/JobTemplate/Setup/ExtractConfiguration.rst b/doc/JobTemplate/Setup/ExtractConfiguration.rst index 1e102ec..04193ff 100644 --- a/doc/JobTemplate/Setup/ExtractConfiguration.rst +++ b/doc/JobTemplate/Setup/ExtractConfiguration.rst @@ -10,7 +10,8 @@ The ``ExtractConfiguration`` job template is a ..... .. topic:: Features * 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. * 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`. diff --git a/doc/JobTemplate/Setup/Parameters.rst b/doc/JobTemplate/Setup/Parameters.rst index d201a71..c64a537 100644 --- a/doc/JobTemplate/Setup/Parameters.rst +++ b/doc/JobTemplate/Setup/Parameters.rst @@ -4,17 +4,27 @@ Parameters ########## 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 `__. +GitHub Actions workflows (see `actions/runner#480 `__). 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 ************* @@ -22,337 +32,687 @@ Instantiation Simple Example ============== -The following instantiation example creates a job `Params` derived from job template `Parameters` version `r0`. It only -requires a `name` parameter to create the artifact names. +.. grid:: 2 -.. 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: - push: - workflow_dispatch: + .. grid-item:: + :columns: 7 - jobs: - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling + .. code-block:: yaml + + name: Pipeline + + 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 =============== -The following instantiation example creates 3 jobs from the same template, but with differing input parameters. 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, 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:: 2 -+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ -| Version | 3.8 πŸ”΄ | 3.9 🟠 | 3.10 🟑 | 3.11 🟒 | 3.12 🟒 | 3.13.a1 🟣 | pypy-3.8 πŸ”΄ | pypy-3.9 🟠 | pypy-3.10 🟑 | -+============+=============+=============+==============+==============+=========================+============+=============+==============================+===============================+ -| 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 🟨 | | | | | | | | | | -+------------+-------------+-------------+--------------+--------------+-------------------------+------------+-------------+------------------------------+-------------------------------+ + .. grid-item:: + :columns: 5 + + The following instantiation example creates 3 jobs from the same template, but with differing input parameters. + + 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. + + 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. + + 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. + + .. grid-item:: + :columns: 7 + + .. 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: - push: - workflow_dispatch: +.. rubric:: Goto :ref:`input parameters ` - jobs: - UnitTestingParams: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling - python_version_list: "3.8 3.9 3.10 3.11 pypy-3.9 pypy-3.10" - include_list: "ubuntu:3.12 macos:3.12" - exclude_list: "windows:pypy-3.9 windows:pypy-3.10" ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| 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`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ - PerformanceTestingParams: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling - python_version_list: "3.11 3.12" - system_list: "ubuntu windows macos" +.. rubric:: Goto Goto :ref:`secrets ` - PlatformTestingParams: - 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" +This job template needs no secrets. -Parameters -********** +.. rubric:: Goto Goto :ref:`output parameters ` + ++---------------------------------------------------------------------+----------+-------------------------------------------------------------------+ +| 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 `__ + 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 `__, + 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 ==== -+----------------+----------+----------+--------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==============+ -| name | yes | string | β€” β€” β€” β€” | -+----------------+----------+----------+--------------+ +:Type: string +:Required: no +:Default Value: ``''`` +: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 ============== -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| python_version | optional | string | ``3.12`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``'3.13'`` +:Possible Values: Any valid Python version conforming to the pattern ``.`` or ``pypy-.``. |br| + See `actions/python-versions - available Python versions `__ + and `actions/setup-python - configurable Python versions `__. +: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 =================== -+----------------------+----------+----------+----------------------------+ -| Parameter Name | Required | Type | Default | -+======================+==========+==========+============================+ -| python_version_list | optional | string | ``3.8 3.9 3.10 3.11 3.12`` | -+----------------------+----------+----------+----------------------------+ +:Type: string +:Required: no +: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 ``.`` or + ``pypy-.``. |br| + See `actions/python-versions - available Python versions `__ + and `actions/setup-python - configurable Python versions `__. +: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 =========== -+----------------+----------+----------+-----------------------------------------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+=========================================+ -| system_list | optional | string | ``ubuntu windows macos mingw64 ucrt64`` | -+----------------+----------+----------+-----------------------------------------+ +:Type: string +:Required: no +:Default Value: ``'ubuntu windows macos macos-arm 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 ============ -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| include_list | optional | string | ``""`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``:`` tuples. +:Description: List of space-separated ``:`` 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 ============ -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| exclude_list | optional | string | ``""`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``:`` tuples. +:Description: List of space-separated ``:`` 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 ============ -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| disable_list | optional | string | ``""`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: A space separated list of ``:`` tuples. +:Description: List of space-separated ``:`` 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 - :scale: 80 % + .. image:: ../../_static/GH_Workflow_DisabledJobsWarnings.png + :width: 400px -**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 `__ +: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 `__ +: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 `__ +: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 `__ +: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 ******* This job template needs no secrets. -Results + +.. _JOBTMPL/Parameters/Outputs: + +Outputs ******* +.. _JOBTMPL/Parameters/Output/python_version: + python_version ============== -A single string parameter representing the default Python version that should be used across multiple jobs in the same -pipeline. +:Type: string +:Default Value: ``'3.13'`` +:Possible Values: Any valid Python version conforming to the pattern ``.`` or ``pypy-.``. +:Description: Returns -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. + A single string parameter representing the default Python version that should be used across multiple jobs in the same + 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: - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling + CodeCoverage: + uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5 + needs: + - Params + with: + python_version: ${{ needs.Params.outputs.python_version }} - CodeCoverage: - uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@r5 - needs: - - Params - with: - python_version: ${{ needs.Params.outputs.python_version }} + +.. _JOBTMPL/Parameters/Output/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 -* ``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 + jobs: + Params: + uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 + with: + name: pyDummy -**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: - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling + name: Unit Testing (Matrix) - UnitTesting: - uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@dev - needs: - - Params - with: - jobs: ${{ needs.Params.outputs.python_jobs }} + on: + workflow_call: + inputs: + jobs: + required: true + 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 }} - 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 }} + [ + {"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 ============== -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_html`` - UnitTesting HTML summary report -* ``codecoverage_sqlite`` - Code Coverage internal database (SQLite) -* ``codecoverage_json`` - Code Coverage JSON report -* ``codecoverage_xml`` - Code Coverage XML report -* ``codecoverage_html`` - Code Coverage HTML report -* ``statictyping_html`` - Static Type Checking HTML report -* ``package_all`` - Packaged Python project (multiple formats) -* ``documentation_pdf`` - Documentation in PDF format -* ``documentation_html`` - Documentation in HTML format + * ``unittesting_xml`` - UnitTesting XML summary report + * ``unittesting_html`` - UnitTesting HTML summary report + * ``perftesting_xml`` - PerformanceTesting XML summary report + * ``benchtesting_xml`` - Benchmarking XML summary report + * ``apptesting_xml`` - ApplicationTesting XML summary report + * ``codecoverage_sqlite`` - Code Coverage internal database (SQLite) + * ``codecoverage_xml`` - Code Coverage XML report + * ``codecoverage_json`` - Code Coverage JSON report + * ``codecoverage_html`` - Code Coverage HTML report + * ``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 - - jobs: - Params: - uses: pyTooling/Actions/.github/workflows/Parameters.yml@r5 - with: - name: pyTooling - - Coverage: - uses: pyTooling/Actions/.github/workflows/CoverageCollection.yml@dev - needs: - - Params - with: - artifact: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }} + Coverage: + uses: pyTooling/Actions/.github/workflows/UnitTesting.yml@r5 + needs: + - Params + with: + 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']`` -* ``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']`` +:Type: string (JSON) +:Description: Returns a JSON dictionary of artifact names. |br| + Use :ref:`JOBTMPL/Parameters/Output/artifact_names` as a more powerful replacement. +:Replacements: * ``params['unittesting']`` |rarr| ``artifact_names['unittesting_xml']`` + * ``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']`` diff --git a/doc/JobTemplate/SystemList.rst b/doc/JobTemplate/SystemList.rst index 4fd9703..2e26ed2 100644 --- a/doc/JobTemplate/SystemList.rst +++ b/doc/JobTemplate/SystemList.rst @@ -6,7 +6,7 @@ +------+-----------+------------------------------+-----------------------------------------------------------------+ | Icon | System | Used version | Comments | +======+===========+==============================+=================================================================+ -| 🧊 | Windows | Windows Server 2025 (latest) | | +| πŸͺŸ | Windows | Windows Server 2025 (latest) | | +------+-----------+------------------------------+-----------------------------------------------------------------+ | 🐧 | Ubuntu | Ubuntu 24.04 (LTS) (latest) | | +------+-----------+------------------------------+-----------------------------------------------------------------+ diff --git a/doc/_static/pyTooling-Actions-Parameters.png b/doc/_static/pyTooling-Actions-Parameters.png new file mode 100644 index 0000000..bd28140 Binary files /dev/null and b/doc/_static/pyTooling-Actions-Parameters.png differ