Debian Codegraph @

django/contrib/admindocs/views.py

raw
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