From f2a6c052073caaa3c527f48a4d43a1f9cd2dcde7 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 11 Apr 2025 02:16:06 +0100
Subject: [PATCH 1/2] Improve type annotations for versions and languages
---
build_docs.py | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)
diff --git a/build_docs.py b/build_docs.py
index fa0ce44..d802590 100755
--- 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,7 +41,6 @@
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
@@ -50,6 +48,14 @@
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"))
@@ -389,7 +395,7 @@ def edit(file: Path):
def setup_switchers(
- versions: Sequence[Version], languages: Sequence[Language], html_root: Path
+ versions: Versions, languages: Languages, html_root: Path
):
"""Setup cross-links between CPython versions:
- Cross-link various languages in a language switcher
@@ -462,9 +468,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 +1076,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 +1088,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"]
@@ -1104,7 +1110,7 @@ def parse_languages_from_config() -> list[Language]:
def build_sitemap(
- versions: Iterable[Version], languages: Iterable[Language], www_root: Path, group
+ versions: Versions, languages: Languages, www_root: Path, group
):
"""Build a sitemap with all live versions and translations."""
if not www_root.exists():
@@ -1155,10 +1161,10 @@ 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,
+ http: urllib3.PoolManager
) -> None:
"""Maintains the /2/ and /3/ symlinks for each language.
From ae92f3611a8fdba7935dfeb7a5e7241770706ece Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Fri, 11 Apr 2025 02:16:59 +0100
Subject: [PATCH 2/2] Format
---
build_docs.py | 14 +++++---------
1 file changed, 5 insertions(+), 9 deletions(-)
diff --git a/build_docs.py b/build_docs.py
index d802590..21b3e6a 100755
--- a/build_docs.py
+++ b/build_docs.py
@@ -53,8 +53,8 @@
from collections.abc import Sequence
from typing import Literal, TypeAlias
- Versions: TypeAlias = Sequence['Version']
- Languages: TypeAlias = Sequence['Language']
+ Versions: TypeAlias = Sequence["Version"]
+ Languages: TypeAlias = Sequence["Language"]
try:
from os import EX_OK, EX_SOFTWARE as EX_FAILURE
@@ -394,9 +394,7 @@ def edit(file: Path):
temporary.rename(file)
-def setup_switchers(
- versions: Versions, languages: Languages, 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
@@ -1109,9 +1107,7 @@ def parse_languages_from_config() -> Languages:
]
-def build_sitemap(
- versions: Versions, languages: Languages, 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).")
@@ -1164,7 +1160,7 @@ def major_symlinks(
versions: Versions,
languages: Languages,
skip_cache_invalidation: bool,
- http: urllib3.PoolManager
+ http: urllib3.PoolManager,
) -> None:
"""Maintains the /2/ and /3/ symlinks for each language.
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy