FilesExpand file tree

v2.1.1

/

update_readme_snippets.py

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

executable file

·

151 lines (119 loc) · 4.78 KB

v2.1.1

/

update_readme_snippets.py

Copy path

Top

File metadata and controls

• Code
• Blame

executable file

·

151 lines (119 loc) · 4.78 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

#!/usr/bin/env python3

"""Update README.md with live code snippets from example files.

This script finds specially marked code blocks in README.md and updates them

with the actual code from the referenced files.

Usage:

python scripts/update_readme_snippets.py

python scripts/update_readme_snippets.py --check # Check mode for CI

"""

import argparse

import re

import sys

from pathlib import Path

def get_github_url(file_path: str) -> str:

"""Generate a GitHub URL for the file.

Args:

file_path: Path to the file relative to repo root

Returns:

GitHub URL

"""

base_url = "https://github.com/modelcontextprotocol/python-sdk/blob/main"

return f"{base_url}/{file_path}"

def process_snippet_block(match: re.Match[str], check_mode: bool = False) -> str:

"""Process a single snippet-source block.

Args:

match: The regex match object

check_mode: If True, return original if no changes needed

Returns:

The updated block content

"""

full_match = match.group(0)

indent = match.group(1)

file_path = match.group(2)

try:

code = Path(file_path).read_text(encoding="utf-8").rstrip()

github_url = get_github_url(file_path)

# Build the replacement block

indented_code = code.replace("\n", f"\n{indent}")

replacement = f"""{indent}<!-- snippet-source {file_path} -->

{indent}```python

{indent}{indented_code}

{indent}```

{indent}_Full example: [{file_path}]({github_url})_

{indent}<!-- /snippet-source -->"""

# In check mode, only check if code has changed

if check_mode:

# Extract existing code from the match

existing_content = match.group(3)

if existing_content is not None:

existing_lines = existing_content.strip().split("\n")

# Find code between ```python and ```

code_lines: list[str] = []

in_code = False

for line in existing_lines:

if line.strip() == "```python":

in_code = True

elif line.strip() == "```":

break

elif in_code:

code_lines.append(line)

existing_code = "\n".join(code_lines).strip()

# Compare with the indented version we would generate

expected_code = code.replace("\n", f"\n{indent}").strip()

if existing_code == expected_code:

return full_match

return replacement

except (OSError, UnicodeDecodeError) as e:

# Fatal, not "warn and keep the stale block": that would let --check pass with exit 0.

sys.exit(f"Error processing {file_path}: {e}")

def update_readme_snippets(check_mode: bool = False) -> bool:

"""Update code snippets in README.md with live code from source files.

Args:

check_mode: If True, only check if updates are needed without modifying

Returns:

True if file is up to date or was updated, False if check failed

"""

readme_path = Path("README.md")

if not readme_path.exists():

print(f"Error: README file not found: {readme_path}")

return False

content = readme_path.read_text(encoding="utf-8")

original_content = content

# Pattern to match snippet-source blocks

# Matches: <!-- snippet-source path/to/file.py -->

# ... any content ...

# <!-- /snippet-source -->

pattern = r"^(\s*)<!-- snippet-source ([^\s]+) -->\n" r"(.*?)" r"^\1<!-- /snippet-source -->"

# Process all snippet-source blocks

updated_content = re.sub(

pattern, lambda m: process_snippet_block(m, check_mode), content, flags=re.MULTILINE | re.DOTALL

)

if check_mode:

if updated_content != original_content:

print(

f"Error: {readme_path} has outdated code snippets. "

"Run 'python scripts/update_readme_snippets.py' to update."

)

return False

else:

print(f"{readme_path} code snippets are up to date")

return True

else:

if updated_content != original_content:

readme_path.write_text(updated_content, encoding="utf-8")

print(f"Updated {readme_path}")

else:

print(f"{readme_path} already up to date")

return True

def main():

"""Main entry point."""

parser = argparse.ArgumentParser(description="Update README code snippets from source files")

parser.add_argument(

"--check", action="store_true", help="Check mode - verify snippets are up to date without modifying"

)

args = parser.parse_args()

success = update_readme_snippets(check_mode=args.check)

if not success:

sys.exit(1)

if __name__ == "__main__":

main()