feat: Add check-eol-cached hook

Author: GideonBear

.github/workflows/bump_cache.yml

@@ -3,7 +3,8 @@ name: Check Cached Release Cycle
 on:
   workflow_dispatch:
   schedule:
-    - cron: "0 14 14 1,4,7,10 *"
+    # EOLs are currently scheduled for 20xx-10-01
+    - cron: "0 14 2 1,4,7,10 *"
 
 jobs:
   bump-cache:
@@ -40,12 +41,14 @@ jobs:
           echo EOF
         } >> "$GITHUB_OUTPUT"
 
-    - name: Open Issue If Bumped
-      if: ${{ steps.bump.outputs.RES != ''}}
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: |
-        today=$(date +"%Y-%m-%d")
-        gh issue create \
-          --title "($today) Release Cycle Cache Outdated" \
-          --body '\`\`\`diff\n${{ steps.report.outputs.RES }}\n\`\`\`'
+    - name: Set Date
+      id: date
+      run:
+        echo "today=$(date +"%Y-%m-%d")" >> "$GITHUB_OUTPUT"
+
+    - name: Create Pull Request If Bumped
+      uses: peter-evans/create-pull-request@v7
+      with:
+        branch: "bump-cache"
+        title: "chore: update release cycle cache (${{ steps.date.outputs.today }})"
+        commit-message: "chore: update release cycle cache (${{ steps.date.outputs.today }})"

.pre-commit-hooks.yaml

@@ -4,3 +4,10 @@
   language: python
   files: '^pyproject.toml$'
   types: [toml]
+
+- id: check-eol-cached
+  name: Check supported Python EOL (cached)
+  entry: checkeol --cached
+  language: python
+  files: '^pyproject.toml$'
+  types: [toml]

pre_commit_python_eol/bump_cache.py

@@ -1,8 +1,12 @@
 import json
 import platform
-from pathlib import Path
 
 from pre_commit_python_eol import __url__, __version__
+from pre_commit_python_eol.check_eol import CACHED_EOL_VERSIONS as LOCAL_CACHE_EOL_VERSIONS
+from pre_commit_python_eol.check_eol import CACHED_RELEASE_CYCLE as LOCAL_CACHE_CYCLE
+from pre_commit_python_eol.check_eol import (
+    get_eol_versions,
+)
 
 try:
     import httpx
@@ -18,21 +22,30 @@
 )
 
 CACHE_SOURCE = "https://peps.python.org/api/release-cycle.json"
-LOCAL_CACHE = Path("./pre_commit_python_eol/cached_release_cycle.json")
 
 
-def bump_cache() -> None:
+def bump_cached_release_cycle() -> None:
     """Update the cached release cycle JSON from the source repository."""
     with httpx.Client(headers={"User-Agent": USER_AGENT}) as client:
         r = client.get(CACHE_SOURCE)
         r.raise_for_status()
 
         rj = r.json()
 
-    with LOCAL_CACHE.open("w", encoding="utf8") as f:
+    with LOCAL_CACHE_CYCLE.open("w", encoding="utf8") as f:
         json.dump(rj, f, indent=2, ensure_ascii=False)
         f.write("\n")  # Add in trailing newline
 
 
+def bump_cached_eol_versions() -> None:
+    """Update the cached EOL versions JSON from the source repository."""
+    eol_versions = dict(version.to_json() for version in get_eol_versions())
+
+    with LOCAL_CACHE_EOL_VERSIONS.open("w", encoding="utf8") as f:
+        json.dump(eol_versions, f, indent=2, ensure_ascii=False)
+        f.write("\n")  # Add in trailing newline
+
+
 if __name__ == "__main__":
-    bump_cache()
+    bump_cached_release_cycle()
+    bump_cached_eol_versions()

pre_commit_python_eol/cached_eol_versions.json

@@ -0,0 +1,50 @@
+{
+  "3.9": {
+    "status": "end-of-life",
+    "end_of_life": "2025-10-31"
+  },
+  "3.8": {
+    "status": "end-of-life",
+    "end_of_life": "2024-10-07"
+  },
+  "3.7": {
+    "status": "end-of-life",
+    "end_of_life": "2023-06-27"
+  },
+  "3.6": {
+    "status": "end-of-life",
+    "end_of_life": "2021-12-23"
+  },
+  "3.5": {
+    "status": "end-of-life",
+    "end_of_life": "2020-09-30"
+  },
+  "3.4": {
+    "status": "end-of-life",
+    "end_of_life": "2019-03-18"
+  },
+  "3.3": {
+    "status": "end-of-life",
+    "end_of_life": "2017-09-29"
+  },
+  "3.2": {
+    "status": "end-of-life",
+    "end_of_life": "2016-02-20"
+  },
+  "3.1": {
+    "status": "end-of-life",
+    "end_of_life": "2012-04-09"
+  },
+  "3.0": {
+    "status": "end-of-life",
+    "end_of_life": "2009-06-27"
+  },
+  "2.7": {
+    "status": "end-of-life",
+    "end_of_life": "2020-01-01"
+  },
+  "2.6": {
+    "status": "end-of-life",
+    "end_of_life": "2013-10-29"
+  }
+}

pre_commit_python_eol/check_eol.py

@@ -15,6 +15,7 @@
 from packaging import specifiers, version
 
 CACHED_RELEASE_CYCLE = Path(__file__).parent / "cached_release_cycle.json"
+CACHED_EOL_VERSIONS = Path(__file__).parent / "cached_eol_versions.json"
 
 
 class EOLPythonError(Exception): ...  # noqa: D101
@@ -81,6 +82,13 @@ def from_json(cls, ver: str, metadata: dict[str, t.Any]) -> PythonRelease:
             end_of_life=_parse_eol_date(metadata["end_of_life"]),
         )
 
+    def to_json(self) -> tuple[str, dict[str, str]]:
+        """Recreates the original JSON object from the `PythonRelease` instance."""
+        return str(self.python_ver), {
+            "status": self.status.value,
+            "end_of_life": self.end_of_life.isoformat(),
+        }
+
 
 def _get_cached_release_cycle(cache_json: Path) -> list[PythonRelease]:
     """
@@ -100,7 +108,27 @@ def _get_cached_release_cycle(cache_json: Path) -> list[PythonRelease]:
     )
 
 
-def check_python_support(toml_file: Path, cache_json: Path = CACHED_RELEASE_CYCLE) -> None:
+def get_cached_eol_versions() -> abc.Iterator[PythonRelease]:
+    """Parse the locally cached EOL Python versions into `PythonRelease` instance(s)."""
+    with CACHED_EOL_VERSIONS.open("r", encoding="utf-8") as f:
+        contents = json.load(f)
+
+    return (PythonRelease.from_json(v, m) for v, m in contents.items())
+
+
+def get_eol_versions(cache_json: Path = CACHED_RELEASE_CYCLE) -> abc.Iterator[PythonRelease]:
+    """Enumerate all EOL Python versions."""
+    release_cycle = _get_cached_release_cycle(cache_json)
+    utc_today = dt.datetime.now(dt.timezone.utc).date()
+
+    for r in release_cycle:
+        if r.status == ReleasePhase.EOL or r.end_of_life <= utc_today:
+            yield r
+
+
+def check_python_support(
+    toml_file: Path, *, cached: bool = False, cache_json: Path = CACHED_RELEASE_CYCLE
+) -> None:
     """
     Check the input TOML's `requires-python` for overlap with EOL Python version(s).
 
@@ -115,19 +143,12 @@ def check_python_support(toml_file: Path, cache_json: Path = CACHED_RELEASE_CYCL
         raise RequiresPythonNotFoundError
 
     package_spec = specifiers.SpecifierSet(requires_python)
-    release_cycle = _get_cached_release_cycle(cache_json)
-    utc_today = dt.datetime.now(dt.timezone.utc).date()
-
-    eol_supported = []
-    for r in release_cycle:
-        if r.python_ver in package_spec:
-            if r.status == ReleasePhase.EOL:
-                eol_supported.append(r)
-                continue
 
-            if r.end_of_life <= utc_today:
-                eol_supported.append(r)
-                continue
+    if cached:
+        eol_versions = get_cached_eol_versions()
+    else:
+        eol_versions = get_eol_versions(cache_json)
+    eol_supported = [version for version in eol_versions if version.python_ver in package_spec]
 
     if eol_supported:
         eol_supported.sort(key=attrgetter("python_ver"))  # Sort ascending for error msg generation
@@ -138,12 +159,13 @@ def check_python_support(toml_file: Path, cache_json: Path = CACHED_RELEASE_CYCL
 def main(argv: abc.Sequence[str] | None = None) -> int:  # noqa: D103
     parser = argparse.ArgumentParser()
     parser.add_argument("filenames", nargs="*", type=Path)
+    parser.add_argument("--cached", action="store_true")
     args = parser.parse_args(argv)
 
     ec = 0
     for file in args.filenames:
         try:
-            check_python_support(file)
+            check_python_support(file, cached=args.cached)
         except EOLPythonError as e:
             print(f"{file}: {e}")
             ec = 1