Coverage for scripts/pin_readme_links.py: 100%

41 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-12 12:29 +0000

1"""Pin the README's repository links to the release tag at build time (ADR 0012). 

2 

3Pinned here, not in git: master's README must keep linking documents added 

4after the last tag. Every refusal fails the publish, because PyPI keeps a 

5release's README forever and an unpinned link would go stale in silence. 

6""" 

7 

8from __future__ import annotations 

9 

10import re 

11import sys 

12from pathlib import Path 

13 

14REPO = "https://github.com/Akinzou/MetaTrader5-Python" 

15# What ends a ref in a URL; `\b` would also stop at `-` and `.` and turn 

16# `master-old` into `v3.0.1-old`, a link that 404s and passes every check. 

17_END = r"(?=[/#?)\s\]>\"'`]|$)" 

18_REF = r"([^/#?)\s\]>\"'`]+)" 

19# Owner and repository ignore case on GitHub, branch names do not: `blob/Master` 

20# 404s in git too, and is reported below instead of repaired here. 

21MASTER_LINK = re.compile(f"(?i:{re.escape(REPO)})" + r"/(blob|tree)/master" + _END) 

22# Every way a link names a ref of this repository. Only the ref segment is 

23# read, so `master` in a file name or a badge's query string is no ref. 

24REF_LINKS = [ 

25 re.compile(f"(?i:{p})" + _REF) 

26 for p in ( 

27 r"github\.com/akinzou/metatrader5-python/(?:blob|tree|raw|blame|edit|commits)/", 

28 r"github\.com/akinzou/metatrader5-python/archive/(?:refs/(?:heads|tags)/)?", 

29 r"raw\.githubusercontent\.com/akinzou/metatrader5-python/", 

30 r"metatrader5-python\.git@", 

31 ) 

32] 

33PROJECT_TABLE = re.compile(r"^\[project\]$(.*?)(?=^\[|\Z)", re.MULTILINE | re.DOTALL) 

34VERSION = re.compile(r'^version = "([^"]+)"$', re.MULTILINE) 

35 

36 

37def project_version(pyproject: Path) -> str | None: 

38 """`version` of the [project] table; a regex because tomllib is 3.11+.""" 

39 if not pyproject.is_file(): 

40 return None 

41 table = PROJECT_TABLE.search(pyproject.read_text(encoding="utf-8")) 

42 found = VERSION.search(table.group(1)) if table else None 

43 return found.group(1) if found else None 

44 

45 

46def unpinned(text: str, tag: str) -> list[str]: 

47 """Links naming any ref but `tag`: master, main, HEAD, a branch, ...""" 

48 # A tag archive is `<tag>.zip`; everything else names the ref alone. 

49 return [ 

50 m.group(0) 

51 for p in REF_LINKS 

52 for m in p.finditer(text) 

53 if m.group(1) not in (tag, f"{tag}.zip", f"{tag}.tar.gz") 

54 ] 

55 

56 

57def main(argv: list[str]) -> int: 

58 version = project_version(Path("pyproject.toml")) 

59 if version is None: 

60 print("pyproject.toml: no `version` in the [project] table") 

61 return 1 

62 tag = f"v{version}" 

63 # The full ref, not the name: a branch called v3.0.1 must not pass for the tag. 

64 if argv != [f"refs/tags/{tag}"]: 

65 print(f"build from refs/tags/{tag}, not {' '.join(argv) or 'nothing'}") 

66 return 1 

67 readme = Path("README.md") 

68 # Bytes: Path.read_text has no newline= before Python 3.13, and text mode 

69 # would turn LF into CRLF when run on Windows. 

70 text = readme.read_bytes().decode("utf-8") 

71 pinned, count = MASTER_LINK.subn(lambda m: f"{REPO}/{m.group(1)}/{tag}", text) 

72 if count == 0: 

73 # A renamed repository or a changed link style would otherwise ship 

74 # master links to PyPI. 

75 print("README.md: no master links to this repository to pin") 

76 return 1 

77 left = unpinned(pinned, tag) 

78 if left: 

79 print(f"README.md links not pinned to {tag}: " + ", ".join(left)) 

80 return 1 

81 readme.write_bytes(pinned.encode("utf-8")) 

82 print(f"README.md: {count} link(s) pinned to {tag}") 

83 return 0 

84 

85 

86if __name__ == "__main__": 

87 sys.exit(main(sys.argv[1:]))