Generate an iCalendar file of the release dates

Author: hugovk

.coveragerc

@@ -0,0 +1,7 @@
+[run]
+omit =
+    release_management/__main__.py
+
+[report]
+exclude_also =
+    if __name__ == .__main__.:

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_ical, create_release_json
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -77,5 +77,8 @@ def create_pep_zero(app: Sphinx, env: BuildEnvironment, docnames: list[str]) ->
     release_cycle = create_release_cycle()
     app.outdir.joinpath('api/release-cycle.json').write_text(release_cycle, encoding="utf-8")
 
+    release_ical = create_release_ical()
+    app.outdir.joinpath('api/python-releases.ics').write_text(release_ical, encoding="utf-8")
+
     release_json = create_release_json()
     app.outdir.joinpath('api/python-releases.json').write_text(release_json, encoding="utf-8")

pytest.ini

@@ -5,12 +5,15 @@ addopts =
     --strict-config
     --strict-markers
     --import-mode=importlib
-    --cov check_peps --cov pep_sphinx_extensions
-    --cov-report html --cov-report xml
+    --cov check_peps
+    --cov pep_sphinx_extensions
+    --cov release_management
+    --cov-report html
+    --cov-report xml
 empty_parameter_set_mark = fail_at_collect
 filterwarnings =
     error
 minversion = 6.0
-testpaths = pep_sphinx_extensions
+testpaths = pep_sphinx_extensions release_management
 xfail_strict = True
 disable_test_id_escaping_and_forfeit_all_rights_to_community_support = True

release_management/__init__.py

@@ -2,6 +2,7 @@
 
 import sys
 from dataclasses import dataclass
+from functools import cache
 from pathlib import Path
 
 try:
@@ -67,6 +68,7 @@ def schedule_bullet(self):
         return f'- {self.stage}: {self.date:%A, %Y-%m-%d}'
 
 
+@cache
 def load_python_releases() -> PythonReleases:
     with open(RELEASE_DIR / 'python-releases.toml', 'rb') as f:
         python_releases = tomllib.load(f)

release_management/serialize.py

@@ -2,6 +2,9 @@
 
 import dataclasses
 import json
+import re
+
+from icalendar import Calendar, Event
 
 from release_management import load_python_releases
 
@@ -48,3 +51,42 @@ def version_info(metadata: VersionMetadata, /) -> dict[str, str | int]:
         'end_of_life': end_of_life,
         'release_manager': metadata.release_manager,
     }
+
+
+def ical_uid(name: str) -> str:
+    user = re.sub(r'[^a-z0-9.]+', '', name.lower())
+    return f'python-{user}@python.org'
+
+
+def create_release_ical() -> str:
+    python_releases = load_python_releases()
+
+    calendar = Calendar()
+    calendar.add('version', '2.0')
+    calendar.add('prodid', '-//Python Software Foundation//Python releases//EN')
+    calendar.add('x-wr-calname', 'Python releases')
+    calendar.add(
+        'x-wr-caldesc', 'Python releases schedule from https://peps.python.org'
+    )
+
+    all_releases = []
+    for version, releases in python_releases.releases.items():
+        for release in releases:
+            all_releases.append((version, release))
+
+    all_releases.sort(key=lambda r: r[1].date)
+
+    for version, release in all_releases:
+        event = Event()
+        event.add('summary', f'Python {release.stage}')
+        event.add('uid', ical_uid(release.stage))
+        event.add('dtstart', release.date)
+        pep_number = python_releases.metadata[version].pep
+        event.add('url', f'https://peps.python.org/pep-{pep_number:04d}/')
+
+        if release.note:
+            event.add('description', f'Note: {release.note}')
+
+        calendar.add_component(event)
+
+    return calendar.to_ical().decode('utf-8')

release_management/tests/test_serialize.py

@@ -0,0 +1,67 @@
+import pytest
+from icalendar import Calendar
+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_ical_returns_valid_icalendar():
+    # Act
+    ical_str = serialize.create_release_ical()
+
+    # Assert
+    # Non-empty string
+    assert isinstance(ical_str, str)
+    assert len(ical_str) > 0
+
+    # Parseable as a valid iCalendar
+    cal = Calendar.from_ical(ical_str)
+    assert cal is not None
+
+
+def test_create_release_ical_has_calendar_metadata():
+    # Act
+    ical_str = serialize.create_release_ical()
+
+    # Assert
+    cal = Calendar.from_ical(ical_str)
+
+    # Check calendar metadata
+    assert cal.get('version') == '2.0'
+    assert cal.get('prodid') == '-//Python Software Foundation//Python releases//EN'
+    assert cal.get('x-wr-calname') == 'Python releases'
+    assert 'peps.python.org' in cal.get('x-wr-caldesc')
+
+
+def test_create_release_ical_first_event():
+    # Act
+    ical_str = serialize.create_release_ical()
+
+    # Assert
+    cal = Calendar.from_ical(ical_str)
+    first_event = cal.events[0]
+    assert first_event.get('summary') == 'Python 1.6.0 alpha 1'
+    assert str(first_event.get('dtstart').dt) == '2000-03-31'
+    assert first_event.get('uid') == '[email protected]'
+    assert first_event.get('url') == 'https://peps.python.org/pep-0160/'
+
+
+def test_create_release_ical_sorted_by_date():
+    # Act
+    ical_str = serialize.create_release_ical()
+
+    # Assert
+    cal = Calendar.from_ical(ical_str)
+    dates = [event.get('dtstart').dt for event in cal.events]
+    assert dates == sorted(dates)

requirements.txt

@@ -10,5 +10,8 @@ sphinx-notfound-page >= 1.0.2
 pytest
 pytest-cov
 
+# For python-releases.ical
+icalendar
+
 # For python-releases.toml
 tomli >= 1.1.0 ; python_version < "3.11"