| 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>", "")) |