Add initial scripts

python · ambv · Nov 10, 2025 · Mar 29, 2025 · Mar 29, 2025 · Mar 29, 2025
commit 813ac0d2eaa1a43f5a80a3a5d2bed9dff830decc
diff --git a/release_engineering/__init__.py b/release_engineering/__init__.py
@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import tomllib
+from pathlib import Path
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Literal, TypeAlias
+
+    ReleaseState: TypeAlias = Literal['actual', 'expected']
+    ReleaseSchedules: TypeAlias = dict[tuple[str, ReleaseState], list['ReleaseInfo']]
+
+RELEASE_DIR = Path(__file__).resolve().parent
+ROOT_DIR = RELEASE_DIR.parent
+PEP_ROOT = ROOT_DIR / 'peps'
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class PythonReleases:
+    metadata: dict[str, 'VersionMetadata']
+    releases: dict[str, list['ReleaseInfo']]
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class VersionMetadata:
+    """Metadata for a given interpreter version (MAJOR.MINOR)."""
+
+    pep: int
+    status: str
+    branch: str
+    release_manager: str
+    start_of_development: dt.date
+    first_release: dt.date
+    feature_freeze: dt.date
+    end_of_bugfix: dt.date  # a.k.a. security mode or source-only releases
+    end_of_life: dt.date
+
+    @classmethod
+    def from_toml(cls, data: dict[str, int | str | dt.date]):
+        return cls(**{k.replace('-', '_'): v for k, v in data.items()})
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class ReleaseInfo:
+    """Information about a release."""
+
+    stage: str
+    state: ReleaseState
+    date: dt.date
+    note: str = ''  # optional note / comment, displayed in the schedule
+
+    @property
+    def schedule_bullet(self):
+        """Return a formatted bullet point for the schedule list."""
+        return f'- {self.stage}: {self.date:%A, %Y-%m-%d}'
+
+
+def load_python_releases() -> PythonReleases:
+    with open(RELEASE_DIR / 'python-releases.toml', 'rb') as f:
+        python_releases = tomllib.load(f)
+    all_metadata = {
+        v: VersionMetadata.from_toml(metadata)
+        for v, metadata in python_releases['metadata'].items()
+    }
+    all_releases = {
+        v: [ReleaseInfo(**r) for r in releases]
+        for v, releases in python_releases['release'].items()
+    }
+    return PythonReleases(metadata=all_metadata, releases=all_releases)
diff --git a/release_engineering/__main__.py b/release_engineering/__main__.py
@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import argparse
+
+CMD_UPDATE_PEPS = 'update-peps'
+CMD_RELEASE_CYCLE = 'release-cycle'
+
+PARSER = argparse.ArgumentParser(allow_abbrev=False)
+PARSER.add_argument('COMMAND', choices=[CMD_UPDATE_PEPS, CMD_RELEASE_CYCLE])
+
+args = PARSER.parse_args()
+if args.COMMAND == CMD_UPDATE_PEPS:
+    from release_engineering.update_release_schedules import update_peps
+
+    update_peps()
+elif args.COMMAND == CMD_RELEASE_CYCLE:
+    from pathlib import Path
+
+    from release_engineering.generate_release_cycle import create_release_cycle
+
+    Path('release-cycle.json').write_text(create_release_cycle(), encoding='utf-8')
diff --git a/release_engineering/generate_release_cycle.py b/release_engineering/generate_release_cycle.py
@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+
+from release_engineering import load_python_releases
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from release_engineering import VersionMetadata
+
+
+def create_release_cycle() -> str:
+    metadata = load_python_releases().metadata
+    versions = [v for v in metadata if version_to_tuple(v) >= (2, 6)]
+    versions.sort(key=version_to_tuple, reverse=True)
+    if '2.7' in versions:
+        versions.remove('2.7')
+        versions.insert(versions.index('3.1'), '2.7')
+
+    release_cycle = {version: version_info(metadata[version]) for version in versions}
+    return (
+        json.dumps(release_cycle, indent=2, sort_keys=False, ensure_ascii=False) + '\n'
+    )
+
+
+def version_to_tuple(version: str, /) -> tuple[int, ...]:
+    return tuple(map(int, version.split('.')))
+
+
+def version_info(metadata: VersionMetadata, /) -> dict[str, str]:
+    end_of_life = metadata.end_of_life.isoformat()
+    if metadata.status != 'end-of-life':
+        end_of_life = end_of_life.removesuffix('-01')
+    return {
+        'branch': metadata.branch,
+        'pep': metadata.pep,
+        'status': metadata.status,
+        'first_release': metadata.first_release.isoformat(),
+        'end_of_life': end_of_life,
+        'release_manager': metadata.release_manager,
+    }
diff --git a/release_engineering/update_release_schedules.py b/release_engineering/update_release_schedules.py
@@ -0,0 +1,167 @@
+"""Update release schedules in PEPs.
+
+The ``python-releases.toml`` data is treated as authoritative for the given
+versions in ``VERSIONS_TO_REGENERATE``. Each PEP must contain markers for the
+start and end of each release schedule (feature, bugfix, and security, as
+appropriate). These are:
+
+    .. feature release schedule
+    .. bugfix release schedule
+    .. security release schedule
+    .. end of schedule
+
+This script will use the dates in the [[release."{version}"]] tables to create
+and update the release schedule lists in each PEP.
+
+Optionally, to add a comment or note to a particular release, use the ``note``
+field, which will append the given text in brackets to the relevant line.
+
+Usage:
+
+    $ python -m release_engineering update-peps
+    $ # or
+    $ make regen-all
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+from release_engineering import (
+    PEP_ROOT,
+    ReleaseInfo,
+    VersionMetadata,
+    load_python_releases,
+)
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from release_engineering import ReleaseSchedules, ReleaseState, VersionMetadata
+
+TODAY = dt.date.today()
+
+VERSIONS_TO_REGENERATE = (
+    '3.8',
+    '3.9',
+    '3.10',
+    '3.11',
+    '3.12',
+    '3.13',
+    '3.14',
+)
+
+
+def update_peps() -> None:
+    python_releases = load_python_releases()
+    for version in VERSIONS_TO_REGENERATE:
+        metadata = python_releases.metadata[version]
+        schedules = create_schedules(
+            version,
+            python_releases.releases[version],
+            metadata.start_of_development,
+            metadata.end_of_bugfix,
+        )
+        update_pep(metadata, schedules)
+
+
+def create_schedules(
+    version: str,
+    releases: list[ReleaseInfo],
+    start_of_development: dt.date,
+    bugfix_ends: dt.date,
+) -> ReleaseSchedules:
+    schedules: ReleaseSchedules = {
+        ('feature', 'actual'): [],
+        ('feature', 'expected'): [],
+        ('bugfix', 'actual'): [],
+        ('bugfix', 'expected'): [],
+        ('security', 'actual'): [],
+    }
+
+    # first entry into the dictionary
+    db_state: ReleaseState = 'actual' if TODAY >= start_of_development else 'expected'
+    schedules['feature', db_state].append(
+        ReleaseInfo(
+            stage=f'{version} development begins',
+            state=db_state,
+            date=start_of_development,
+        )
+    )
+
+    for release_info in releases:
+        if release_info.stage.startswith(f'{version}.0'):
+            schedules['feature', release_info.state].append(release_info)
+        elif release_info.date <= bugfix_ends:
+            schedules['bugfix', release_info.state].append(release_info)
+        else:
+            assert release_info.state == 'actual', release_info
+            schedules['security', release_info.state].append(release_info)
+
+    return schedules
+
+
+def update_pep(metadata: VersionMetadata, schedules: ReleaseSchedules) -> None:
+    pep_path = PEP_ROOT.joinpath(f'pep-{metadata.pep:0>4}.rst')
+    pep_lines = iter(pep_path.read_text(encoding='utf-8').splitlines())
+    output_lines: list[str] = []
+    schedule_name = ''
+    for line in pep_lines:
+        output_lines.append(line)
+        if line.startswith('.. ') and 'schedule' in line:
+            schedule_name = line.split()[1]
+            assert schedule_name in {'feature', 'bugfix', 'security'}
+            output_lines += generate_schedule_lists(
+                schedules,
+                schedule_name=schedule_name,
+                feature_freeze_date=metadata.feature_freeze,
+            )
+
+            # skip source lines until the end of schedule marker
+            while True:
+                line = next(pep_lines, None)
+                if line == '.. end of schedule':
+                    output_lines.append(line)
+                    break
+                if line is None:
+                    raise ValueError('No end of schedule marker found!')
+
+    if not schedule_name:
+        raise ValueError('No schedule markers found!')
+
+    with open(pep_path, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(output_lines))
+        f.write('\n')  # trailing newline
+
+
+def generate_schedule_lists(
+    schedules: ReleaseSchedules,
+    *,
+    schedule_name: str,
+    feature_freeze_date: dt.date = dt.date.min,
+) -> Iterator[str]:
+    state: ReleaseState
+    for state in 'actual', 'expected':
+        if not schedules.get((schedule_name, state)):
+            continue
+
+        yield ''
+        if schedule_name != 'security':
+            yield f'{state.title()}:'
+            yield ''
+        for release_info in schedules[schedule_name, state]:
+            yield release_info.schedule_bullet
+            if release_info.note:
+                yield f'  ({release_info.note})'
+            if release_info.date == feature_freeze_date:
+                yield '  (No new features beyond this point.)'
+
+    if schedule_name == 'bugfix':
+        yield '  (final regular bugfix release with binary installers)'
+
+    yield ''
+
+
+if __name__ == '__main__':
+    update_peps()