diff --git a/CHANGES.rst b/CHANGES.rst index f45573a..8506f16 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -4,6 +4,9 @@ CHANGES tip (unreleased) ---------------- +- Introduced ``FieldTracker`` as replacement for ``ModelTracker``, which is now + deprecated. + - ``PassThroughManager.for_queryset_class()`` no longer ignores superclass ``get_query_set``. Thanks Andy Freeland. diff --git a/README.rst b/README.rst index cc23f80..0ba3574 100644 --- a/README.rst +++ b/README.rst @@ -207,6 +207,7 @@ Assignment to ``a.body`` is equivalent to assignment to ``a.body.content``. .. note:: + a.body.excerpt is only updated when a.save() is called @@ -436,11 +437,40 @@ last saved. An example of applying ``FieldTracker`` to a model: tracker = FieldTracker() +.. note:: + + ``django-model-utils`` 1.3.0 introduced the ``ModelTracker`` object for + tracking changes to model field values. Unfortunately ``ModelTracker`` + suffered from some serious flaws in its handling of ``ForeignKey`` fields, + potentially resulting in many extra database queries if a ``ForeignKey`` + field was tracked. In order to avoid breaking API backwards-compatibility, + ``ModelTracker`` retains the previous behavior but is deprecated, and + ``FieldTracker`` has been introduced to provide better ``ForeignKey`` + handling. All uses of ``ModelTracker`` should be replaced by + ``FieldTracker``. + + Summary of differences between ``ModelTracker`` and ``FieldTracker``: + + * The previous value returned for a tracked ``ForeignKey`` field will now + be the raw ID rather than the full object (avoiding extra database + queries). (GH-43) + + * The ``changed()`` method no longer returns the empty dictionary for all + unsaved instances; rather, ``None`` is considered to be the initial value + of all fields if the model has never been saved, thus ``changed()`` on an + unsaved instance will return a dictionary containing all fields whose + current value is not ``None``. + + * The ``has_changed()`` method no longer crashes after an object's first + save. (GH-53). + + Accessing a field tracker ------------------------- There are multiple methods available for checking for changes in model fields. + previous ~~~~~~~~ Returns the value of the given field during the last save: @@ -454,6 +484,7 @@ Returns the value of the given field during the last save: Returns ``None`` when the model instance isn't saved yet. + has_changed ~~~~~~~~~~~ Returns ``True`` if the given field has changed since the last save: @@ -470,6 +501,7 @@ Returns ``True`` if the given field has changed since the last save: The ``has_changed`` method relies on ``previous`` to determine whether a field's values has changed. + changed ~~~~~~~ Returns a dictionary of all fields that have been changed since the last save