Debian Codegraph @

docs/_ext/github_links.py

raw
1 import ast
2 import functools
3 import importlib.util
4 import pathlib
5
6
7 class CodeLocator(ast.NodeVisitor):
8 def __init__(self):
9 super().__init__()
10 self.current_path = []
11 self.node_line_numbers = {}
12 self.import_locations = {}
13
14 @classmethod
15 def from_code(cls, code):
16 tree = ast.parse(code)
17 locator = cls()
18 locator.visit(tree)
19 return locator
20
21 def visit_node(self, node):
22 self.current_path.append(node.name)
23 self.node_line_numbers[".".join(self.current_path)] = node.lineno
24 self.generic_visit(node)
25 self.current_path.pop()
26
27 def visit_FunctionDef(self, node):
28 self.visit_node(node)
29
30 def visit_ClassDef(self, node):
31 self.visit_node(node)
32
33 def visit_ImportFrom(self, node):
34 for alias in node.names:
35 if alias.asname:
36 # Exclude linking aliases (`import x as y`) to avoid confusion
37 # when clicking a source link to a differently named entity.
38 continue
39 if alias.name == "*":
40 # Resolve wildcard imports.
41 file = module_name_to_file_path(node.module)
42 file_contents = file.read_text(encoding="utf-8")
43 locator = CodeLocator.from_code(file_contents)
44 self.import_locations.update(locator.import_locations)
45 self.import_locations.update(
46 {n: node.module for n in locator.node_line_numbers if "." not in n}
47 )
48 else:
49 self.import_locations[alias.name] = ("." * node.level) + (
50 node.module or ""
51 )
52
53
54 @functools.lru_cache(maxsize=1024)
55 def get_locator(file):
56 file_contents = file.read_text(encoding="utf-8")
57 return CodeLocator.from_code(file_contents)
58
59
60 class CodeNotFound(Exception):
61 pass
62
63
64 def module_name_to_file_path(module_name):
65 # Avoid importlib machinery as locating a module involves importing its
66 # parent, which would trigger import side effects.
67
68 for suffix in [".py", "/__init__.py"]:
69 file_path = pathlib.Path(__file__).parents[2] / (
70 module_name.replace(".", "/") + suffix
71 )
72 if file_path.exists():
73 return file_path
74
75 raise CodeNotFound
76
77
78 def get_path_and_line(module, fullname):
79 path = module_name_to_file_path(module_name=module)
80
81 locator = get_locator(path)
82
83 lineno = locator.node_line_numbers.get(fullname)
84
85 if lineno is not None:
86 return path, lineno
87
88 imported_object = fullname.split(".", maxsplit=1)[0]
89 try:
90 imported_path = locator.import_locations[imported_object]
91 except KeyError:
92 raise CodeNotFound
93
94 # From a statement such as:
95 # from . import y.z
96 # - either y.z might be an object in the parent module
97 # - or y might be a module, and z be an object in y
98 # also:
99 # - either the current file is x/__init__.py, and z would be in x.y
100 # - or the current file is x/a.py, and z would be in x.a.y
101 if path.name != "__init__.py":
102 # Look in parent module
103 module = module.rsplit(".", maxsplit=1)[0]
104 try:
105 imported_module = importlib.util.resolve_name(
106 name=imported_path, package=module
107 )
108 except ImportError as error:
109 raise ImportError(
110 f"Could not import '{imported_path}' in '{module}'."
111 ) from error
112 try:
113 return get_path_and_line(module=imported_module, fullname=fullname)
114 except CodeNotFound:
115 if "." not in fullname:
116 raise
117
118 first_element, remainder = fullname.rsplit(".", maxsplit=1)
119 # Retrying, assuming the first element of the fullname is a module.
120 return get_path_and_line(
121 module=f"{imported_module}.{first_element}", fullname=remainder
122 )
123
124
125 def get_branch(version, next_version):
126 if version == next_version:
127 return "main"
128 else:
129 return f"stable/{version}.x"
130
131
132 def github_linkcode_resolve(domain, info, *, version, next_version):
133 if domain != "py":
134 return None
135
136 if not (module := info["module"]):
137 return None
138
139 try:
140 path, lineno = get_path_and_line(module=module, fullname=info["fullname"])
141 except CodeNotFound:
142 return None
143
144 branch = get_branch(version=version, next_version=next_version)
145 relative_path = path.relative_to(pathlib.Path(__file__).parents[2])
146 # Use "/" explicitly to join the path parts since str(file), on Windows,
147 # uses the Windows path separator which is incorrect for URLs.
148 url_path = "/".join(relative_path.parts)
149 return f"https://github.com/django/django/blob/{branch}/{url_path}#L{lineno}"