Improve type annotations for versions and languages (#253)

AA-Turner · web-flow · commit e096701ea6bf · 2025-04-11T02:17:57.000+01:00
diff --git a/build_docs.py b/build_docs.py
@@ -33,7 +33,6 @@
 import sys
 from argparse import ArgumentParser, Namespace
 from bisect import bisect_left as bisect
-from collections.abc import Iterable, Sequence
 from contextlib import contextmanager, suppress
 from dataclasses import dataclass
 from datetime import datetime as dt, timezone
@@ -42,14 +41,21 @@
 from pathlib import Path
 from string import Template
 from time import perf_counter, sleep
-from typing import Literal
 from urllib.parse import urljoin
 
 import jinja2
 import tomlkit
 import urllib3
 import zc.lockfile
 
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from typing import Literal, TypeAlias
+
+    Versions: TypeAlias = Sequence["Version"]
+    Languages: TypeAlias = Sequence["Language"]
+
 try:
     from os import EX_OK, EX_SOFTWARE as EX_FAILURE
 except ImportError:
@@ -170,7 +176,7 @@ def picker_label(self):
             return f"pre ({self.name})"
         return self.name
 
-    def setup_indexsidebar(self, versions: Sequence[Version], dest_path: Path):
+    def setup_indexsidebar(self, versions: Versions, dest_path: Path):
         """Build indexsidebar.html for Sphinx."""
         template_path = HERE / "templates" / "indexsidebar.html"
         template = jinja2.Template(template_path.read_text(encoding="UTF-8"))
@@ -388,9 +394,7 @@ def edit(file: Path):
     temporary.rename(file)
 
 
-def setup_switchers(
-    versions: Sequence[Version], languages: Sequence[Language], html_root: Path
-):
+def setup_switchers(versions: Versions, languages: Languages, html_root: Path):
     """Setup cross-links between CPython versions:
     - Cross-link various languages in a language switcher
     - Cross-link various versions in a version switcher
@@ -462,9 +466,9 @@ class DocBuilder:
     """Builder for a CPython version and a language."""
 
     version: Version
-    versions: Sequence[Version]
+    versions: Versions
     language: Language
-    languages: Sequence[Language]
+    languages: Languages
     cpython_repo: Repository
     build_root: Path
     www_root: Path
@@ -1070,7 +1074,7 @@ def build_docs(args) -> bool:
     return all_built_successfully
 
 
-def parse_versions_from_devguide(http: urllib3.PoolManager) -> list[Version]:
+def parse_versions_from_devguide(http: urllib3.PoolManager) -> Versions:
     releases = http.request(
         "GET",
         "https://raw.githubusercontent.com/"
@@ -1082,7 +1086,7 @@ def parse_versions_from_devguide(http: urllib3.PoolManager) -> list[Version]:
     return versions
 
 
-def parse_languages_from_config() -> list[Language]:
+def parse_languages_from_config() -> Languages:
     """Read config.toml to discover languages to build."""
     config = tomlkit.parse((HERE / "config.toml").read_text(encoding="UTF-8"))
     defaults = config["defaults"]
@@ -1103,9 +1107,7 @@ def parse_languages_from_config() -> list[Language]:
     ]
 
 
-def build_sitemap(
-    versions: Iterable[Version], languages: Iterable[Language], www_root: Path, group
-):
+def build_sitemap(versions: Versions, languages: Languages, www_root: Path, group):
     """Build a sitemap with all live versions and translations."""
     if not www_root.exists():
         logging.info("Skipping sitemap generation (www root does not even exist).")
@@ -1155,8 +1157,8 @@ def copy_robots_txt(
 def major_symlinks(
     www_root: Path,
     group: str,
-    versions: Iterable[Version],
-    languages: Iterable[Language],
+    versions: Versions,
+    languages: Languages,
     skip_cache_invalidation: bool,
     http: urllib3.PoolManager,
 ) -> None:
