| 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}" |