| 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} |