Debian Codegraph @

model_utils/tracker.py

raw
1 from __future__ import annotations
2
3 from copy import deepcopy
4 from functools import wraps
5 from typing import (
6 TYPE_CHECKING,
7 Any,
8 Generic,
9 Iterable,
10 Protocol,
11 TypeVar,
12 cast,
13 overload,
14 )
15
16 from django.core.exceptions import FieldError
17 from django.db import models
18 from django.db.models.fields.files import FieldFile
19
20 if TYPE_CHECKING:
21 from collections.abc import Callable, Mapping
22 from types import TracebackType
23
24 class _AugmentedModel(models.Model):
25 _instance_initialized: bool
26 _deferred_fields: set[str]
27
28 T = TypeVar("T")
29
30
31 class Descriptor(Protocol[T]):
32 def __get__(self, instance: object, owner: type[object]) -> T:
33 ...
34
35 def __set__(self, instance: object, value: T) -> None:
36 ...
37
38
39 class FullDescriptor(Descriptor[T]):
40 def __delete__(self, instance: object) -> None:
41 ...
42
43
44 class LightStateFieldFile(FieldFile):
45 """
46 FieldFile subclass with the only aim to remove the instance from the state.
47
48 The change introduced in Django 3.1 on FieldFile subclasses results in pickling the
49 whole instance for every field tracked.
50 As this is done on the initialization of objects, a simple queryset evaluation on
51 Django 3.1+ can make the app unusable, as CPU and memory usage gets easily
52 multiplied by magnitudes.
53 """
54 def __getstate__(self) -> dict[str, Any]:
55 """
56 We don't need to deepcopy the instance, so nullify if provided.
57 """
58 state = super().__getstate__()
59 if 'instance' in state:
60 state['instance'] = None
61 return state
62
63
64 def lightweight_deepcopy(value: T) -> T:
65 """
66 Use our lightweight class to avoid copying the instance on a FieldFile deepcopy.
67 """
68 if isinstance(value, FieldFile):
69 value = cast(T, LightStateFieldFile(
70 instance=value.instance,
71 field=value.field,
72 name=value.name,
73 ))
74 return deepcopy(value)
75
76
77 class DescriptorWrapper(Generic[T]):
78
79 def __init__(self, field_name: str, descriptor: Descriptor[T], tracker_attname: str):
80 self.field_name = field_name
81 self.descriptor = descriptor
82 self.tracker_attname = tracker_attname
83
84 @overload
85 def __get__(self, instance: None, owner: type[models.Model]) -> DescriptorWrapper[T]:
86 ...
87
88 @overload
89 def __get__(self, instance: models.Model, owner: type[models.Model]) -> T:
90 ...
91
92 def __get__(self, instance: models.Model | None, owner: type[models.Model]) -> DescriptorWrapper[T] | T:
93 if instance is None:
94 return self
95 was_deferred = self.field_name in instance.get_deferred_fields()
96 value = self.descriptor.__get__(instance, owner)
97 if was_deferred:
98 tracker_instance = getattr(instance, self.tracker_attname)
99 tracker_instance.saved_data[self.field_name] = lightweight_deepcopy(value)
100 return value
101
102 def __set__(self, instance: models.Model, value: T) -> None:
103 initialized = hasattr(instance, '_instance_initialized')
104 was_deferred = self.field_name in instance.get_deferred_fields()
105
106 # Sentinel attribute to detect whether we are already trying to
107 # set the attribute higher up the stack. This prevents infinite
108 # recursion when retrieving deferred values from the database.
109 recursion_sentinel_attname = '_setting_' + self.field_name
110 already_setting = hasattr(instance, recursion_sentinel_attname)
111
112 if initialized and was_deferred and not already_setting:
113 setattr(instance, recursion_sentinel_attname, True)
114 try:
115 # Retrieve the value to set the saved_data value.
116 # This will undefer the field
117 getattr(instance, self.field_name)
118 finally:
119 instance.__dict__.pop(recursion_sentinel_attname, None)
120 if hasattr(self.descriptor, '__set__'):
121 self.descriptor.__set__(instance, value)
122 else:
123 instance.__dict__[self.field_name] = value
124
125 def __getattr__(self, attr: str) -> T:
126 return getattr(self.descriptor, attr)
127
128 @staticmethod
129 def cls_for_descriptor(descriptor: Descriptor[T]) -> type[DescriptorWrapper[T]]:
130 if hasattr(descriptor, '__delete__'):
131 return FullDescriptorWrapper
132 else:
133 return DescriptorWrapper
134
135
136 class FullDescriptorWrapper(DescriptorWrapper[T]):
137 """
138 Wrapper for descriptors with all three descriptor methods.
139 """
140 def __delete__(self, obj: models.Model) -> None:
141 cast(FullDescriptor[T], self.descriptor).__delete__(obj)
142
143
144 class FieldsContext:
145 """
146 A context manager for tracking nested reset fields contexts.
147
148 If tracked fields is mentioned in more than one FieldsContext, it's state
149 is being reset on exiting last context that mentions that field.
150
151 >>> with fields_context(obj.tracker, 'f1', state=state):
152 ... with fields_context(obj.tracker, 'f1', 'f2', state=state):
153 ... obj.do_something_useful()
154 ... # f2 is reset after inner context exit
155 ... obj.do_something_else()
156 ... # f1 is reset after outer context exit
157 >>>
158
159 * Note that fields are counted by passing same state dict
160 * FieldsContext is instantiated using FieldInstanceTracker (`obj.tracker`)
161 * Different objects has own state stack
162
163 """
164
165 def __init__(
166 self,
167 tracker: FieldInstanceTracker,
168 *fields: str,
169 state: dict[str, int] | None = None
170 ):
171 """
172 :param tracker: FieldInstanceTracker instance to be reset after
173 context exit
174 :param fields: a list of field names to be tracked in current context
175 :param state: shared state dict used to count number of field
176 occurrences in context stack.
177
178 On context enter each field mentioned in `fields` has +1 in shared
179 state, and on exit it receives -1. Fields that have zero after context
180 exit are reset in tracker instance.
181 """
182 if state is None:
183 state = {}
184 self.tracker = tracker
185 self.fields = fields
186 self.state = state
187
188 def __enter__(self) -> FieldsContext:
189 """
190 Increments tracked fields occurrences count in shared state.
191 """
192 for f in self.fields:
193 self.state.setdefault(f, 0)
194 self.state[f] += 1
195 return self
196
197 def __exit__(
198 self,
199 exc_type: type[BaseException] | None,
200 exc_val: BaseException | None,
201 exc_tb: TracebackType | None
202 ) -> None:
203 """
204 Decrements tracked fields occurrences count in shared state.
205
206 If any field has no more occurrences in shared state, this field is
207 being reset by tracker.
208 """
209 reset_fields = []
210 for f in self.fields:
211 self.state[f] -= 1
212 if self.state[f] == 0:
213 reset_fields.append(f)
214 del self.state[f]
215 if reset_fields:
216 self.tracker.set_saved_fields(fields=reset_fields)
217
218
219 class FieldInstanceTracker:
220 def __init__(self, instance: models.Model, fields: Iterable[str], field_map: Mapping[str, str]):
221 self.instance = cast('_AugmentedModel', instance)
222 self.fields = fields
223 self.field_map = field_map
224 self.context = FieldsContext(self, *self.fields)
225
226 def __enter__(self) -> FieldsContext:
227 return self.context.__enter__()
228
229 def __exit__(
230 self,
231 exc_type: type[BaseException] | None,
232 exc_val: BaseException | None,
233 exc_tb: TracebackType | None
234 ) -> None:
235 return self.context.__exit__(exc_type, exc_val, exc_tb)
236
237 def __call__(self, *fields: str) -> FieldsContext:
238 return FieldsContext(self, *fields, state=self.context.state)
239
240 @property
241 def deferred_fields(self) -> set[str]:
242 return self.instance.get_deferred_fields()
243
244 def get_field_value(self, field: str) -> Any:
245 return getattr(self.instance, self.field_map[field])
246
247 def set_saved_fields(self, fields: Iterable[str] | None = None) -> None:
248 if not self.instance.pk:
249 self.saved_data = {}
250 elif fields is None:
251 self.saved_data = self.current()
252 else:
253 self.saved_data.update(**self.current(fields=fields))
254
255 # preventing mutable fields side effects
256 for field, field_value in self.saved_data.items():
257 self.saved_data[field] = lightweight_deepcopy(field_value)
258
259 def current(self, fields: Iterable[str] | None = None) -> dict[str, Any]:
260 """Returns dict of current values for all tracked fields"""
261 if fields is None:
262 deferred_fields = self.deferred_fields
263 if deferred_fields:
264 fields = [
265 field for field in self.fields
266 if field not in deferred_fields
267 ]
268 else:
269 fields = self.fields
270
271 return {f: self.get_field_value(f) for f in fields}
272
273 def has_changed(self, field: str) -> bool:
274 """Returns ``True`` if field has changed from currently saved value"""
275 if field in self.fields:
276 # deferred fields haven't changed
277 if field in self.deferred_fields and field not in self.instance.__dict__:
278 return False
279 prev: object = self.previous(field)
280 curr: object = self.get_field_value(field)
281 return prev != curr
282 else:
283 raise FieldError('field "%s" not tracked' % field)
284
285 def previous(self, field: str) -> Any:
286 """Returns currently saved value of given field"""
287
288 # handle deferred fields that have not yet been loaded from the database
289 if self.instance.pk and field in self.deferred_fields and field not in self.saved_data:
290
291 # if the field has not been assigned locally, simply fetch and un-defer the value
292 if field not in self.instance.__dict__:
293 self.get_field_value(field)
294
295 # if the field has been assigned locally, store the local value, fetch the database value,
296 # store database value to saved_data, and restore the local value
297 else:
298 current_value = self.get_field_value(field)
299 self.instance.refresh_from_db(fields=[field])
300 self.saved_data[field] = lightweight_deepcopy(self.get_field_value(field))
301 setattr(self.instance, self.field_map[field], current_value)
302
303 return self.saved_data.get(field)
304
305 def changed(self) -> dict[str, Any]:
306 """Returns dict of fields that changed since save (with old values)"""
307 return {
308 field: self.previous(field)
309 for field in self.fields
310 if self.has_changed(field)
311 }
312
313
314 class FieldTracker:
315
316 tracker_class = FieldInstanceTracker
317
318 def __init__(self, fields: Iterable[str] | None = None):
319 # finalize_class() will replace None; pretend it is never None.
320 self.fields = cast(Iterable[str], fields)
321
322 @overload
323 def __call__(
324 self,
325 func: None = None,
326 fields: Iterable[str] | None = None
327 ) -> Callable[[Callable[..., T]], Callable[..., T]]:
328 ...
329
330 @overload
331 def __call__(
332 self,
333 func: Callable[..., T],
334 fields: Iterable[str] | None = None
335 ) -> Callable[..., T]:
336 ...
337
338 def __call__(
339 self,
340 func: Callable[..., T] | None = None,
341 fields: Iterable[str] | None = None
342 ) -> Callable[[Callable[..., T]], Callable[..., T]] | Callable[..., T]:
343 def decorator(f: Callable[..., T]) -> Callable[..., T]:
344 @wraps(f)
345 def inner(obj: models.Model, *args: object, **kwargs: object) -> T:
346 tracker = getattr(obj, self.attname)
347 field_list = tracker.fields if fields is None else fields
348 with tracker(*field_list):
349 return f(obj, *args, **kwargs)
350
351 return inner
352 if func is None:
353 return decorator
354 return decorator(func)
355
356 def get_field_map(self, cls: type[models.Model]) -> dict[str, str]:
357 """Returns dict mapping fields names to model attribute names"""
358 field_map = {field: field for field in self.fields}
359 all_fields = {f.name: f.attname for f in cls._meta.fields}
360 field_map.update(**{k: v for (k, v) in all_fields.items()
361 if k in field_map})
362 return field_map
363
364 def contribute_to_class(self, cls: type[models.Model], name: str) -> None:
365 self.name = name
366 self.attname = '_%s' % name
367 models.signals.class_prepared.connect(self.finalize_class, sender=cls)
368
369 def finalize_class(self, sender: type[models.Model], **kwargs: object) -> None:
370 if self.fields is None or TYPE_CHECKING:
371 self.fields = (field.attname for field in sender._meta.fields)
372 self.fields = set(self.fields)
373 for field_name in self.fields:
374 descriptor: models.Field[Any, Any] = getattr(sender, field_name)
375 wrapper_cls = DescriptorWrapper.cls_for_descriptor(descriptor)
376 wrapped_descriptor = wrapper_cls(field_name, descriptor, self.attname)
377 setattr(sender, field_name, wrapped_descriptor)
378 self.field_map = self.get_field_map(sender)
379 self.patch_init(sender)
380 self.model_class = sender
381 setattr(sender, self.name, self)
382 self.patch_save(sender)
383
384 def initialize_tracker(
385 self,
386 sender: type[models.Model],
387 instance: models.Model,
388 **kwargs: object
389 ) -> None:
390 if not isinstance(instance, self.model_class):
391 return # Only init instances of given model (including children)
392 tracker = self.tracker_class(instance, self.fields, self.field_map)
393 setattr(instance, self.attname, tracker)
394 tracker.set_saved_fields()
395 cast('_AugmentedModel', instance)._instance_initialized = True
396
397 def patch_init(self, model: type[models.Model]) -> None:
398 original = getattr(model, '__init__')
399
400 @wraps(original)
401 def inner(instance: models.Model, *args: Any, **kwargs: Any) -> None:
402 original(instance, *args, **kwargs)
403 self.initialize_tracker(model, instance)
404
405 setattr(model, '__init__', inner)
406
407 def patch_save(self, model: type[models.Model]) -> None:
408 self._patch(model, 'save_base', 'update_fields')
409 self._patch(model, 'refresh_from_db', 'fields')
410
411 def _patch(self, model: type[models.Model], method: str, fields_kwarg: str) -> None:
412 original = getattr(model, method)
413
414 @wraps(original)
415 def inner(instance: models.Model, *args: object, **kwargs: Any) -> object:
416 update_fields: Iterable[str] | None = kwargs.get(fields_kwarg)
417 if update_fields is None:
418 fields = self.fields
419 else:
420 fields = (
421 field for field in update_fields if
422 field in self.fields
423 )
424 tracker = getattr(instance, self.attname)
425 with tracker(*fields):
426 return original(instance, *args, **kwargs)
427
428 setattr(model, method, inner)
429
430 @overload
431 def __get__(self, instance: None, owner: type[models.Model]) -> FieldTracker:
432 ...
433
434 @overload
435 def __get__(self, instance: models.Model, owner: type[models.Model]) -> FieldInstanceTracker:
436 ...
437
438 def __get__(self, instance: models.Model | None, owner: type[models.Model]) -> FieldTracker | FieldInstanceTracker:
439 if instance is None:
440 return self
441 else:
442 return getattr(instance, self.attname)
443
444
445 class ModelInstanceTracker(FieldInstanceTracker):
446
447 def has_changed(self, field: str) -> bool:
448 """Returns ``True`` if field has changed from currently saved value"""
449 if not self.instance.pk:
450 return True
451 elif field in self.saved_data:
452 prev: object = self.previous(field)
453 curr: object = self.get_field_value(field)
454 return prev != curr
455 else:
456 raise FieldError('field "%s" not tracked' % field)
457
458 def changed(self) -> dict[str, Any]:
459 """Returns dict of fields that changed since save (with old values)"""
460 if not self.instance.pk:
461 return {}
462 saved = self.saved_data.items()
463 current = self.current()
464 return {k: v for k, v in saved if v != current[k]}
465
466
467 class ModelTracker(FieldTracker):
468 tracker_class = ModelInstanceTracker
469
470 def get_field_map(self, cls: type[models.Model]) -> dict[str, str]:
471 return {field: field for field in self.fields}