diff --git a/.github/workflows/Package.yml b/.github/workflows/Package.yml index e772f0f..e23de40 100644 --- a/.github/workflows/Package.yml +++ b/.github/workflows/Package.yml @@ -46,7 +46,6 @@ on: type: string jobs: - Package: name: 📦 Package in Source and Wheel Format runs-on: "ubuntu-${{ inputs.ubuntu_image_version }}" diff --git a/.gitignore b/.gitignore index f2c0f24..9fdee07 100644 --- a/.gitignore +++ b/.gitignore @@ -25,7 +25,7 @@ coverage.xml # Sphinx doc/_build/ -doc/pyDummy/**/*.* +doc/myPackage/**/*.* !doc/myPackage/index.rst # BuildTheDocs diff --git a/doc/JobTemplate/AllInOne/CompletePipeline.rst b/doc/JobTemplate/AllInOne/CompletePipeline.rst index 7bef2cb..a27e1ba 100644 --- a/doc/JobTemplate/AllInOne/CompletePipeline.rst +++ b/doc/JobTemplate/AllInOne/CompletePipeline.rst @@ -193,6 +193,18 @@ It can be used for simple Python packages as well as namespace packages. * :ref:`pyTooling/Actions/.github/workflows/CheckDocumentation.yml ` * :ref:`pyTooling/Actions/.github/workflows/StaticTypeCheck.yml ` * :ref:`pyTooling/Actions/.github/workflows/Package.yml ` + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * pip + + * :pypi:`build` + * :pypi:`wheel` + * :ref:`pyTooling/Actions/.github/workflows/PublishTestResults.yml ` * :ref:`pyTooling/Actions/.github/workflows/PublishCoverageResults.yml ` * :ref:`pyTooling/Actions/.github/workflows/SphinxDocumentation.yml ` diff --git a/doc/JobTemplate/Package/Package.rst b/doc/JobTemplate/Package/Package.rst index 078e3ad..379f12a 100644 --- a/doc/JobTemplate/Package/Package.rst +++ b/doc/JobTemplate/Package/Package.rst @@ -6,22 +6,45 @@ Package This job packages the Python source code as a source package (``*.tar.gz``) and wheel package (``*.whl``) and uploads it as an artifact. -**Behavior:** +.. topic:: Features -1. Checkout repository -2. Setup Python and install dependencies -3. Package Python sources: + * Package source code as wheel and source distribution. + * Support packaging using :pypi:`build` (recommended) or :pypi:`setuptools`. - * If parameter ``requirements`` is empty, use ``build`` package and run ``python build``. - * If parameter ``requirements`` is ``no-isolation``, use ``build`` package in *no-isolation* mode and run - ``python build``. - * If parameter ``requirements`` is non-empty, use ``setuptools`` package and run ``python setup.py``. +.. topic:: Behavior: -**Dependencies:** + 1. Checkout repository. + 2. Setup Python and install dependencies. + 3. Package Python sources: -* :gh:`actions/checkout` -* :gh:`actions/setup-python` -* :gh:`actions/upload-artifact` + * If parameter :ref:`JOBTMPL/Package/Input/requirements` is empty, use :pypi:`build` for packaging and execute + ``python -m build ...``. + * If parameter :ref:`JOBTMPL/Package/Input/requirements` is ``no-isolation``, use :pypi:`build` for packaging in + *no-isolation* mode executing ``python -m build --no-isolation ...``. + * If parameter :ref:`JOBTMPL/Package/Input/requirements` is non-empty, use :pypi:`setuptools` for package and + execute ``python setup.py ...``. + + +.. topic:: Job Execution + + .. image:: ../../_static/pyTooling-Actions-Package.png + :width: 500px + +.. topic:: Dependencies + + * :gh:`actions/checkout` + * :gh:`actions/setup-python` + * :gh:`pyTooling/upload-artifact` + + * :gh:`actions/upload-artifact` + + * pip + + * :pypi:`build` + * :pypi:`wheel` + + +.. _JOBTMPL/Package/Instantiation: Instantiation ************* @@ -48,51 +71,114 @@ Complex Example uses: pyTooling/Actions/.github/workflows/Package.yml@r5 needs: - Params - - Coverage with: python_version: ${{ needs.Params.outputs.python_version }} requirements: -r build/requirements.txt artifact: ${{ fromJson(needs.Params.outputs.artifact_names).package_all }} -Parameters -********** +.. seealso:: + + :ref:`JOBTMPL/PublishOnPyPI` + + +.. _JOBTMPL/Package/Parameters: + +Parameter Summary +***************** + +.. rubric:: Goto :ref:`input parameters ` + ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| Parameter Name | Required | Type | Default | ++=====================================================================+==========+==========+===================================================================+ +| :ref:`JOBTMPL/Package/Input/ubuntu_image_version` | no | string | ``'24.04'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Package/Input/python_version` | no | string | ``'3.13'`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Package/Input/requirements` | no | string | ``''`` | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ +| :ref:`JOBTMPL/Package/Input/artifact` | yes | string | — — — — | ++---------------------------------------------------------------------+----------+----------+-------------------------------------------------------------------+ + +.. rubric:: Goto :ref:`secrets ` + +This job template needs no secrets. + +.. rubric:: Goto :ref:`output parameters ` + +This job template has no output parameters. + + +.. _JOBTMPL/Package/Inputs: + +Input Parameters +**************** + +.. _JOBTMPL/Package/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/Package/Input/python_version: python_version ============== -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| python_version | optional | string | 3.11 | -+----------------+----------+----------+----------+ +: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. +.. _JOBTMPL/Package/Input/requirements: requirements ============ -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| requirements | optional | string | ``""`` | -+----------------+----------+----------+----------+ +:Type: string +:Required: no +:Default Value: ``''`` +:Possible Values: Any valid list of parameters for ``pip install``. |br| + Either a requirements file can be referenced using ``'-r path/to/requirements.txt'``, or a list of + packages can be specified using a space separated list like ``'build wheel'``. +:Behavior: If the value is an empty string, :pypi:`build` is used for packaging. |br| + if the value is ``no-isolation``, :ypy:`build` is used in *no-isolation* mode for packaging. |br| + otherwise, a list of requirements is assumed and :pypi:`setuptools` is used for packaging. +:Description: Python dependencies to be installed through *pip*. -Python dependencies to be installed through pip; if empty, use pyproject.toml through build. +.. _JOBTMPL/Package/Input/artifact: artifact ======== -+----------------+----------+----------+----------+ -| Parameter Name | Required | Type | Default | -+================+==========+==========+==========+ -| artifact | yes | string | — — — — | -+----------------+----------+----------+----------+ +:Type: string +:Required: yes +:Possible Values: Any valid artifact name. +:Description: Name of the artifact containing the unittest report summary in XML format. -Name of the package artifact. +.. _JOBTMPL/Package/Secrets: Secrets ******* @@ -100,7 +186,17 @@ Secrets This job template needs no secrets. -Results +.. _JOBTMPL/Package/Outputs: + +Outputs ******* This job template has no output parameters. + + +.. _JOBTMPL/Package/Optimizations: + +Optimizations +************* + +This template offers no optimizations (reduced job runtime). diff --git a/doc/_static/pyTooling-Actions-Package.png b/doc/_static/pyTooling-Actions-Package.png new file mode 100644 index 0000000..a685fff Binary files /dev/null and b/doc/_static/pyTooling-Actions-Package.png differ diff --git a/doc/index.rst b/doc/index.rst index 85138db..3158631 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -205,7 +205,7 @@ License :caption: pyDummy Example :hidden: - pyDummy/pyDummy + myPackage/myPackage unittests/index coverage/index CodeCoverage