| 1 |
import inspect |
| 2 |
from importlib import import_module |
| 3 |
from inspect import cleandoc |
| 4 |
from pathlib import Path |
| 5 |
|
| 6 |
from django.apps import apps |
| 7 |
from django.contrib import admin |
| 8 |
from django.contrib.admin.views.decorators import staff_member_required |
| 9 |
from django.contrib.admindocs import utils |
| 10 |
from django.contrib.admindocs.utils import ( |
| 11 |
remove_non_capturing_groups, |
| 12 |
replace_metacharacters, |
| 13 |
replace_named_groups, |
| 14 |
replace_unnamed_groups, |
| 15 |
) |
| 16 |
from django.contrib.auth import get_permission_codename |
| 17 |
from django.core.exceptions import ( |
| 18 |
ImproperlyConfigured, |
| 19 |
PermissionDenied, |
| 20 |
ViewDoesNotExist, |
| 21 |
) |
| 22 |
from django.db import models |
| 23 |
from django.http import Http404 |
| 24 |
from django.template.engine import Engine |
| 25 |
from django.urls import get_mod_func, get_resolver, get_urlconf |
| 26 |
from django.utils._os import safe_join |
| 27 |
from django.utils.decorators import method_decorator |
| 28 |
from django.utils.functional import cached_property |
| 29 |
from django.utils.inspect import ( |
| 30 |
func_accepts_kwargs, |
| 31 |
func_accepts_var_args, |
| 32 |
get_func_full_args, |
| 33 |
method_has_no_args, |
| 34 |
) |
| 35 |
from django.utils.translation import gettext as _ |
| 36 |
from django.views.generic import TemplateView |
| 37 |
|
| 38 |
from .utils import get_view_name, strip_p_tags |
| 39 |
|
| 40 |
# Exclude methods starting with these strings from documentation |
| 41 |
MODEL_METHODS_EXCLUDE = ("_", "add_", "delete", "save", "set_") |
| 42 |
|
| 43 |
|
| 44 |
class BaseAdminDocsView(TemplateView): |
| 45 |
""" |
| 46 |
Base view for admindocs views. |
| 47 |
""" |
| 48 |
|
| 49 |
@method_decorator(staff_member_required) |
| 50 |
def dispatch(self, request, *args, **kwargs): |
| 51 |
if not utils.docutils_is_available: |
| 52 |
# Display an error message for people without docutils |
| 53 |
self.template_name = "admin_doc/missing_docutils.html" |
| 54 |
return self.render_to_response(admin.site.each_context(request)) |
| 55 |
return super().dispatch(request, *args, **kwargs) |
| 56 |
|
| 57 |
def get_context_data(self, **kwargs): |
| 58 |
return super().get_context_data( |
| 59 |
**{ |
| 60 |
**kwargs, |
| 61 |
**admin.site.each_context(self.request), |
| 62 |
} |
| 63 |
) |
| 64 |
|
| 65 |
|
| 66 |
class BookmarkletsView(BaseAdminDocsView): |
| 67 |
template_name = "admin_doc/bookmarklets.html" |
| 68 |
|
| 69 |
|
| 70 |
class TemplateTagIndexView(BaseAdminDocsView): |
| 71 |
template_name = "admin_doc/template_tag_index.html" |
| 72 |
|
| 73 |
def get_context_data(self, **kwargs): |
| 74 |
tags = [] |
| 75 |
try: |
| 76 |
engine = Engine.get_default() |
| 77 |
except ImproperlyConfigured: |
| 78 |
# Non-trivial TEMPLATES settings aren't supported (#24125). |
| 79 |
pass |
| 80 |
else: |
| 81 |
app_libs = sorted(engine.template_libraries.items()) |
| 82 |
builtin_libs = [("", lib) for lib in engine.template_builtins] |
| 83 |
for module_name, library in builtin_libs + app_libs: |
| 84 |
for tag_name, tag_func in library.tags.items(): |
| 85 |
title, body, metadata = utils.parse_docstring(tag_func.__doc__) |
| 86 |
title = title and utils.parse_rst( |
| 87 |
title, "tag", _("tag:") + tag_name |
| 88 |
) |
| 89 |
body = body and utils.parse_rst(body, "tag", _("tag:") + tag_name) |
| 90 |
for key in metadata: |
| 91 |
metadata[key] = utils.parse_rst( |
| 92 |
metadata[key], "tag", _("tag:") + tag_name |
| 93 |
) |
| 94 |
tag_library = module_name.split(".")[-1] |
| 95 |
tags.append( |
| 96 |
{ |
| 97 |
"name": tag_name, |
| 98 |
"title": title, |
| 99 |
"body": body, |
| 100 |
"meta": metadata, |
| 101 |
"library": tag_library, |
| 102 |
} |
| 103 |
) |
| 104 |
return super().get_context_data(**{**kwargs, "tags": tags}) |
| 105 |
|
| 106 |
|
| 107 |
class TemplateFilterIndexView(BaseAdminDocsView): |
| 108 |
template_name = "admin_doc/template_filter_index.html" |
| 109 |
|
| 110 |
def get_context_data(self, **kwargs): |
| 111 |
filters = [] |
| 112 |
try: |
| 113 |
engine = Engine.get_default() |
| 114 |
except ImproperlyConfigured: |
| 115 |
# Non-trivial TEMPLATES settings aren't supported (#24125). |
| 116 |
pass |
| 117 |
else: |
| 118 |
app_libs = sorted(engine.template_libraries.items()) |
| 119 |
builtin_libs = [("", lib) for lib in engine.template_builtins] |
| 120 |
for module_name, library in builtin_libs + app_libs: |
| 121 |
for filter_name, filter_func in library.filters.items(): |
| 122 |
title, body, metadata = utils.parse_docstring(filter_func.__doc__) |
| 123 |
title = title and utils.parse_rst( |
| 124 |
title, "filter", _("filter:") + filter_name |
| 125 |
) |
| 126 |
body = body and utils.parse_rst( |
| 127 |
body, "filter", _("filter:") + filter_name |
| 128 |
) |
| 129 |
for key in metadata: |
| 130 |
metadata[key] = utils.parse_rst( |
| 131 |
metadata[key], "filter", _("filter:") + filter_name |
| 132 |
) |
| 133 |
tag_library = module_name.split(".")[-1] |
| 134 |
filters.append( |
| 135 |
{ |
| 136 |
"name": filter_name, |
| 137 |
"title": title, |
| 138 |
"body": body, |
| 139 |
"meta": metadata, |
| 140 |
"library": tag_library, |
| 141 |
} |
| 142 |
) |
| 143 |
return super().get_context_data(**{**kwargs, "filters": filters}) |
| 144 |
|
| 145 |
|
| 146 |
class ViewIndexView(BaseAdminDocsView): |
| 147 |
template_name = "admin_doc/view_index.html" |
| 148 |
|
| 149 |
def get_context_data(self, **kwargs): |
| 150 |
views = [] |
| 151 |
url_resolver = get_resolver(get_urlconf()) |
| 152 |
try: |
| 153 |
view_functions = extract_views_from_urlpatterns(url_resolver.url_patterns) |
| 154 |
except ImproperlyConfigured: |
| 155 |
view_functions = [] |
| 156 |
for func, regex, namespace, name in view_functions: |
| 157 |
views.append( |
| 158 |
{ |
| 159 |
"full_name": get_view_name(func), |
| 160 |
"url": simplify_regex(regex), |
| 161 |
"url_name": ":".join((namespace or []) + (name and [name] or [])), |
| 162 |
"namespace": ":".join(namespace or []), |
| 163 |
"name": name, |
| 164 |
} |
| 165 |
) |
| 166 |
return super().get_context_data(**{**kwargs, "views": views}) |
| 167 |
|
| 168 |
|
| 169 |
class ViewDetailView(BaseAdminDocsView): |
| 170 |
template_name = "admin_doc/view_detail.html" |
| 171 |
|
| 172 |
@staticmethod |
| 173 |
def _get_view_func(view): |
| 174 |
urlconf = get_urlconf() |
| 175 |
if get_resolver(urlconf)._is_callback(view): |
| 176 |
mod, func = get_mod_func(view) |
| 177 |
try: |
| 178 |
# Separate the module and function, e.g. |
| 179 |
# 'mymodule.views.myview' -> 'mymodule.views', 'myview'). |
| 180 |
return getattr(import_module(mod), func) |
| 181 |
except ImportError: |
| 182 |
# Import may fail because view contains a class name, e.g. |
| 183 |
# 'mymodule.views.ViewContainer.my_view', so mod takes the form |
| 184 |
# 'mymodule.views.ViewContainer'. Parse it again to separate |
| 185 |
# the module and class. |
| 186 |
mod, klass = get_mod_func(mod) |
| 187 |
return getattr(getattr(import_module(mod), klass), func) |
| 188 |
|
| 189 |
def get_context_data(self, **kwargs): |
| 190 |
view = self.kwargs["view"] |
| 191 |
view_func = self._get_view_func(view) |
| 192 |
if view_func is None: |
| 193 |
raise Http404 |
| 194 |
title, body, metadata = utils.parse_docstring(view_func.__doc__) |
| 195 |
title = title and utils.parse_rst(title, "view", _("view:") + view) |
| 196 |
body = body and utils.parse_rst(body, "view", _("view:") + view) |
| 197 |
for key in metadata: |
| 198 |
metadata[key] = utils.parse_rst(metadata[key], "model", _("view:") + view) |
| 199 |
return super().get_context_data( |
| 200 |
**{ |
| 201 |
**kwargs, |
| 202 |
"name": view, |
| 203 |
"summary": strip_p_tags(title), |
| 204 |
"body": body, |
| 205 |
"meta": metadata, |
| 206 |
} |
| 207 |
) |
| 208 |
|
| 209 |
|
| 210 |
def user_has_model_view_permission(user, opts): |
| 211 |
"""Based off ModelAdmin.has_view_permission.""" |
| 212 |
codename_view = get_permission_codename("view", opts) |
| 213 |
codename_change = get_permission_codename("change", opts) |
| 214 |
return user.has_perm("%s.%s" % (opts.app_label, codename_view)) or user.has_perm( |
| 215 |
"%s.%s" % (opts.app_label, codename_change) |
| 216 |
) |
| 217 |
|
| 218 |
|
| 219 |
class ModelIndexView(BaseAdminDocsView): |
| 220 |
template_name = "admin_doc/model_index.html" |
| 221 |
|
| 222 |
def get_context_data(self, **kwargs): |
| 223 |
m_list = [ |
| 224 |
m._meta |
| 225 |
for m in apps.get_models() |
| 226 |
if user_has_model_view_permission(self.request.user, m._meta) |
| 227 |
] |
| 228 |
return super().get_context_data(**{**kwargs, "models": m_list}) |
| 229 |
|
| 230 |
|
| 231 |
class ModelDetailView(BaseAdminDocsView): |
| 232 |
template_name = "admin_doc/model_detail.html" |
| 233 |
|
| 234 |
def get_context_data(self, **kwargs): |
| 235 |
model_name = self.kwargs["model_name"] |
| 236 |
# Get the model class. |
| 237 |
try: |
| 238 |
app_config = apps.get_app_config(self.kwargs["app_label"]) |
| 239 |
except LookupError: |
| 240 |
raise Http404(_("App %(app_label)r not found") % self.kwargs) |
| 241 |
try: |
| 242 |
model = app_config.get_model(model_name) |
| 243 |
except LookupError: |
| 244 |
raise Http404( |
| 245 |
_("Model %(model_name)r not found in app %(app_label)r") % self.kwargs |
| 246 |
) |
| 247 |
|
| 248 |
opts = model._meta |
| 249 |
if not user_has_model_view_permission(self.request.user, opts): |
| 250 |
raise PermissionDenied |
| 251 |
|
| 252 |
title, body, metadata = utils.parse_docstring(model.__doc__) |
| 253 |
title = title and utils.parse_rst(title, "model", _("model:") + model_name) |
| 254 |
body = body and utils.parse_rst(body, "model", _("model:") + model_name) |
| 255 |
|
| 256 |
# Gather fields/field descriptions. |
| 257 |
fields = [] |
| 258 |
for field in opts.fields: |
| 259 |
# ForeignKey is a special case since the field will actually be a |
| 260 |
# descriptor that returns the other object |
| 261 |
if isinstance(field, models.ForeignKey): |
| 262 |
data_type = field.remote_field.model.__name__ |
| 263 |
app_label = field.remote_field.model._meta.app_label |
| 264 |
verbose = utils.parse_rst( |
| 265 |
( |
| 266 |
_("the related `%(app_label)s.%(data_type)s` object") |
| 267 |
% { |
| 268 |
"app_label": app_label, |
| 269 |
"data_type": data_type, |
| 270 |
} |
| 271 |
), |
| 272 |
"model", |
| 273 |
_("model:") + data_type, |
| 274 |
) |
| 275 |
else: |
| 276 |
data_type = get_readable_field_data_type(field) |
| 277 |
verbose = field.verbose_name |
| 278 |
fields.append( |
| 279 |
{ |
| 280 |
"name": field.name, |
| 281 |
"data_type": data_type, |
| 282 |
"verbose": verbose or "", |
| 283 |
"help_text": field.help_text, |
| 284 |
} |
| 285 |
) |
| 286 |
|
| 287 |
# Gather many-to-many fields. |
| 288 |
for field in opts.many_to_many: |
| 289 |
data_type = field.remote_field.model.__name__ |
| 290 |
app_label = field.remote_field.model._meta.app_label |
| 291 |
verbose = _("related `%(app_label)s.%(object_name)s` objects") % { |
| 292 |
"app_label": app_label, |
| 293 |
"object_name": data_type, |
| 294 |
} |
| 295 |
fields.append( |
| 296 |
{ |
| 297 |
"name": "%s.all" % field.name, |
| 298 |
"data_type": "List", |
| 299 |
"verbose": utils.parse_rst( |
| 300 |
_("all %s") % verbose, "model", _("model:") + opts.model_name |
| 301 |
), |
| 302 |
} |
| 303 |
) |
| 304 |
fields.append( |
| 305 |
{ |
| 306 |
"name": "%s.count" % field.name, |
| 307 |
"data_type": "Integer", |
| 308 |
"verbose": utils.parse_rst( |
| 309 |
_("number of %s") % verbose, |
| 310 |
"model", |
| 311 |
_("model:") + opts.model_name, |
| 312 |
), |
| 313 |
} |
| 314 |
) |
| 315 |
|
| 316 |
methods = [] |
| 317 |
# Gather model methods. |
| 318 |
for func_name, func in model.__dict__.items(): |
| 319 |
if inspect.isfunction(func) or isinstance( |
| 320 |
func, (cached_property, property) |
| 321 |
): |
| 322 |
try: |
| 323 |
for exclude in MODEL_METHODS_EXCLUDE: |
| 324 |
if func_name.startswith(exclude): |
| 325 |
raise StopIteration |
| 326 |
except StopIteration: |
| 327 |
continue |
| 328 |
verbose = func.__doc__ |
| 329 |
verbose = verbose and ( |
| 330 |
utils.parse_rst( |
| 331 |
cleandoc(verbose), "model", _("model:") + opts.model_name |
| 332 |
) |
| 333 |
) |
| 334 |
# Show properties, cached_properties, and methods without |
| 335 |
# arguments as fields. Otherwise, show as a 'method with |
| 336 |
# arguments'. |
| 337 |
if isinstance(func, (cached_property, property)): |
| 338 |
fields.append( |
| 339 |
{ |
| 340 |
"name": func_name, |
| 341 |
"data_type": get_return_data_type(func_name), |
| 342 |
"verbose": verbose or "", |
| 343 |
} |
| 344 |
) |
| 345 |
elif ( |
| 346 |
method_has_no_args(func) |
| 347 |
and not func_accepts_kwargs(func) |
| 348 |
and not func_accepts_var_args(func) |
| 349 |
): |
| 350 |
fields.append( |
| 351 |
{ |
| 352 |
"name": func_name, |
| 353 |
"data_type": get_return_data_type(func_name), |
| 354 |
"verbose": verbose or "", |
| 355 |
} |
| 356 |
) |
| 357 |
else: |
| 358 |
arguments = get_func_full_args(func) |
| 359 |
# Join arguments with ', ' and in case of default value, |
| 360 |
# join it with '='. Use repr() so that strings will be |
| 361 |
# correctly displayed. |
| 362 |
print_arguments = ", ".join( |
| 363 |
[ |
| 364 |
"=".join([arg_el[0], *map(repr, arg_el[1:])]) |
| 365 |
for arg_el in arguments |
| 366 |
] |
| 367 |
) |
| 368 |
methods.append( |
| 369 |
{ |
| 370 |
"name": func_name, |
| 371 |
"arguments": print_arguments, |
| 372 |
"verbose": verbose or "", |
| 373 |
} |
| 374 |
) |
| 375 |
|
| 376 |
# Gather related objects |
| 377 |
for rel in opts.related_objects: |
| 378 |
verbose = _("related `%(app_label)s.%(object_name)s` objects") % { |
| 379 |
"app_label": rel.related_model._meta.app_label, |
| 380 |
"object_name": rel.related_model._meta.object_name, |
| 381 |
} |
| 382 |
accessor = rel.accessor_name |
| 383 |
fields.append( |
| 384 |
{ |
| 385 |
"name": "%s.all" % accessor, |
| 386 |
"data_type": "List", |
| 387 |
"verbose": utils.parse_rst( |
| 388 |
_("all %s") % verbose, "model", _("model:") + opts.model_name |
| 389 |
), |
| 390 |
} |
| 391 |
) |
| 392 |
fields.append( |
| 393 |
{ |
| 394 |
"name": "%s.count" % accessor, |
| 395 |
"data_type": "Integer", |
| 396 |
"verbose": utils.parse_rst( |
| 397 |
_("number of %s") % verbose, |
| 398 |
"model", |
| 399 |
_("model:") + opts.model_name, |
| 400 |
), |
| 401 |
} |
| 402 |
) |
| 403 |
return super().get_context_data( |
| 404 |
**{ |
| 405 |
**kwargs, |
| 406 |
"name": opts.label, |
| 407 |
"summary": strip_p_tags(title), |
| 408 |
"description": body, |
| 409 |
"fields": fields, |
| 410 |
"methods": methods, |
| 411 |
} |
| 412 |
) |
| 413 |
|
| 414 |
|
| 415 |
class TemplateDetailView(BaseAdminDocsView): |
| 416 |
template_name = "admin_doc/template_detail.html" |
| 417 |
|
| 418 |
def get_context_data(self, **kwargs): |
| 419 |
template = self.kwargs["template"] |
| 420 |
templates = [] |
| 421 |
try: |
| 422 |
default_engine = Engine.get_default() |
| 423 |
except ImproperlyConfigured: |
| 424 |
# Non-trivial TEMPLATES settings aren't supported (#24125). |
| 425 |
pass |
| 426 |
else: |
| 427 |
directories = list(default_engine.dirs) |
| 428 |
for loader in default_engine.template_loaders: |
| 429 |
if hasattr(loader, "get_dirs"): |
| 430 |
for dir_ in loader.get_dirs(): |
| 431 |
if dir_ not in directories: |
| 432 |
directories.append(dir_) |
| 433 |
for index, directory in enumerate(directories): |
| 434 |
template_file = Path(safe_join(directory, template)) |
| 435 |
if template_file.exists(): |
| 436 |
template_contents = template_file.read_text() |
| 437 |
else: |
| 438 |
template_contents = "" |
| 439 |
templates.append( |
| 440 |
{ |
| 441 |
"file": template_file, |
| 442 |
"exists": template_file.exists(), |
| 443 |
"contents": template_contents, |
| 444 |
"order": index, |
| 445 |
} |
| 446 |
) |
| 447 |
return super().get_context_data( |
| 448 |
**{ |
| 449 |
**kwargs, |
| 450 |
"name": template, |
| 451 |
"templates": templates, |
| 452 |
} |
| 453 |
) |
| 454 |
|
| 455 |
|
| 456 |
#################### |
| 457 |
# Helper functions # |
| 458 |
#################### |
| 459 |
|
| 460 |
|
| 461 |
def get_return_data_type(func_name): |
| 462 |
"""Return a somewhat-helpful data type given a function name""" |
| 463 |
if func_name.startswith("get_"): |
| 464 |
if func_name.endswith("_list"): |
| 465 |
return "List" |
| 466 |
elif func_name.endswith("_count"): |
| 467 |
return "Integer" |
| 468 |
return "" |
| 469 |
|
| 470 |
|
| 471 |
def get_readable_field_data_type(field): |
| 472 |
""" |
| 473 |
Return the description for a given field type, if it exists. Fields' |
| 474 |
descriptions can contain format strings, which will be interpolated with |
| 475 |
the values of field.__dict__ before being output. |
| 476 |
""" |
| 477 |
return field.description % field.__dict__ |
| 478 |
|
| 479 |
|
| 480 |
def extract_views_from_urlpatterns(urlpatterns, base="", namespace=None): |
| 481 |
""" |
| 482 |
Return a list of views from a list of urlpatterns. |
| 483 |
|
| 484 |
Each object in the returned list is a 4-tuple: |
| 485 |
(view_func, regex, namespace, name) |
| 486 |
""" |
| 487 |
views = [] |
| 488 |
for p in urlpatterns: |
| 489 |
if hasattr(p, "url_patterns"): |
| 490 |
try: |
| 491 |
patterns = p.url_patterns |
| 492 |
except ImportError: |
| 493 |
continue |
| 494 |
views.extend( |
| 495 |
extract_views_from_urlpatterns( |
| 496 |
patterns, |
| 497 |
base + str(p.pattern), |
| 498 |
(namespace or []) + (p.namespace and [p.namespace] or []), |
| 499 |
) |
| 500 |
) |
| 501 |
elif hasattr(p, "callback"): |
| 502 |
try: |
| 503 |
views.append((p.callback, base + str(p.pattern), namespace, p.name)) |
| 504 |
except ViewDoesNotExist: |
| 505 |
continue |
| 506 |
else: |
| 507 |
raise TypeError(_("%s does not appear to be a urlpattern object") % p) |
| 508 |
return views |
| 509 |
|
| 510 |
|
| 511 |
def simplify_regex(pattern): |
| 512 |
r""" |
| 513 |
Clean up urlpattern regexes into something more readable by humans. For |
| 514 |
example, turn "^(?P<sport_slug>\w+)/athletes/(?P<athlete_slug>\w+)/$" |
| 515 |
into "/<sport_slug>/athletes/<athlete_slug>/". |
| 516 |
""" |
| 517 |
pattern = remove_non_capturing_groups(pattern) |
| 518 |
pattern = replace_named_groups(pattern) |
| 519 |
pattern = replace_unnamed_groups(pattern) |
| 520 |
pattern = replace_metacharacters(pattern) |
| 521 |
if not pattern.startswith("/"): |
| 522 |
pattern = "/" + pattern |
| 523 |
return pattern |