🧪 Mv GHA pip deps cache mgmt to in-tree actions

The upstream `actions/setup-python` has rudimentary support for cache
management but it's rather limited. It also has bugs in caching [[1]].

Having own reusable cache computation bit gives us better level of
control, letting us make cache depend on specific Python runtime
features.

[1]: actions/setup-python#1034

.github/actions/cache-keys/action.yml

@@ -0,0 +1,43 @@
+---
+
+outputs:
+  cache-key-for-dep-files:
+    description: >-
+      A cache key string derived from the dependency declaration files.
+    value: ${{ steps.calc-cache-key-files.outputs.files-hash-key }}
+
+runs:
+  using: composite
+  steps:
+  - name: >-
+      Calculate dependency files' combined hash value
+      for use in the cache key
+    id: calc-cache-key-files
+    run: |
+      from os import environ
+      from pathlib import Path
+
+      FILE_APPEND_MODE = 'a'
+
+      files_derived_hash = '${{
+          hashFiles(
+            'tox.ini',
+            'pyproject.toml',
+            '.pre-commit-config.yaml',
+            'pytest.ini',
+            'requirements/**'
+          )
+      }}'
+
+      print(f'Computed file-derived hash is {files_derived_hash}.')
+
+      with Path(environ['GITHUB_OUTPUT']).open(
+              mode=FILE_APPEND_MODE,
+      ) as outputs_file:
+          print(
+              f'files-hash-key={files_derived_hash}',
+              file=outputs_file,
+          )
+    shell: python
+
+...

.github/actions/cache-pip-deps/action.yml

@@ -0,0 +1,111 @@
+---
+
+inputs:
+  cache-key-for-dep-files:
+    description: >-
+      A cache key string derived from the dependency declaration files.
+    required: true
+
+outputs:
+  cache-key-for-pip-deps:
+    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 }}
+  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 }}
+  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 }}
+  pip-cache-dir:
+    description: >-
+      The discovered pip cache directory path.
+    value: ${{ steps.pip-cache-dir.outputs.dir }}
+
+runs:
+  using: composite
+  steps:
+  - name: >-
+      Calculate Python interpreter properties
+      version hash value
+      for use in the cache key
+    id: python-runtime
+    run: |
+      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 }}-pip-{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-dep-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 pip cache dir
+    id: pip-cache-dir
+    run: >-
+      echo "dir=$(python -m pip cache dir)" >> "${GITHUB_OUTPUT}"
+    shell: bash
+  - name: Skip setting up pip cache
+    if: >-
+      !fromJSON(steps.python-runtime.outputs.is-stable-abi)
+    run: >-
+      >&2 echo Skipping cache configuration because the current
+      Python ABI is unstable...
+    shell: bash
+  - name: Set up pip cache
+    if: fromJSON(steps.python-runtime.outputs.is-stable-abi)
+    uses: actions/cache@v4
+    with:
+      path: ${{ steps.pip-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 }}
+
+...

.github/workflows/ci-cd.yml

@@ -79,9 +79,16 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ env.PYTHON_LATEST }}
-        cache: pip
-        cache-dependency-path:
-          requirements/*.txt
+    - name: >-
+        Calculate dependency files' combined hash value
+        for use in the cache key
+      id: calc-cache-key-files
+      uses: ./.github/actions/cache-keys
+    - name: Set up pip cache
+      uses: ./.github/actions/cache-pip-deps
+      with:
+        cache-key-for-dep-files: >-
+          ${{ steps.calc-cache-key-files.outputs.cache-key-for-dep-files }}
     - name: Install core libraries for build
       run: python -Im pip install build
     - name: Build sdists and pure-python wheel
@@ -220,8 +227,16 @@ jobs:
       with:
         python-version: ${{ matrix.pyver }}
         allow-prereleases: true
-        cache: pip
-        cache-dependency-path: requirements/*.txt
+    - name: >-
+        Calculate dependency files' combined hash value
+        for use in the cache key
+      id: calc-cache-key-files
+      uses: ./.github/actions/cache-keys
+    - name: Set up pip cache
+      uses: ./.github/actions/cache-pip-deps
+      with:
+        cache-key-for-dep-files: >-
+          ${{ steps.calc-cache-key-files.outputs.cache-key-for-dep-files }}
     - name: Install dependencies
       uses: py-actions/py-dependency-install@v4
       with:

.github/workflows/reusable-linters.yml

@@ -36,8 +36,16 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ env.PYTHON_LATEST }}
-        cache: pip
-        cache-dependency-path: requirements/*.txt
+    - name: >-
+        Calculate dependency files' combined hash value
+        for use in the cache key
+      id: calc-cache-key-files
+      uses: ./.github/actions/cache-keys
+    - name: Set up pip cache
+      uses: ./.github/actions/cache-pip-deps
+      with:
+        cache-key-for-dep-files: >-
+          ${{ steps.calc-cache-key-files.outputs.cache-key-for-dep-files }}
     - name: Cache pre-commit.com virtualenvs
       uses: actions/cache@v4
       with: