ENH: Add scripts to publish wheels and cached builds

Author: CavRiley

.gitignore

@@ -73,6 +73,9 @@ docs/_build
 .idea/*
 *.swp
 /itkVersion.py
+# PyPI credentials
+.pypirc
+
 # pixi environments
 .pixi/*
 !.pixi/config.toml

.pypirc.example

@@ -0,0 +1,23 @@
+# .pypirc.example -- DO NOT commit real credentials
+# Copy to ~/.pypirc and fill in your token.
+#
+# Generate a token at: https://pypi.org/manage/account/token/
+# For TestPyPI:        https://test.pypi.org/manage/account/token/
+#
+# Alternatively, set environment variables:
+#   TWINE_USERNAME=__token__
+#   TWINE_PASSWORD=pypi-<your-token>
+
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-YOUR-TOKEN-HERE
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR-TOKEN-HERE

README.md

@@ -1,7 +1,7 @@
 # ITK Python Package
 
 This project configures pyproject.toml files and manages environmental
-variables needed to build ITK Python binary wheels on MacOS, Linux, and Windows platforms.
+variables needed to build ITK Python binary wheels on macOS, Linux, and Windows platforms.
 Scripts are available for both [ITK infrastructure](https://github.com/insightSoftwareConsortium/ITK) and
 ITK external module Python packages.
 
@@ -20,7 +20,7 @@ or at the [ITK GitHub homepage](https://github.com/insightSoftwareConsortium/ITK
 ## Building Remote Modules with ITKPythonPackage
 
 ITK reusable workflows are available to build and package Python wheels as
-part of Continuous Integration (CI) via Github Actions runners.
+part of Continuous Integration (CI) via GitHub Actions runners.
 Those workflows can handle the overhead of fetching, configuring, and
 running ITKPythonPackage build scripts for most ITK external modules.
 See [ITKRemoteModuleBuildTestPackageAction](https://github.com/InsightSoftwareConsortium/ITKRemoteModuleBuildTestPackageAction)
@@ -31,7 +31,7 @@ for more information.
 
 For special cases where ITK reusable workflows are not a good fit,
 ITKPythonPackage scripts can be directly used to build Python wheels
-to target Windows, Linux, and MacOS platforms. See
+to target Windows, Linux, and macOS platforms. See
 below or the [ITKPythonPackage ReadTheDocs](https://itkpythonpackage.readthedocs.io/en/latest/Build_ITK_Module_Python_packages.html)
 documentation for more information on building wheels by hand.
 
@@ -273,8 +273,43 @@ On Windows systems
 
 To build caches for local use, you can run the `build_wheels.py` script with the `--build-itk-tarball-cache`
 
+#### Publish Tarball Caches
+
+To publish the tarball caches to a GitHub Release, you can run:
+
+> [!NOTE]
+> This requires the `GH_TOKEN` environment variable to be set or `gh auth login` to have been run beforehand.
+> Tarballs are expected in the parent directory of `--build-dir-root` (POSIX `.tar.zst`) or inside it (Windows `.zip`).
+
+```bash
+pixi run -e publish publish-tarball-cache --itk-package-version v6.0b02 --build-dir-root /path/to/build/root
+```
+
+Users can also specify the GitHub repository to publish to using `--repo` (defaults to ITKPythonBuilds) and
+`--create-release` to create the release if it does not already exist.
+
 </details>
 
+To see how to publish wheels see this section:
+
+<details>
+<summary><strong>Publishing Wheels</strong></summary>
+This repository contains a script for publishing wheels to PyPI and TestPyPI.
+
+The script can be run with the pixi environment as such:
+
+> [!NOTE]
+> This script assumes you have the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables set or the
+> `.pypirc` file configured on your machine. An example `.pypirc` can be seen in the root of this repository
+
+```bash
+pixi run -e publish publish-wheels --dist-directory /path/to/dist/
+```
+
+You can also optionally pass in `--test` to publish to TestPyPI for validation before uploading to production,
+`--repository-url` to specify a custom package index, or `--skip-existing` to skip already-uploaded wheels.
+
+</details>
 
 ---
 ## Frequently Asked Questions

docs/Build_ITK_Module_Python_packages.rst

@@ -277,9 +277,35 @@ Example output::
 Uploading to PyPI
 =================
 
+Using the Publish Environment
+-----------------------------
+
+ITKPythonPackage provides a ``publish`` Pixi environment with ``twine``
+pre-configured. Set your PyPI credentials (see ``.pypirc.example`` in the
+repository root) and run:
+
+.. code-block:: bash
+
+   export TWINE_USERNAME=__token__
+   export TWINE_PASSWORD=pypi-<your-token>
+
+   # Test on TestPyPI first
+   pixi run -e publish publish-wheels \
+     --dist-directory /path/to/module/dist \
+     --test
+
+   # Then upload to production PyPI
+   pixi run -e publish publish-wheels \
+     --dist-directory /path/to/module/dist
+
+Pass ``--skip-existing`` to skip already-uploaded wheels when re-running after
+a partial upload failure.
+
 Manual Upload
 -------------
 
+Alternatively, install and use ``twine`` directly.
+
 Test on TestPyPI first::
 
    pip install twine

docs/Build_ITK_Python_packages.rst

@@ -343,6 +343,103 @@ Install and smoke-test a wheel directly from the ``dist/`` directory:
    python -c "import itk; print(itk.__version__)"
 
 
+Publishing
+==========
+
+ITKPythonPackage provides a lightweight ``publish`` Pixi environment with
+`twine <https://twine.readthedocs.io/>`_ for uploading wheels to PyPI and the
+`GitHub CLI <https://cli.github.com/>`_ for uploading tarball caches to GitHub
+Releases. Install it with::
+
+   pixi install -e publish
+
+
+Publishing Wheels to PyPI
+-------------------------
+
+The ``publish-wheels`` task validates wheel metadata with ``twine check`` and
+then uploads all ``.whl`` files from a ``dist/`` directory.
+
+**Authentication** — set environment variables or configure ``~/.pypirc``
+(see ``.pypirc.example`` in the repository root):
+
+.. code-block:: bash
+
+   export TWINE_USERNAME=__token__
+   export TWINE_PASSWORD=pypi-<your-token>
+
+Upload to **TestPyPI** first for validation:
+
+.. code-block:: bash
+
+   pixi run -e publish publish-wheels \
+     --dist-directory /path/to/dist \
+     --test
+
+Then upload to **production PyPI**:
+
+.. code-block:: bash
+
+   pixi run -e publish publish-wheels \
+     --dist-directory /path/to/dist
+
+Additional options:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Option
+     - Description
+   * - ``--test``
+     - Upload to TestPyPI (``https://test.pypi.org/legacy/``)
+   * - ``--repository-url``
+     - Custom package index URL (overrides ``--test``)
+   * - ``--skip-existing``
+     - Skip already-uploaded wheels instead of failing
+
+
+Publishing Tarball Caches to GitHub Releases
+--------------------------------------------
+
+The ``publish-tarball-cache`` task uploads ``.tar.zst`` (POSIX) and ``.zip``
+(Windows) build caches to a GitHub Release on the
+`ITKPythonBuilds <https://github.com/InsightSoftwareConsortium/ITKPythonBuilds>`_
+repository.
+
+**Authentication** — set the ``GH_TOKEN`` environment variable or run
+``gh auth login`` beforehand.
+
+.. code-block:: bash
+
+   pixi run -e publish publish-tarball-cache \
+     --itk-package-version v6.0b02 \
+     --build-dir-root /path/to/build \
+     --create-release
+
+Additional options:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Option
+     - Description
+   * - ``--itk-package-version``
+     - **(required)** Release tag name (e.g. ``v6.0b02``)
+   * - ``--build-dir-root``
+     - Root of the build directory; tarballs are found in its parent
+       (POSIX ``.tar.zst``) or inside it (Windows ``.zip``)
+   * - ``--repo``
+     - Target GitHub repository (default: ``InsightSoftwareConsortium/ITKPythonBuilds``)
+   * - ``--create-release``
+     - Create the GitHub Release if it does not already exist
+
+.. note::
+   The ``--clobber`` flag is used internally so re-uploading a tarball for the
+   same platform replaces the existing asset without manual cleanup.
+
+
 Troubleshooting
 ===============