format.py 8.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. # -*- coding: utf-8 -*-
  2. import re
  3. import sys
  4. from string import punctuation
  5. from typing import List, Tuple, Dict
  6. # Temporary replacement
  7. # The descriptions that contain () at the end must adapt to the new policy later
  8. punctuation = punctuation.replace('()', '')
  9. anchor = '###'
  10. auth_keys = ['apiKey', 'OAuth', 'X-Mashape-Key', 'User-Agent', 'No']
  11. https_keys = ['Yes', 'No']
  12. cors_keys = ['Yes', 'No', 'Unknown']
  13. index_title = 0
  14. index_desc = 1
  15. index_auth = 2
  16. index_https = 3
  17. index_cors = 4
  18. num_segments = 5
  19. min_entries_per_category = 3
  20. max_description_length = 100
  21. anchor_re = re.compile(anchor + '\s(.+)')
  22. category_title_in_index_re = re.compile('\*\s\[(.*)\]')
  23. link_re = re.compile('\[(.+)\]\((http.*)\)')
  24. # Type aliases
  25. APIList = List[str]
  26. Categories = Dict[str, APIList]
  27. CategoriesLineNumber = Dict[str, int]
  28. def error_message(line_number: int, message: str) -> str:
  29. line = line_number + 1
  30. return f'(L{line:03d}) {message}'
  31. def get_categories_content(contents: List[str]) -> Tuple[Categories, CategoriesLineNumber]:
  32. categories = {}
  33. category_line_num = {}
  34. for line_num, line_content in enumerate(contents):
  35. if line_content.startswith(anchor):
  36. category = line_content.split(anchor)[1].strip()
  37. categories[category] = []
  38. category_line_num[category] = line_num
  39. continue
  40. if not line_content.startswith('|') or line_content.startswith('|---'):
  41. continue
  42. raw_title = [
  43. raw_content.strip() for raw_content in line_content.split('|')[1:-1]
  44. ][0]
  45. title_match = link_re.match(raw_title)
  46. if title_match:
  47. title = title_match.group(1).upper()
  48. categories[category].append(title)
  49. return (categories, category_line_num)
  50. def check_alphabetical_order(lines: List[str]) -> List[str]:
  51. err_msgs = []
  52. categories, category_line_num = get_categories_content(contents=lines)
  53. for category, api_list in categories.items():
  54. if sorted(api_list) != api_list:
  55. err_msg = error_message(
  56. category_line_num[category],
  57. f'{category} category is not alphabetical order'
  58. )
  59. err_msgs.append(err_msg)
  60. return err_msgs
  61. def check_title(line_num: int, raw_title: str) -> List[str]:
  62. err_msgs = []
  63. title_match = link_re.match(raw_title)
  64. # url should be wrapped in "[TITLE](LINK)" Markdown syntax
  65. if not title_match:
  66. err_msg = error_message(line_num, 'Title syntax should be "[TITLE](LINK)"')
  67. err_msgs.append(err_msg)
  68. else:
  69. # do not allow "... API" in the entry title
  70. title = title_match.group(1)
  71. if title.upper().endswith(' API'):
  72. err_msg = error_message(line_num, 'Title should not end with "... API". Every entry is an API here!')
  73. err_msgs.append(err_msg)
  74. return err_msgs
  75. def check_description(line_num: int, description: str) -> List[str]:
  76. err_msgs = []
  77. first_char = description[0]
  78. if first_char.upper() != first_char:
  79. err_msg = error_message(line_num, 'first character of description is not capitalized')
  80. err_msgs.append(err_msg)
  81. last_char = description[-1]
  82. if last_char in punctuation:
  83. err_msg = error_message(line_num, f'description should not end with {last_char}')
  84. err_msgs.append(err_msg)
  85. desc_length = len(description)
  86. if desc_length > max_description_length:
  87. err_msg = error_message(line_num, f'description should not exceed {max_description_length} characters (currently {desc_length})')
  88. err_msgs.append(err_msg)
  89. return err_msgs
  90. def check_auth(line_num: int, auth: str) -> List[str]:
  91. err_msgs = []
  92. backtick = '`'
  93. if auth != 'No' and (not auth.startswith(backtick) or not auth.endswith(backtick)):
  94. err_msg = error_message(line_num, 'auth value is not enclosed with `backticks`')
  95. err_msgs.append(err_msg)
  96. if auth.replace(backtick, '') not in auth_keys:
  97. err_msg = error_message(line_num, f'{auth} is not a valid Auth option')
  98. err_msgs.append(err_msg)
  99. return err_msgs
  100. def check_https(line_num: int, https: str) -> List[str]:
  101. err_msgs = []
  102. if https not in https_keys:
  103. err_msg = error_message(line_num, f'{https} is not a valid HTTPS option')
  104. err_msgs.append(err_msg)
  105. return err_msgs
  106. def check_cors(line_num: int, cors: str) -> List[str]:
  107. err_msgs = []
  108. if cors not in cors_keys:
  109. err_msg = error_message(line_num, f'{cors} is not a valid CORS option')
  110. err_msgs.append(err_msg)
  111. return err_msgs
  112. def check_entry(line_num: int, segments: List[str]) -> List[str]:
  113. raw_title = segments[index_title]
  114. description = segments[index_desc]
  115. auth = segments[index_auth]
  116. https = segments[index_https]
  117. cors = segments[index_cors]
  118. title_err_msgs = check_title(line_num, raw_title)
  119. desc_err_msgs = check_description(line_num, description)
  120. auth_err_msgs = check_auth(line_num, auth)
  121. https_err_msgs = check_https(line_num, https)
  122. cors_err_msgs = check_cors(line_num, cors)
  123. err_msgs = [
  124. *title_err_msgs,
  125. *desc_err_msgs,
  126. *auth_err_msgs,
  127. *https_err_msgs,
  128. *cors_err_msgs
  129. ]
  130. return err_msgs
  131. def check_file_format(lines: List[str]) -> List[str]:
  132. err_msgs = []
  133. category_title_in_index = []
  134. alphabetical_err_msgs = check_alphabetical_order(lines)
  135. err_msgs.extend(alphabetical_err_msgs)
  136. num_in_category = min_entries_per_category + 1
  137. category = ''
  138. category_line = 0
  139. for line_num, line_content in enumerate(lines):
  140. category_title_match = category_title_in_index_re.match(line_content)
  141. if category_title_match:
  142. category_title_in_index.append(category_title_match.group(1))
  143. # check each category for the minimum number of entries
  144. if line_content.startswith(anchor):
  145. category_match = anchor_re.match(line_content)
  146. if category_match:
  147. if category_match.group(1) not in category_title_in_index:
  148. err_msg = error_message(line_num, f'category header ({category_match.group(1)}) not added to Index section')
  149. err_msgs.append(err_msg)
  150. else:
  151. err_msg = error_message(line_num, 'category header is not formatted correctly')
  152. err_msgs.append(err_msg)
  153. if num_in_category < min_entries_per_category:
  154. err_msg = error_message(category_line, f'{category} category does not have the minimum {min_entries_per_category} entries (only has {num_in_category})')
  155. err_msgs.append(err_msg)
  156. category = line_content.split(' ')[1]
  157. category_line = line_num
  158. num_in_category = 0
  159. continue
  160. # skips lines that we do not care about
  161. if not line_content.startswith('|') or line_content.startswith('|---'):
  162. continue
  163. num_in_category += 1
  164. segments = line_content.split('|')[1:-1]
  165. if len(segments) < num_segments:
  166. err_msg = error_message(line_num, f'entry does not have all the required columns (have {len(segments)}, need {num_segments})')
  167. err_msgs.append(err_msg)
  168. continue
  169. for segment in segments:
  170. # every line segment should start and end with exactly 1 space
  171. if len(segment) - len(segment.lstrip()) != 1 or len(segment) - len(segment.rstrip()) != 1:
  172. err_msg = error_message(line_num, 'each segment must start and end with exactly 1 space')
  173. err_msgs.append(err_msg)
  174. segments = [segment.strip() for segment in segments]
  175. entry_err_msgs = check_entry(line_num, segments)
  176. err_msgs.extend(entry_err_msgs)
  177. return err_msgs
  178. def main(filename: str) -> None:
  179. with open(filename, mode='r', encoding='utf-8') as file:
  180. lines = list(line.rstrip() for line in file)
  181. file_format_err_msgs = check_file_format(lines)
  182. if file_format_err_msgs:
  183. for err_msg in file_format_err_msgs:
  184. print(err_msg)
  185. sys.exit(1)
  186. if __name__ == '__main__':
  187. num_args = len(sys.argv)
  188. if num_args < 2:
  189. print('No .md file passed (file should contain Markdown table syntax)')
  190. sys.exit(1)
  191. filename = sys.argv[1]
  192. main(filename)