This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

django-model-changes allows you to track model instance changes.

Project Description

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
    
  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
Release History

Release History

This version
History Node

0.15

History Node

0.14

History Node

0.13

History Node

0.12

History Node

0.11

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django-model-changes-0.15.tar.gz (12.1 kB) Copy SHA256 Checksum SHA256 Source Dec 26, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting