Debian Codegraph @

django/contrib/admin/utils.py

raw
1 import datetime
2 import decimal
3 import json
4 from collections import defaultdict
5 from functools import reduce
6 from operator import or_
7
8 from django.core.exceptions import FieldDoesNotExist
9 from django.core.validators import EMPTY_VALUES
10 from django.db import models, router
11 from django.db.models.constants import LOOKUP_SEP
12 from django.db.models.deletion import Collector
13 from django.forms.utils import pretty_name
14 from django.urls import NoReverseMatch, reverse
15 from django.utils import formats, timezone
16 from django.utils.hashable import make_hashable
17 from django.utils.html import format_html
18 from django.utils.regex_helper import _lazy_re_compile
19 from django.utils.text import capfirst
20 from django.utils.translation import ngettext
21 from django.utils.translation import override as translation_override
22
23 QUOTE_MAP = {i: "_%02X" % i for i in b'":/_#?;@&=+$,"[]<>%\n\\'}
24 UNQUOTE_MAP = {v: chr(k) for k, v in QUOTE_MAP.items()}
25 UNQUOTE_RE = _lazy_re_compile("_(?:%s)" % "|".join([x[1:] for x in UNQUOTE_MAP]))
26
27
28 class FieldIsAForeignKeyColumnName(Exception):
29 """A field is a foreign key attname, i.e. <FK>_id."""
30
31 pass
32
33
34 def lookup_spawns_duplicates(opts, lookup_path):
35 """
36 Return True if the given lookup path spawns duplicates.
37 """
38 lookup_fields = lookup_path.split(LOOKUP_SEP)
39 # Go through the fields (following all relations) and look for an m2m.
40 for field_name in lookup_fields:
41 if field_name == "pk":
42 field_name = opts.pk.name
43 try:
44 field = opts.get_field(field_name)
45 except FieldDoesNotExist:
46 # Ignore query lookups.
47 continue
48 else:
49 if hasattr(field, "path_infos"):
50 # This field is a relation; update opts to follow the relation.
51 path_info = field.path_infos
52 opts = path_info[-1].to_opts
53 if any(path.m2m for path in path_info):
54 # This field is a m2m relation so duplicates must be
55 # handled.
56 return True
57 return False
58
59
60 def get_last_value_from_parameters(parameters, key):
61 value = parameters.get(key)
62 return value[-1] if isinstance(value, list) else value
63
64
65 def prepare_lookup_value(key, value, separator=","):
66 """
67 Return a lookup value prepared to be used in queryset filtering.
68 """
69 if isinstance(value, list):
70 return [prepare_lookup_value(key, v, separator=separator) for v in value]
71 # if key ends with __in, split parameter into separate values
72 if key.endswith("__in"):
73 value = value.split(separator)
74 # if key ends with __isnull, special case '' and the string literals 'false' and '0'
75 elif key.endswith("__isnull"):
76 value = value.lower() not in ("", "false", "0")
77 return value
78
79
80 def build_q_object_from_lookup_parameters(parameters):
81 q_object = models.Q()
82 for param, param_item_list in parameters.items():
83 q_object &= reduce(or_, (models.Q((param, item)) for item in param_item_list))
84 return q_object
85
86
87 def quote(s):
88 """
89 Ensure that primary key values do not confuse the admin URLs by escaping
90 any '/', '_' and ':' and similarly problematic characters.
91 Similar to urllib.parse.quote(), except that the quoting is slightly
92 different so that it doesn't get automatically unquoted by the web browser.
93 """
94 return s.translate(QUOTE_MAP) if isinstance(s, str) else s
95
96
97 def unquote(s):
98 """Undo the effects of quote()."""
99 return UNQUOTE_RE.sub(lambda m: UNQUOTE_MAP[m[0]], s)
100
101
102 def flatten(fields):
103 """
104 Return a list which is a single level of flattening of the original list.
105 """
106 flat = []
107 for field in fields:
108 if isinstance(field, (list, tuple)):
109 flat.extend(field)
110 else:
111 flat.append(field)
112 return flat
113
114
115 def flatten_fieldsets(fieldsets):
116 """Return a list of field names from an admin fieldsets structure."""
117 field_names = []
118 for name, opts in fieldsets:
119 field_names.extend(flatten(opts["fields"]))
120 return field_names
121
122
123 def get_deleted_objects(objs, request, admin_site):
124 """
125 Find all objects related to ``objs`` that should also be deleted. ``objs``
126 must be a homogeneous iterable of objects (e.g. a QuerySet).
127
128 Return a nested list of strings suitable for display in the
129 template with the ``unordered_list`` filter.
130 """
131 try:
132 obj = objs[0]
133 except IndexError:
134 return [], {}, set(), []
135 else:
136 using = router.db_for_write(obj._meta.model)
137 collector = NestedObjects(using=using, origin=objs)
138 collector.collect(objs)
139 perms_needed = set()
140
141 def format_callback(obj):
142 model = obj.__class__
143 opts = obj._meta
144
145 no_edit_link = "%s: %s" % (capfirst(opts.verbose_name), obj)
146
147 if admin_site.is_registered(model):
148 if not admin_site.get_model_admin(model).has_delete_permission(
149 request, obj
150 ):
151 perms_needed.add(opts.verbose_name)
152 try:
153 admin_url = reverse(
154 "%s:%s_%s_change"
155 % (admin_site.name, opts.app_label, opts.model_name),
156 None,
157 (quote(obj.pk),),
158 )
159 except NoReverseMatch:
160 # Change url doesn't exist -- don't display link to edit
161 return no_edit_link
162
163 # Display a link to the admin page.
164 return format_html(
165 '{}: <a href="{}">{}</a>', capfirst(opts.verbose_name), admin_url, obj
166 )
167 else:
168 # Don't display link to edit, because it either has no
169 # admin or is edited inline.
170 return no_edit_link
171
172 to_delete = collector.nested(format_callback)
173
174 protected = [format_callback(obj) for obj in collector.protected]
175 model_count = {
176 model._meta.verbose_name_plural: len(objs)
177 for model, objs in collector.model_objs.items()
178 }
179
180 return to_delete, model_count, perms_needed, protected
181
182
183 class NestedObjects(Collector):
184 def __init__(self, *args, **kwargs):
185 super().__init__(*args, **kwargs)
186 self.edges = {} # {from_instance: [to_instances]}
187 self.protected = set()
188 self.model_objs = defaultdict(set)
189
190 def add_edge(self, source, target):
191 self.edges.setdefault(source, []).append(target)
192
193 def collect(self, objs, source=None, source_attr=None, **kwargs):
194 for obj in objs:
195 if source_attr and not source_attr.endswith("+"):
196 related_name = source_attr % {
197 "class": source._meta.model_name,
198 "app_label": source._meta.app_label,
199 }
200 self.add_edge(getattr(obj, related_name), obj)
201 else:
202 self.add_edge(None, obj)
203 self.model_objs[obj._meta.model].add(obj)
204 try:
205 return super().collect(objs, source_attr=source_attr, **kwargs)
206 except models.ProtectedError as e:
207 self.protected.update(e.protected_objects)
208 except models.RestrictedError as e:
209 self.protected.update(e.restricted_objects)
210
211 def related_objects(self, related_model, related_fields, objs):
212 qs = super().related_objects(related_model, related_fields, objs)
213 return qs.select_related(
214 *[related_field.name for related_field in related_fields]
215 )
216
217 def _nested(self, obj, seen, format_callback):
218 if obj in seen:
219 return []
220 seen.add(obj)
221 children = []
222 for child in self.edges.get(obj, ()):
223 children.extend(self._nested(child, seen, format_callback))
224 if format_callback:
225 ret = [format_callback(obj)]
226 else:
227 ret = [obj]
228 if children:
229 ret.append(children)
230 return ret
231
232 def nested(self, format_callback=None):
233 """
234 Return the graph as a nested list.
235 """
236 seen = set()
237 roots = []
238 for root in self.edges.get(None, ()):
239 roots.extend(self._nested(root, seen, format_callback))
240 return roots
241
242 def can_fast_delete(self, *args, **kwargs):
243 """
244 We always want to load the objects into memory so that we can display
245 them to the user in confirm page.
246 """
247 return False
248
249
250 def model_format_dict(obj):
251 """
252 Return a `dict` with keys 'verbose_name' and 'verbose_name_plural',
253 typically for use with string formatting.
254
255 `obj` may be a `Model` instance, `Model` subclass, or `QuerySet` instance.
256 """
257 if isinstance(obj, (models.Model, models.base.ModelBase)):
258 opts = obj._meta
259 elif isinstance(obj, models.query.QuerySet):
260 opts = obj.model._meta
261 else:
262 opts = obj
263 return {
264 "verbose_name": opts.verbose_name,
265 "verbose_name_plural": opts.verbose_name_plural,
266 }
267
268
269 def model_ngettext(obj, n=None):
270 """
271 Return the appropriate `verbose_name` or `verbose_name_plural` value for
272 `obj` depending on the count `n`.
273
274 `obj` may be a `Model` instance, `Model` subclass, or `QuerySet` instance.
275 If `obj` is a `QuerySet` instance, `n` is optional and the length of the
276 `QuerySet` is used.
277 """
278 if isinstance(obj, models.query.QuerySet):
279 if n is None:
280 n = obj.count()
281 obj = obj.model
282 d = model_format_dict(obj)
283 singular, plural = d["verbose_name"], d["verbose_name_plural"]
284 return ngettext(singular, plural, n or 0)
285
286
287 def lookup_field(name, obj, model_admin=None):
288 opts = obj._meta
289 try:
290 f = _get_non_gfk_field(opts, name)
291 except (FieldDoesNotExist, FieldIsAForeignKeyColumnName):
292 # For non-regular field values, the value is either a method,
293 # property, related field, or returned via a callable.
294 if callable(name):
295 attr = name
296 value = attr(obj)
297 elif hasattr(model_admin, name) and name != "__str__":
298 attr = getattr(model_admin, name)
299 value = attr(obj)
300 else:
301 sentinel = object()
302 attr = getattr(obj, name, sentinel)
303 if callable(attr):
304 value = attr()
305 else:
306 if attr is sentinel:
307 attr = obj
308 for part in name.split(LOOKUP_SEP):
309 attr = getattr(attr, part, sentinel)
310 if attr is sentinel:
311 return None, None, None
312 value = attr
313 if hasattr(model_admin, "model") and hasattr(model_admin.model, name):
314 attr = getattr(model_admin.model, name)
315 f = None
316 else:
317 attr = None
318 value = getattr(obj, name)
319 return f, attr, value
320
321
322 def _get_non_gfk_field(opts, name):
323 """
324 For historical reasons, the admin app relies on GenericForeignKeys as being
325 "not found" by get_field(). This could likely be cleaned up.
326
327 Reverse relations should also be excluded as these aren't attributes of the
328 model (rather something like `foo_set`).
329 """
330 field = opts.get_field(name)
331 if (
332 field.is_relation
333 and
334 # Generic foreign keys OR reverse relations
335 ((field.many_to_one and not field.related_model) or field.one_to_many)
336 ):
337 raise FieldDoesNotExist()
338
339 # Avoid coercing <FK>_id fields to FK
340 if (
341 field.is_relation
342 and not field.many_to_many
343 and hasattr(field, "attname")
344 and field.attname == name
345 ):
346 raise FieldIsAForeignKeyColumnName()
347
348 return field
349
350
351 def label_for_field(name, model, model_admin=None, return_attr=False, form=None):
352 """
353 Return a sensible label for a field name. The name can be a callable,
354 property (but not created with @property decorator), or the name of an
355 object's attribute, as well as a model field, including across related
356 objects. If return_attr is True, also return the resolved attribute
357 (which could be a callable). This will be None if (and only if) the name
358 refers to a field.
359 """
360 attr = None
361 try:
362 field = _get_non_gfk_field(model._meta, name)
363 try:
364 label = field.verbose_name
365 except AttributeError:
366 # field is likely a ForeignObjectRel
367 label = field.related_model._meta.verbose_name
368 except FieldDoesNotExist:
369 if name == "__str__":
370 label = str(model._meta.verbose_name)
371 attr = str
372 else:
373 if callable(name):
374 attr = name
375 elif hasattr(model_admin, name):
376 attr = getattr(model_admin, name)
377 elif hasattr(model, name):
378 attr = getattr(model, name)
379 elif form and name in form.fields:
380 attr = form.fields[name]
381 else:
382 try:
383 attr = get_fields_from_path(model, name)[-1]
384 except (FieldDoesNotExist, NotRelationField):
385 message = f"Unable to lookup '{name}' on {model._meta.object_name}"
386 if model_admin:
387 message += f" or {model_admin.__class__.__name__}"
388 if form:
389 message += f" or {form.__class__.__name__}"
390 raise AttributeError(message)
391
392 if hasattr(attr, "short_description"):
393 label = attr.short_description
394 elif (
395 isinstance(attr, property)
396 and hasattr(attr, "fget")
397 and hasattr(attr.fget, "short_description")
398 ):
399 label = attr.fget.short_description
400 elif callable(attr):
401 if attr.__name__ == "<lambda>":
402 label = "--"
403 else:
404 label = pretty_name(attr.__name__)
405 else:
406 label = pretty_name(name)
407 except FieldIsAForeignKeyColumnName:
408 label = pretty_name(name)
409 attr = name
410
411 if return_attr:
412 return (label, attr)
413 else:
414 return label
415
416
417 def help_text_for_field(name, model):
418 help_text = ""
419 try:
420 field = _get_non_gfk_field(model._meta, name)
421 except (FieldDoesNotExist, FieldIsAForeignKeyColumnName):
422 pass
423 else:
424 if hasattr(field, "help_text"):
425 help_text = field.help_text
426 return help_text
427
428
429 def display_for_field(value, field, empty_value_display, avoid_link=False):
430 from django.contrib.admin.templatetags.admin_list import _boolean_icon
431
432 if getattr(field, "flatchoices", None):
433 try:
434 return dict(field.flatchoices).get(value, empty_value_display)
435 except TypeError:
436 # Allow list-like choices.
437 flatchoices = make_hashable(field.flatchoices)
438 value = make_hashable(value)
439 return dict(flatchoices).get(value, empty_value_display)
440
441 # BooleanField needs special-case null-handling, so it comes before the
442 # general null test.
443 elif isinstance(field, models.BooleanField):
444 return _boolean_icon(value)
445 elif value in field.empty_values:
446 return empty_value_display
447 elif isinstance(field, models.DateTimeField):
448 return formats.localize(timezone.template_localtime(value))
449 elif isinstance(field, (models.DateField, models.TimeField)):
450 return formats.localize(value)
451 elif isinstance(field, models.DecimalField):
452 return formats.number_format(value, field.decimal_places)
453 elif isinstance(field, (models.IntegerField, models.FloatField)):
454 return formats.number_format(value)
455 elif isinstance(field, models.FileField) and value and not avoid_link:
456 return format_html('<a href="{}">{}</a>', value.url, value)
457 elif isinstance(field, models.URLField) and value and not avoid_link:
458 return format_html('<a href="{}">{}</a>', value, value)
459 elif isinstance(field, models.JSONField) and value:
460 try:
461 return json.dumps(value, ensure_ascii=False, cls=field.encoder)
462 except TypeError:
463 return display_for_value(value, empty_value_display)
464 else:
465 return display_for_value(value, empty_value_display)
466
467
468 def display_for_value(value, empty_value_display, boolean=False):
469 from django.contrib.admin.templatetags.admin_list import _boolean_icon
470
471 if boolean:
472 return _boolean_icon(value)
473 elif value in EMPTY_VALUES:
474 return empty_value_display
475 elif isinstance(value, bool):
476 return str(value)
477 elif isinstance(value, datetime.datetime):
478 return formats.localize(timezone.template_localtime(value))
479 elif isinstance(value, (datetime.date, datetime.time)):
480 return formats.localize(value)
481 elif isinstance(value, (int, decimal.Decimal, float)):
482 return formats.number_format(value)
483 elif isinstance(value, (list, tuple)):
484 return ", ".join(str(v) for v in value)
485 else:
486 return str(value)
487
488
489 class NotRelationField(Exception):
490 pass
491
492
493 def get_model_from_relation(field):
494 if hasattr(field, "path_infos"):
495 return field.path_infos[-1].to_opts.model
496 else:
497 raise NotRelationField
498
499
500 def reverse_field_path(model, path):
501 """Create a reversed field path.
502
503 E.g. Given (Order, "user__groups"),
504 return (Group, "user__order").
505
506 Final field must be a related model, not a data field.
507 """
508 reversed_path = []
509 parent = model
510 pieces = path.split(LOOKUP_SEP)
511 for piece in pieces:
512 field = parent._meta.get_field(piece)
513 # skip trailing data field if extant:
514 if len(reversed_path) == len(pieces) - 1: # final iteration
515 try:
516 get_model_from_relation(field)
517 except NotRelationField:
518 break
519
520 # Field should point to another model
521 if field.is_relation and not (field.auto_created and not field.concrete):
522 related_name = field.related_query_name()
523 parent = field.remote_field.model
524 else:
525 related_name = field.field.name
526 parent = field.related_model
527 reversed_path.insert(0, related_name)
528 return (parent, LOOKUP_SEP.join(reversed_path))
529
530
531 def get_fields_from_path(model, path):
532 """Return list of Fields given path relative to model.
533
534 e.g. (ModelX, "user__groups__name") -> [
535 <django.db.models.fields.related.ForeignKey object at 0x...>,
536 <django.db.models.fields.related.ManyToManyField object at 0x...>,
537 <django.db.models.fields.CharField object at 0x...>,
538 ]
539 """
540 pieces = path.split(LOOKUP_SEP)
541 fields = []
542 for piece in pieces:
543 if fields:
544 parent = get_model_from_relation(fields[-1])
545 else:
546 parent = model
547 fields.append(parent._meta.get_field(piece))
548 return fields
549
550
551 def construct_change_message(form, formsets, add):
552 """
553 Construct a JSON structure describing changes from a changed object.
554 Translations are deactivated so that strings are stored untranslated.
555 Translation happens later on LogEntry access.
556 """
557 # Evaluating `form.changed_data` prior to disabling translations is required
558 # to avoid fields affected by localization from being included incorrectly,
559 # e.g. where date formats differ such as MM/DD/YYYY vs DD/MM/YYYY.
560 changed_data = form.changed_data
561 with translation_override(None):
562 # Deactivate translations while fetching verbose_name for form
563 # field labels and using `field_name`, if verbose_name is not provided.
564 # Translations will happen later on LogEntry access.
565 changed_field_labels = _get_changed_field_labels_from_form(form, changed_data)
566
567 change_message = []
568 if add:
569 change_message.append({"added": {}})
570 elif form.changed_data:
571 change_message.append({"changed": {"fields": changed_field_labels}})
572 if formsets:
573 with translation_override(None):
574 for formset in formsets:
575 for added_object in formset.new_objects:
576 change_message.append(
577 {
578 "added": {
579 "name": str(added_object._meta.verbose_name),
580 "object": str(added_object),
581 }
582 }
583 )
584 for changed_object, changed_fields in formset.changed_objects:
585 change_message.append(
586 {
587 "changed": {
588 "name": str(changed_object._meta.verbose_name),
589 "object": str(changed_object),
590 "fields": _get_changed_field_labels_from_form(
591 formset.forms[0], changed_fields
592 ),
593 }
594 }
595 )
596 for deleted_object in formset.deleted_objects:
597 change_message.append(
598 {
599 "deleted": {
600 "name": str(deleted_object._meta.verbose_name),
601 "object": str(deleted_object),
602 }
603 }
604 )
605 return change_message
606
607
608 def _get_changed_field_labels_from_form(form, changed_data):
609 changed_field_labels = []
610 for field_name in changed_data:
611 try:
612 verbose_field_name = form.fields[field_name].label or field_name
613 except KeyError:
614 verbose_field_name = field_name
615 changed_field_labels.append(str(verbose_field_name))
616 return changed_field_labels