Generate a release schedule as an .ics file

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: hugovk

pep_sphinx_extensions/pep_zero_generator/pep_index_generator.py

@@ -26,7 +26,7 @@
 from pep_sphinx_extensions.pep_zero_generator import subindices
 from pep_sphinx_extensions.pep_zero_generator import writer
 from pep_sphinx_extensions.pep_zero_generator.constants import SUBINDICES_BY_TOPIC
-from release_management.serialize import create_release_cycle, create_release_json
+from release_management.serialize import create_release_cycle, create_release_schedule_calendar, create_release_json
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -79,3 +79,6 @@ def create_pep_zero(app: Sphinx, env: BuildEnvironment, docnames: list[str]) ->
 
     release_json = create_release_json()
     app.outdir.joinpath('api/python-releases.json').write_text(release_json, encoding="utf-8")
+
+    release_ical = create_release_schedule_calendar()
+    app.outdir.joinpath('release-schedule.ics').write_text(release_ical, encoding="utf-8")

release_management/__init__.py

@@ -23,6 +23,7 @@
 RELEASE_DIR = Path(__file__).resolve().parent
 ROOT_DIR = RELEASE_DIR.parent
 PEP_ROOT = ROOT_DIR / 'peps'
+_PYTHON_RELEASES = None
 
 dc_kw = {'kw_only': True, 'slots': True} if sys.version_info[:2] >= (3, 10) else {}
 
@@ -68,6 +69,10 @@ def schedule_bullet(self):
 
 
 def load_python_releases() -> PythonReleases:
+    global _PYTHON_RELEASES
+    if _PYTHON_RELEASES is not None:
+        return _PYTHON_RELEASES
+
     with open(RELEASE_DIR / 'python-releases.toml', 'rb') as f:
         python_releases = tomllib.load(f)
     all_metadata = {
@@ -78,4 +83,5 @@ def load_python_releases() -> PythonReleases:
         v: [ReleaseInfo(**r) for r in releases]
         for v, releases in python_releases['release'].items()
     }
-    return PythonReleases(metadata=all_metadata, releases=all_releases)
+    _PYTHON_RELEASES = PythonReleases(metadata=all_metadata, releases=all_releases)
+    return _PYTHON_RELEASES

release_management/__main__.py

@@ -6,6 +6,7 @@
     CMD_FULL_JSON := 'full-json',
     CMD_UPDATE_PEPS := 'update-peps',
     CMD_RELEASE_CYCLE := 'release-cycle',
+    CMD_CALENDAR := 'calendar',
 )
 parser = argparse.ArgumentParser(allow_abbrev=False)
 parser.add_argument('COMMAND', choices=commands)
@@ -31,3 +32,11 @@
     json_path = ROOT_DIR / 'release-cycle.json'
     json_path.write_text(create_release_cycle(), encoding='utf-8')
     raise SystemExit(0)
+
+if args.COMMAND == CMD_CALENDAR:
+    from release_management import ROOT_DIR
+    from release_management.serialize import create_release_schedule_calendar
+
+    calendar_path = ROOT_DIR / 'release-schedule.ics'
+    calendar_path.write_text(create_release_schedule_calendar(), encoding='utf-8')
+    raise SystemExit(0)

release_management/serialize.py

@@ -1,14 +1,20 @@
 from __future__ import annotations
 
+import datetime as dt
 import dataclasses
 import json
+import re
 
 from release_management import ROOT_DIR, load_python_releases
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     from release_management import VersionMetadata
 
+# Seven years captures the full lifecycle from prereleases to end-of-life
+TODAY = dt.date.today()
+SEVEN_YEARS_AGO = TODAY.replace(year=TODAY.year - 7)
+
 
 def create_release_json() -> str:
     python_releases = dataclasses.asdict(load_python_releases())
@@ -48,3 +54,41 @@ def version_info(metadata: VersionMetadata, /) -> dict[str, str | int]:
         'end_of_life': end_of_life,
         'release_manager': metadata.release_manager,
     }
+
+
+def create_release_schedule_calendar() -> str:
+    python_releases = load_python_releases()
+    all_releases = [
+        (version, release)
+        for version, releases in python_releases.releases.items()
+        for release in releases
+        # Keep size reasonable by omitting releases older than 7 years
+        if release.date >= SEVEN_YEARS_AGO
+    ]
+    all_releases.sort(key=lambda r: r[1].date)
+
+    lines = [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Python Software Foundation//Python release schedule//EN',
+        'X-WR-CALDESC:Python releases schedule from https://peps.python.org',
+        'X-WR-CALNAME:Python releases schedule',
+    ]
+    for version, release in all_releases:
+        normalised_stage = release.stage.casefold().replace(' ', '')
+        note = (f'DESCRIPTION:Note: {release.note}',) if release.note else ()
+        pep_number = python_releases.metadata[version].pep
+        lines += (
+            'BEGIN:VEVENT',
+            f'SUMMARY:Python {release.stage}',
+            f'DTSTART;VALUE=DATE:{release.date.strftime("%Y%m%d")}',
+            f'UID:python-{normalised_stage}@releases.python.org',
+            *note,
+            f'URL:https://peps.python.org/pep-{pep_number:04d}/',
+            'END:VEVENT',
+        )
+    lines += (
+        'END:VCALENDAR',
+        '',
+    )
+    return '\n'.join(lines)

release_management/tests/test_release_schedule_calendar.py

@@ -0,0 +1,50 @@
+import pytest
+
+from release_management import serialize
+
+
+@pytest.mark.parametrize(
+    ('test_input', 'expected'),
+    [
+        ('3.14.0 alpha 1', '[email protected]'),
+        ('3.14.0 beta 2', '[email protected]'),
+        ('3.14.0 candidate 3', '[email protected]'),
+        ('3.14.1', '[email protected]'),
+    ],
+)
+def test_ical_uid(test_input, expected):
+    assert serialize.ical_uid(test_input) == expected
+
+
+def test_create_release_calendar_has_calendar_metadata():
+    # Act
+    cal_lines = serialize.create_release_schedule_calendar().split('\n')
+
+    # Assert
+
+    # Check calendar metadata
+    assert cal_lines[:5] == [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Python Software Foundation//Python release schedule//EN',
+        'X-WR-CALDESC:Python releases schedule from https://peps.python.org',
+        'X-WR-CALNAME:Python releases schedule',
+    ]
+    assert cal_lines[-2:] == [
+        'END:VCALENDAR',
+        '',
+    ]
+
+
+def test_create_release_calendar_first_event():
+    # Act
+    cal_lines = serialize.create_release_schedule_calendar().split('\n')
+
+    # Assert
+    assert cal_lines[5] == 'BEGIN:VEVENT'
+    assert cal_lines[6].startswith('SUMMARY:Python ')
+    assert cal_lines[7].startswith('DTSTART;VALUE=DATE:')
+    assert cal_lines[8].startswith('UID:python-')
+    assert cal_lines[8].endswith('@release.python.org')
+    assert cal_lines[9].startswith('URL:https://peps.python.org/pep-')
+    assert cal_lines[10].startswith('END:VEVENT')