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
|
#!/usr/bin/env python
from __future__ import annotations
import functools
import glob
import os
import pathlib
import re
import sys
import typing as t
REPO_ROOT = pathlib.Path(__file__).parent.parent
_ALL_NAME_PATTERN = re.compile(r'\s+"(\w+)",?')
PACKAGE_LOCS_TO_SCAN = (
"globus_sdk/__init__.pyi",
"globus_sdk/login_flows/",
"globus_sdk/gare/",
"globus_sdk/globus_app/",
"globus_sdk/scopes/",
"globus_sdk/response.py",
"globus_sdk/_testing/",
)
DEPRECATED_NAMES = {
"ComputeFunctionDocument",
"ComputeFunctionMetadata",
"TimerAPIError",
"TimerClient",
"TimerScopes",
}
def load_docs() -> dict[str, str]:
all_docs = {}
for file in glob.glob("docs/**/*.rst", recursive=True):
with open(file) as f:
all_docs[file] = f.read()
return all_docs
def iter_all_documented_names() -> t.Iterable[str]:
# names under these directives
#
# .. autoclass:: <name>
# .. autoclass:: <name>(<args>)
# .. autofunction:: <name>
# .. autoexception:: <name>
# .. autodata:: <name>
autodoc_pattern = re.compile(
r"""
^\.\.\s+auto(?:class|function|exception|data)::\s+ # auto-directive (uncaptured)
(?:\w+\.)*(\w+)(?:\(.*\))?$ # symbol name (captured)
""",
flags=re.MULTILINE | re.X,
)
# names under these directives
#
# .. class:: <name>
# .. py:data:: <name>
pydoc_pattern = re.compile(
r"""
^\.\.\s+(?:py:data|class)::\s+ # directive
(?:\w+\.)*(\w+)(?:\(.*\))?$ # symbol name (captured)
""",
flags=re.MULTILINE | re.X,
)
for data in load_docs().values():
for match in autodoc_pattern.finditer(data):
yield match.group(1)
for match in pydoc_pattern.finditer(data):
yield match.group(1)
@functools.lru_cache
def all_documented_names() -> frozenset[str]:
return frozenset(iter_all_documented_names())
def is_documented(name: str) -> bool:
return name in all_documented_names()
def get_names_from_all_list(file_path: str) -> list[str]:
with open(f"src/{file_path}") as fp:
contents = fp.readlines()
names: list[str] = []
found_all = False
for line in contents:
if found_all:
if line.strip() == ")":
break
# Extract the actual symbol from the line.
# i.e., ' "Foo",\n' -> 'Foo'
name_match = _ALL_NAME_PATTERN.match(line)
if name_match is not None:
names.append(name_match.group(1))
else:
if line.strip() == "__all__ = (":
found_all = True
else:
continue
return [n for n in names if not n.startswith("_")]
def ensure_exports_are_documented() -> bool:
success = True
used_deprecations = set()
for loc in PACKAGE_LOCS_TO_SCAN:
if loc.endswith("/"):
loc = f"{loc}/__init__.py"
for name in get_names_from_all_list(loc):
if name in DEPRECATED_NAMES:
used_deprecations.add(name)
continue
if not is_documented(name):
print(f"'src/{loc}::{name}' was not found in doc directives")
success = False
if unused_deprecations := (DEPRECATED_NAMES - used_deprecations):
print(f"unused deprecations: {unused_deprecations}")
success = False
return success
if __name__ == "__main__":
os.chdir(REPO_ROOT)
if not ensure_exports_are_documented():
exit(1)
sys.exit(0)
|
