Metadata-Version: 2.4
Name: django-model-changes-py3
Version: 0.15.1
Summary: django-model-changes allows you to track model instance changes.
Home-page: http://github.com/iansprice/django-model-changes-py3
Author: Ian Price
Author-email: iprice@thermaline.com
License: MIT License
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: summary

========================
django-model-changes-py3
========================

PYTHON 3 FORK OF `django-model-changes <https://github.com/kajic/django-model-changes/>`_.

*django-model-changes* allows you to track the state and changes of a model instance:

Quick start
-----------

1. Install django-model-changes::

    pip install django-model-changes-py3

2. Add "django_model_changes" to your INSTALLED_APPS setting like this::

    INSTALLED_APPS = (
        ...
        'django_model_changes',
    )

3. Add the `ChangesMixin` to your model::

    >>> from django.db import models
    >>> from django_model_changes import ChangesMixin

    >>> class User(ChangesMixin, models.Model):
    >>>     name = models.CharField(max_length=100)

4. Get instance changes::

    >>> user = User()
    >>> user.name = 'Foo Bar'
    >>> user.save()

    >>> user.name 'I got a new name'

    >>> # Get current state
    >>> user.current_state()
    {'id': 1, 'name': 'I got a new name'}

    >>> # Get previous state (state after previous save/create/delete)
    >>> user.previous_state()
    {'id': 1, 'name': 'Foo Bar'}

    >>> # Get old state (state before previous save/create/delete)
    >>> user.old_state()
    {'id': None, 'name': ''}

    >>> # Get changes from the previous state to the current state
    >>> user.changes()
    {'name': ('Foo Bar', 'I got a new name')}

    >>> # Get changes from the old state to the current state
    >>> user.old_changes()
    {'id': (None, 1), 'name': ('', 'Foo Bar')}

    >>> # Check if the instance was persisted (saved)
    >>> user.was_persisted()
    False

    >>> # Check if the instance is persisted
    >>> user.is_persisted()
    True

5. Listen for changes::
        
   >>> from django_model_changes import post_change
    
   >>> def my_callback(sender, instance, **kwargs):
   >>>     # Do something with previous and current state
   >>>     instance.old_state()
   >>>     instance.current_state()

   >>>     # There is also a convenience method to get
   >>>     # an instance from the previous state
   >>>     instance.old_instance()

   >>> post_change.connect(my_callback, User)

Overview
--------

django-model-changes allows you to retrieve the following states from an
instance:

1. current_state()
    The current state of the instance.
2. previous_state()
    The state of the instance **after** it was created, saved or deleted the
    last time.
3. old_state()
    The previous previous_state(), i.e. the state of the instance **before**
    it was created, saved or deleted the last time.

It also provides convenience methods to get changes between states:

1. changes()
    Changes from previous_state to current_state.
2. previous_changes()
    Changes from old_state to previous_state.
3. old_changes()
    Changes from old_state to current_state.

And the following methods to determine if an instance was/is persisted in
the database:

1. was_persisted()
    Was the instance persisted in its old state.
2. is_persisted()
    Is the instance is_persisted in its current state.

This schematic tries to illustrate how these methods relate to each other::


    after create/save/delete            after save/delete                  now
    |                                   |                                  |
    .-----------------------------------.----------------------------------.
    |\                                  |\                                 |\
    | \                                 | \                                | \
    |  old_state()                      |  previous_state()                |  current_state()
    |                                   |                                  |
    |-----------------------------------|----------------------------------|
    |  previous_changes() (prev - old)  |  changes() (cur - prev)          |
    |-----------------------------------|----------------------------------|
    |                      old_changes()  (cur - old)                      |
    .----------------------------------------------------------------------.
     \                                                                      \
      \                                                                      \
       was_persisted()                                                        is_persisted()


Documentation
-------------

Refer to the doc strings in `changes.py`_, or build the documentation::

    >>> pip install Sphinx
    >>> cd docs
    >>> make html
    Open build/html/index.html

.. _changes.py: django_model_changes/changes.py