render_readmes.py

#!/usr/bin/env python3
"""Render the browsable catalog sections in the English and Chinese READMEs."""

from __future__ import annotations

import argparse
import html
import sys
from datetime import date, datetime
from pathlib import Path
from typing import Any, Mapping, Sequence
from urllib.parse import quote

try:
    from tools.catalog import CatalogLoadError, load_catalog, validate_catalog
except ModuleNotFoundError:  # Direct ``python tools/render_readmes.py`` execution.
    from catalog import CatalogLoadError, load_catalog, validate_catalog


ROOT_DIR = Path(__file__).resolve().parent.parent
DEFAULT_CATALOG = ROOT_DIR / "catalog"
START_MARKER = "<!-- catalog-index:start -->"
END_MARKER = "<!-- catalog-index:end -->"

LEVEL_LABELS = {
    "en": {
        "beginner": "Beginner",
        "intermediate": "Intermediate",
        "advanced": "Advanced",
        "all-levels": "All levels",
    },
    "zh": {
        "beginner": "入门",
        "intermediate": "进阶",
        "advanced": "高级",
        "all-levels": "所有阶段",
    },
}
LANGUAGE_LABELS = {
    "en": {"en": "English", "zh": "Chinese", "multilingual": "Multilingual"},
    "zh": {"en": "英语", "zh": "中文", "multilingual": "多语言"},
}
SOURCE_LABELS = {
    "en": {
        "official-docs": "Official docs",
        "official-standard": "Official standard",
        "official-project": "Official project",
    },
    "zh": {
        "official-docs": "官方文档",
        "official-standard": "正式标准",
        "official-project": "官方项目",
    },
}


def _text(value: Any) -> str:
    escaped = html.escape(str(value), quote=False)
    return (
        escaped.replace("\\", "\\\\")
        .replace("|", "\\|")
        .replace("[", "\\[")
        .replace("]", "\\]")
        .replace("\n", " ")
    )


def _url(value: Any) -> str:
    return quote(str(value), safe=":/?&=#%@+;,~-._")


def _date_text(value: Any) -> str:
    if isinstance(value, datetime):
        return value.date().isoformat()
    if isinstance(value, date):
        return value.isoformat()
    return _text(value)


def _resource_meta(resource: Mapping[str, Any], lang: str) -> str:
    source = SOURCE_LABELS[lang][str(resource["source_type"])]
    featured = "Featured" if lang == "en" else "精选"
    if resource.get("featured"):
        return f"{source} · {featured}"
    return source


def _access_and_risk(resource: Mapping[str, Any], lang: str) -> str:
    if lang == "zh":
        access = (
            "通常需要 API Key" if resource["requires_key"] else "无需 API Key"
        )
        risk = (
            "检查权限与副作用" if resource["risk"] == "medium" else "低风险"
        )
    else:
        access = (
            "API key typically required"
            if resource["requires_key"]
            else "No API key"
        )
        risk = (
            "Review permissions and side effects"
            if resource["risk"] == "medium"
            else "Low risk"
        )
    return f"{access}<br>{risk}"


def render_catalog_index(data: Mapping[str, Any], *, lang: str) -> str:
    if lang not in {"en", "zh"}:
        raise ValueError("lang must be 'en' or 'zh'")

    metadata = data["catalog"]
    paths: Sequence[Mapping[str, Any]] = metadata["paths"]
    resources: Sequence[Mapping[str, Any]] = data["resources"]
    engineering_depth_count = sum(
        resource["level"] in {"intermediate", "advanced"}
        for resource in resources
    )
    lines: list[str] = [
        START_MARKER,
        "<!-- Generated by tools/render_readmes.py; edit catalog/ instead. -->",
    ]

    if lang == "zh":
        review_summary = (
            f"> **{len(resources)} 条已审核资源** · 最近整体审核："
            f"{_date_text(metadata['reviewed_on'])} · "
            f"{engineering_depth_count} 条进阶或高级资源 · 一手来源优先"
        )
        lines.extend(
            [
                review_summary,
                "",
                "### 选择学习路径",
                "",
            ]
        )
    else:
        review_summary = (
            f"> **{len(resources)} reviewed resources** · Catalog reviewed "
            f"{_date_text(metadata['reviewed_on'])} · "
            f"{engineering_depth_count} intermediate or advanced · "
            "Primary sources first"
        )
        lines.extend(
            [
                review_summary,
                "",
                "### Choose a learning path",
                "",
            ]
        )

    for path in paths:
        title = path["title_zh"] if lang == "zh" else path["title_en"]
        summary = path["summary_zh"] if lang == "zh" else path["summary_en"]
        path_resources = [item for item in resources if item["path"] == path["id"]]
        unit = "条资源" if lang == "zh" else "resources"
        lines.append(
            f"- [**{_text(title)}**](#path-{path['id']}) — {_text(summary)} "
            f"({len(path_resources)} {unit})"
        )

    for path in paths:
        title = path["title_zh"] if lang == "zh" else path["title_en"]
        summary = path["summary_zh"] if lang == "zh" else path["summary_en"]
        path_resources = [item for item in resources if item["path"] == path["id"]]
        lines.extend(
            [
                "",
                f'<a id="path-{path["id"]}"></a>',
                f"### {_text(title)}",
                "",
                _text(summary),
                "",
            ]
        )

        if lang == "zh":
            lines.extend(
                [
                    "| 资源 | 为什么值得看 | 难度与语言 | "
                    "访问与风险 | 审核日期 |",
                    "| --- | --- | --- | --- | --- |",
                ]
            )
        else:
            lines.extend(
                [
                    "| Resource | Why it is useful | Level and language | "
                    "Access and risk | Reviewed |",
                    "| --- | --- | --- | --- | --- |",
                ]
            )

        for resource in path_resources:
            why = resource["why_zh"] if lang == "zh" else resource["why_en"]
            level = LEVEL_LABELS[lang][str(resource["level"])]
            language = LANGUAGE_LABELS[lang][str(resource["language"])]
            resource_link = (
                f"[{_text(resource['title'])}]({_url(resource['url'])})"
                f"<br><sub>{_resource_meta(resource, lang)}</sub>"
            )
            lines.append(
                "| "
                + " | ".join(
                    (
                        resource_link,
                        _text(why),
                        f"{level}<br>{language}",
                        _access_and_risk(resource, lang),
                        _date_text(resource["reviewed_on"]),
                    )
                )
                + " |"
            )

    if lang == "zh":
        contribution = (
            "没有找到合适的官方资料？可以[建议资源或报告错误]"
            "(https://github.com/flypythoncom/python/issues/new/choose)。"
        )
        lines.extend(
            [
                "",
                contribution,
                END_MARKER,
            ]
        )
    else:
        contribution = (
            "Missing an important official source? "
            "[Propose a resource or report a correction]"
            "(https://github.com/flypythoncom/python/issues/new/choose)."
        )
        lines.extend(
            [
                "",
                contribution,
                END_MARKER,
            ]
        )
    return "\n".join(lines)


def replace_generated_block(content: str, generated: str) -> str:
    if content.count(START_MARKER) != 1 or content.count(END_MARKER) != 1:
        raise ValueError("README must contain exactly one catalog marker pair")
    before, remainder = content.split(START_MARKER, maxsplit=1)
    _, after = remainder.split(END_MARKER, maxsplit=1)
    return before + generated + after


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--catalog", type=Path, default=DEFAULT_CATALOG)
    parser.add_argument(
        "--check",
        action="store_true",
        help="fail when either generated README section is out of date",
    )
    return parser


def run(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        data = load_catalog(args.catalog)
    except CatalogLoadError as exc:
        print(str(exc), file=sys.stderr)
        return 2

    issues = validate_catalog(data)
    if issues:
        for issue in issues:
            print(f"{issue.location}: {issue.code}: {issue.message}", file=sys.stderr)
        return 1

    targets = ((ROOT_DIR / "README.md", "en"), (ROOT_DIR / "README_cn.md", "zh"))
    stale: list[Path] = []
    for path, lang in targets:
        current = path.read_text(encoding="utf-8")
        try:
            expected = replace_generated_block(
                current, render_catalog_index(data, lang=lang)
            )
        except ValueError as exc:
            print(f"{path}: {exc}", file=sys.stderr)
            return 2
        if current == expected:
            continue
        if args.check:
            stale.append(path)
        else:
            path.write_text(expected, encoding="utf-8")
            print(f"updated {path}")

    if stale:
        for path in stale:
            print(f"generated catalog section is out of date: {path}", file=sys.stderr)
        return 1
    if args.check:
        print("README catalog sections current")
    return 0


def main() -> None:
    raise SystemExit(run())


if __name__ == "__main__":
    main()