Debian Codegraph @

django/contrib/admindocs/utils.py

raw
1 "Misc. utility functions/classes for admin documentation generator."
2
3 import re
4 from email.errors import HeaderParseError
5 from email.parser import HeaderParser
6 from inspect import cleandoc
7
8 from django.urls import reverse
9 from django.utils.regex_helper import _lazy_re_compile
10 from django.utils.safestring import mark_safe
11
12 try:
13 import docutils.core
14 import docutils.nodes
15 import docutils.parsers.rst.roles
16 import docutils.writers
17 except ImportError:
18 docutils_is_available = False
19 else:
20 docutils_is_available = True
21
22
23 def get_view_name(view_func):
24 if hasattr(view_func, "view_class"):
25 klass = view_func.view_class
26 return f"{klass.__module__}.{klass.__qualname__}"
27 mod_name = view_func.__module__
28 view_name = getattr(view_func, "__qualname__", view_func.__class__.__name__)
29 return mod_name + "." + view_name
30
31
32 def parse_docstring(docstring):
33 """
34 Parse out the parts of a docstring. Return (title, body, metadata).
35 """
36 if not docstring:
37 return "", "", {}
38 docstring = cleandoc(docstring)
39 parts = re.split(r"\n{2,}", docstring)
40 title = parts[0]
41 if len(parts) == 1:
42 body = ""
43 metadata = {}
44 else:
45 parser = HeaderParser()
46 try:
47 metadata = parser.parsestr(parts[-1])
48 except HeaderParseError:
49 metadata = {}
50 body = "\n\n".join(parts[1:])
51 else:
52 metadata = dict(metadata.items())
53 if metadata:
54 body = "\n\n".join(parts[1:-1])
55 else:
56 body = "\n\n".join(parts[1:])
57 return title, body, metadata
58
59
60 def parse_rst(text, default_reference_context, thing_being_parsed=None):
61 """
62 Convert the string from reST to an XHTML fragment.
63 """
64 overrides = {
65 "doctitle_xform": True,
66 "initial_header_level": 3,
67 "default_reference_context": default_reference_context,
68 "link_base": reverse("django-admindocs-docroot").rstrip("/"),
69 "raw_enabled": False,
70 "file_insertion_enabled": False,
71 }
72 thing_being_parsed = thing_being_parsed and "<%s>" % thing_being_parsed
73 # Wrap ``text`` in some reST that sets the default role to ``cmsreference``,
74 # then restores it.
75 source = """
76 .. default-role:: cmsreference
77
78 %s
79
80 .. default-role::
81 """
82 # In docutils < 0.22, the `writer` param must be an instance. Passing a
83 # string writer name like "html" is only supported in 0.22+.
84 writer_instance = docutils.writers.get_writer_class("html")()
85 parts = docutils.core.publish_parts(
86 source % text,
87 source_path=thing_being_parsed,
88 destination_path=None,
89 writer=writer_instance,
90 settings_overrides=overrides,
91 )
92 return mark_safe(parts["fragment"])
93
94
95 #
96 # reST roles
97 #
98 ROLES = {
99 "model": "%s/models/%s/",
100 "view": "%s/views/%s/",
101 "template": "%s/templates/%s/",
102 "filter": "%s/filters/#%s",
103 "tag": "%s/tags/#%s",
104 }
105
106 explicit_title_re = re.compile(r"^(.+?)\s*(?<!\x00)<([^<]*?)>$", re.DOTALL)
107
108
109 def split_explicit_title(text):
110 """
111 Split role content into title and target, if given.
112
113 From sphinx.util.nodes.split_explicit_title
114 See https://github.com/sphinx-doc/sphinx/blob/230ccf2/sphinx/util/nodes.py#L389
115 """
116 match = explicit_title_re.match(text)
117 if match:
118 return True, match.group(1), match.group(2)
119 return False, text, text
120
121
122 def create_reference_role(rolename, urlbase):
123 # Views and template names are case-sensitive.
124 is_case_sensitive = rolename in ["template", "view"]
125
126 def _role(name, rawtext, text, lineno, inliner, options=None, content=None):
127 if options is None:
128 options = {}
129 _, title, target = split_explicit_title(text)
130 node = docutils.nodes.reference(
131 rawtext,
132 title,
133 refuri=(
134 urlbase
135 % (
136 inliner.document.settings.link_base,
137 target if is_case_sensitive else target.lower(),
138 )
139 ),
140 **options,
141 )
142 return [node], []
143
144 docutils.parsers.rst.roles.register_canonical_role(rolename, _role)
145
146
147 def default_reference_role(
148 name, rawtext, text, lineno, inliner, options=None, content=None
149 ):
150 if options is None:
151 options = {}
152 context = inliner.document.settings.default_reference_context
153 node = docutils.nodes.reference(
154 rawtext,
155 text,
156 refuri=(
157 ROLES[context]
158 % (
159 inliner.document.settings.link_base,
160 text.lower(),
161 )
162 ),
163 **options,
164 )
165 return [node], []
166
167
168 if docutils_is_available:
169 docutils.parsers.rst.roles.register_canonical_role(
170 "cmsreference", default_reference_role
171 )
172
173 for name, urlbase in ROLES.items():
174 create_reference_role(name, urlbase)
175
176 # Match the beginning of a named, unnamed, or non-capturing groups.
177 named_group_matcher = _lazy_re_compile(r"\(\?P(<\w+>)")
178 unnamed_group_matcher = _lazy_re_compile(r"\(")
179 non_capturing_group_matcher = _lazy_re_compile(r"\(\?\:")
180
181
182 def replace_metacharacters(pattern):
183 """Remove unescaped metacharacters from the pattern."""
184 return re.sub(
185 r"((?:^|(?<!\\))(?:\\\\)*)(\\?)([?*+^$]|\\[bBAZ])",
186 lambda m: m[1] + m[3] if m[2] else m[1],
187 pattern,
188 )
189
190
191 def _get_group_start_end(start, end, pattern):
192 # Handle nested parentheses, e.g. '^(?P<a>(x|y))/b' or '^b/((x|y)\w+)$'.
193 unmatched_open_brackets, prev_char = 1, None
194 for idx, val in enumerate(pattern[end:]):
195 # Check for unescaped `(` and `)`. They mark the start and end of a
196 # nested group.
197 if val == "(" and prev_char != "\\":
198 unmatched_open_brackets += 1
199 elif val == ")" and prev_char != "\\":
200 unmatched_open_brackets -= 1
201 prev_char = val
202 # If brackets are balanced, the end of the string for the current named
203 # capture group pattern has been reached.
204 if unmatched_open_brackets == 0:
205 return start, end + idx + 1
206
207
208 def _find_groups(pattern, group_matcher):
209 prev_end = None
210 for match in group_matcher.finditer(pattern):
211 if indices := _get_group_start_end(match.start(0), match.end(0), pattern):
212 start, end = indices
213 if prev_end and start > prev_end or not prev_end:
214 yield start, end, match
215 prev_end = end
216
217
218 def replace_named_groups(pattern):
219 r"""
220 Find named groups in `pattern` and replace them with the group name. E.g.,
221 1. ^(?P<a>\w+)/b/(\w+)$ ==> ^<a>/b/(\w+)$
222 2. ^(?P<a>\w+)/b/(?P<c>\w+)/$ ==> ^<a>/b/<c>/$
223 3. ^(?P<a>\w+)/b/(\w+) ==> ^<a>/b/(\w+)
224 4. ^(?P<a>\w+)/b/(?P<c>\w+) ==> ^<a>/b/<c>
225 """
226 group_pattern_and_name = [
227 (pattern[start:end], match[1])
228 for start, end, match in _find_groups(pattern, named_group_matcher)
229 ]
230 for group_pattern, group_name in group_pattern_and_name:
231 pattern = pattern.replace(group_pattern, group_name)
232 return pattern
233
234
235 def replace_unnamed_groups(pattern):
236 r"""
237 Find unnamed groups in `pattern` and replace them with '<var>'. E.g.,
238 1. ^(?P<a>\w+)/b/(\w+)$ ==> ^(?P<a>\w+)/b/<var>$
239 2. ^(?P<a>\w+)/b/((x|y)\w+)$ ==> ^(?P<a>\w+)/b/<var>$
240 3. ^(?P<a>\w+)/b/(\w+) ==> ^(?P<a>\w+)/b/<var>
241 4. ^(?P<a>\w+)/b/((x|y)\w+) ==> ^(?P<a>\w+)/b/<var>
242 """
243 final_pattern, prev_end = "", None
244 for start, end, _ in _find_groups(pattern, unnamed_group_matcher):
245 if prev_end:
246 final_pattern += pattern[prev_end:start]
247 final_pattern += pattern[:start] + "<var>"
248 prev_end = end
249 return final_pattern + pattern[prev_end:]
250
251
252 def remove_non_capturing_groups(pattern):
253 r"""
254 Find non-capturing groups in the given `pattern` and remove them, e.g.
255 1. (?P<a>\w+)/b/(?:\w+)c(?:\w+) => (?P<a>\\w+)/b/c
256 2. ^(?:\w+(?:\w+))a => ^a
257 3. ^a(?:\w+)/b(?:\w+) => ^a/b
258 """
259 group_start_end_indices = _find_groups(pattern, non_capturing_group_matcher)
260 final_pattern, prev_end = "", None
261 for start, end, _ in group_start_end_indices:
262 final_pattern += pattern[prev_end:start]
263 prev_end = end
264 return final_pattern + pattern[prev_end:]
265
266
267 def strip_p_tags(value):
268 return mark_safe(value.replace("<p>", "").replace("</p>", ""))