action.yml

---

name: cache-python-deps
description: >-
  A GitHub Action maintaining caches dependent on Python runtime
  and ABI stability.

branding:
  icon: archive
  color: black

inputs:
  cache-directory-lookup-command:
    description: A command that prints cache directory to standard output.
    default: python -Im pip cache dir
    required: false
  cache-key-for-dependency-files:
    description: >-
      A cache key string derived from the dependency declaration files.
    required: true

outputs:
  cache-directory-path:
    description: The discovered cache directory path.
    value: ${{ steps.cache-dir.outputs.dir }}
  cache-key-for-os:
    description: >-
      A cache key string derived from the current OS and interpreter stability.
    value: >-
      ${{ steps.python-runtime.outputs.restore-key-fallback-prefix }}
  cache-key-for-dependencies:
    description: >-
      A cache key string derived from the current interpreter version
      and the dependency file hashes.
    value: >-
      ${{ steps.python-runtime.outputs.cache-entry-key }}
  cache-key-for-python-interpreter:
    description: >-
      A cache key string derived from the current interpreter version.
    value: >-
      ${{ steps.python-runtime.outputs.restore-key-prefix }}
  is-stable-abi:
    description: >-
      Whether the currently used Python version has a reliable
      Application Binary Interface. If it doesn't, it's best to avoid
      caching any dependencies.
    value: ${{ steps.python-runtime.outputs.is-stable-abi }}

runs:
  using: composite
  steps:
  - name: >-
      Calculate Python interpreter properties version hash value
      for use in the cache key
    id: python-runtime
    run: |
      # Determining the Python runtime features...

      from hashlib import sha512
      from os import environ
      from sys import version, version_info

      FILE_APPEND_MODE = 'a'

      is_stable_abi = version_info.releaselevel == 'final'
      version_hash = sha512(version.encode()).hexdigest()

      stable_or_unstable = f'{"" if is_stable_abi else "un"}stable'
      restore_key_fallback_prefix = (
          f'${{ runner.os }}-python-dep-cache-{stable_or_unstable}'
      )
      restore_key_prefix = f'{restore_key_fallback_prefix}-{version_hash}'
      cache_entry_key = (
          f'{restore_key_prefix}-{version_hash}-'
          '${{ inputs.cache-key-for-dependency-files }}'
      )

      print(f'Python ABI is found to be {stable_or_unstable}.')
      print(f'Python version-derived hash is {version_hash}.')
      print(f'The computed cache entry key is {cache_entry_key}.')

      with open(
              environ['GITHUB_OUTPUT'], mode=FILE_APPEND_MODE,
      ) as outputs_file:
          print(
              'is-stable-abi={is_stable_abi}'.
              format(is_stable_abi=str(is_stable_abi).lower()),
              file=outputs_file,
          )
          print(
              f'restore-key-fallback-prefix={restore_key_fallback_prefix}',
              file=outputs_file,
          )
          print(
              f'restore-key-prefix={restore_key_prefix}',
              file=outputs_file,
          )
          print(f'cache-entry-key={cache_entry_key}', file=outputs_file)
    shell: python
  - name: Get cache dir
    id: cache-dir
    run: >
      # Discovering cache directory...

      echo "dir=$(${{ inputs.cache-directory-lookup-command }})"
      >> "${GITHUB_OUTPUT}"
    shell: bash
  - name: Skip setting up cache
    if: >-
      !fromJSON(steps.python-runtime.outputs.is-stable-abi)
    run: >
      # Skipping cache configuration because due to unstable Python ABI...


      >&2 echo Skipping cache configuration because the current
      Python ABI is unstable...
    shell: bash
  - name: Set up cache
    if: fromJSON(steps.python-runtime.outputs.is-stable-abi)
    uses: actions/cache@v5
    with:
      path: ${{ steps.cache-dir.outputs.dir }}
      key: >-
        ${{ steps.python-runtime.outputs.cache-entry-key }}
      restore-keys: |
        ${{ steps.python-runtime.outputs.cache-entry-key }}
        ${{ steps.python-runtime.outputs.restore-key-prefix }}
        ${{ steps.python-runtime.outputs.restore-key-fallback-prefix }}

...