├── .gitignore ├── .travis.yml ├── LICENSE ├── README.md ├── ondelta ├── __init__.py ├── models.py └── signals.py ├── setup.py ├── test_requirements.txt ├── testproject ├── manage.py └── testproject │ ├── __init__.py │ ├── settings.py │ └── testapp │ ├── __init__.py │ ├── models.py │ └── tests.py └── tox.ini /.gitignore: -------------------------------------------------------------------------------- 1 | *.log 2 | *.pot 3 | *.pyc 4 | local_settings.py 5 | ondelta.egg-info/ 6 | venv/ 7 | .idea/ 8 | .tox/ -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | python: 3 | - "2.7" 4 | - "3.3" 5 | - "3.4" 6 | - "pypy" 7 | 8 | script: 9 | - python setup.py install 10 | - pip install -r test_requirements.txt 11 | - pep8 ondelta --ignore=E501 12 | - pyflakes ondelta 13 | - cd testproject && python manage.py test 14 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2013 Adam Haney 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the "Software"), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software is furnished to do so, 10 | subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | django-ondelta 2 | ============== 3 | 4 | A django model mixin that makes it easy to react to field value 5 | changes on models. Supports an API similar to the model clean method. 6 | 7 | 8 | Quick Start 9 | ----------- 10 | 11 | Given that I have the model 12 | 13 | class MyModel(models.Model): 14 | mai_field = models.CharField() 15 | other_field = models.BooleanField() 16 | 17 | And I want to be notified when mai_field's value is changed and 18 | persisted I would simply need to modify my model to include a 19 | `ondelta_mai_field` method. 20 | 21 | from ondelta.models import OnDeltaMixin 22 | 23 | class MyModel(OnDeltaMixin): 24 | mai_field = models.CharField() 25 | other_field = models.BooleanField() 26 | 27 | def ondelta_mai_field(self, old_value, new_value): 28 | print("mai field had the value of {}".format(old_value)) 29 | print("but after we called save it had the value of {}".format(new_value)) 30 | 31 | This is the easiest method to watch a single field for changes, but 32 | what if we want to perform an action that has an aggregate view 33 | of all of the fields that were changed? `OnDeltaMixin` provides an 34 | `ondelta_all` method for these cases; it is only called once for 35 | each save. 36 | 37 | from ondelta.models import OnDeltaMixin 38 | 39 | class MyModel(OnDeltaMixin): 40 | mai_field = models.CharField() 41 | other_field = models.BooleanField() 42 | 43 | ondelta_all(self, fields_changed): 44 | if 'mai_field' in fields_changed and 'other_field' in fields_changed: 45 | print("Both fields changed during this save!") 46 | 47 | 48 | Unsupported Field Types 49 | ----------------------- 50 | 51 | Some field types are not supported: `ManyToManyField`, reverse `ManyToManyField`, 52 | reverse `ForeignKey`, and reverse `OneToOneField` relations. If you create an 53 | `ondelta_field_name` method for one of these fields, it will **not** be called when 54 | that field is changed. 55 | 56 | 57 | Help 58 | ---- 59 | 60 | I like to help people as much as possible who are using my libraries, 61 | the easiest way to get my attention is to tweet @adamhaney or open an 62 | issue. As long as I'm able I'll help with any issues you have. 63 | -------------------------------------------------------------------------------- /ondelta/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adamhaney/django-ondelta/470138fd72947f457fba3f458938f1b2b6f00d30/ondelta/__init__.py -------------------------------------------------------------------------------- /ondelta/models.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | import copy 4 | import logging 5 | 6 | from django.db import models 7 | from django.utils.functional import cached_property 8 | 9 | from .signals import post_ondelta_signal 10 | 11 | logger = logging.getLogger('ondelta') 12 | 13 | 14 | class OnDeltaMixin(models.Model): 15 | 16 | class Meta: 17 | abstract = True 18 | 19 | def __init__(self, *args, **kwargs): 20 | super(OnDeltaMixin, self).__init__(*args, **kwargs) 21 | if self.pk: 22 | self._ondelta_take_snapshot() 23 | else: 24 | self._ondelta_shadow = None 25 | 26 | @cached_property 27 | def _ondelta_fields_to_watch(self): 28 | """ 29 | This gives us all the fields that we should care about changes 30 | for, excludes fields added by tests (nose adds 'c') and the id 31 | which is an implementation detail of django. 32 | 33 | Child classes may override this method to limit the set of 34 | fields watched by ondelta. 35 | """ 36 | return [f.name for f in self._meta.fields if f.name not in {'c', 'id'}] 37 | 38 | def _ondelta_take_snapshot(self): 39 | self._ondelta_shadow = copy.copy(self) 40 | 41 | def _ondelta_get_differences(self): 42 | 43 | assert self._ondelta_shadow is not None 44 | 45 | fields_changed = dict() 46 | 47 | for field_name in self._ondelta_fields_to_watch: 48 | 49 | try: 50 | snapshot_value = getattr(self._ondelta_shadow, field_name) 51 | except: 52 | logger.exception("Failed to retrieve the old value of {model}.{field} for comparison".format( 53 | model=self.__class__.__name__, 54 | field=field_name, 55 | )) 56 | continue 57 | 58 | try: 59 | current_value = getattr(self, field_name) 60 | except: 61 | logger.exception("Failed to retrieve the new value of {model}.{field} for comparison".format( 62 | model=self.__class__.__name__, 63 | field=field_name, 64 | )) 65 | continue 66 | 67 | if snapshot_value != current_value: 68 | fields_changed[field_name] = { 69 | 'old': snapshot_value, 70 | 'new': current_value, 71 | } 72 | return fields_changed 73 | 74 | def _ondelta_dispatch_notifications(self, fields_changed, recursing=False): 75 | 76 | # Take a snapshot so we can tell if anything changes inside the ondelta_* methods 77 | self._ondelta_take_snapshot() 78 | 79 | for field, changes in fields_changed.items(): 80 | 81 | # Call individual field ondelta methods 82 | method = getattr(self, 'ondelta_{field}'.format(field=field), None) 83 | if method is not None: 84 | method(changes['old'], changes['new']) 85 | 86 | # If any fields changed, call aggregate ondelta_all method 87 | self.ondelta_all(fields_changed=fields_changed) 88 | 89 | # If any fields were changed by the methods called here, recurse 90 | fields_changed_by_ondelta_methods = self._ondelta_get_differences() 91 | if fields_changed_by_ondelta_methods: 92 | self._ondelta_dispatch_notifications(fields_changed_by_ondelta_methods, recursing=True) 93 | # Once all recursive changes have been made, persist them 94 | if not recursing: 95 | self.save() 96 | 97 | def ondelta_all(self, fields_changed): 98 | """ 99 | Child classes interested in executing logic based upon 100 | aggregate field changes should override this method 101 | """ 102 | pass 103 | 104 | def save(self, *args, **kwargs): 105 | super_return = super(OnDeltaMixin, self).save(*args, **kwargs) 106 | if self._ondelta_shadow is None: 107 | self._ondelta_take_snapshot() 108 | else: 109 | fields_changed = self._ondelta_get_differences() 110 | if fields_changed: 111 | self._ondelta_dispatch_notifications(fields_changed) 112 | post_ondelta_signal.send(sender=self.__class__, fields_changed=fields_changed, instance=self) 113 | return super_return 114 | -------------------------------------------------------------------------------- /ondelta/signals.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | from django.dispatch import Signal 3 | 4 | post_ondelta_signal = Signal(providing_args=['fields_changed', 'instance']) 5 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: utf-8 -*- 3 | 4 | import os 5 | from setuptools import setup 6 | 7 | 8 | DESCRIPTION = ( 9 | "A mixin that allows models to register methods that are notified when their values change," 10 | "or register a method that is notified of all changes. Basically, OnDeltaMixin implements" 11 | "the observer pattern." 12 | ) 13 | 14 | 15 | def read(fname): 16 | """ 17 | Utility function to read the README file. 18 | Used for the long_description. It's nice, because now 1) we have a top level 19 | README file and 2) it's easier to type in the README file than to put a raw 20 | string in below ... 21 | 22 | Wrapping this in a try block because it appears that IOErrors are being throw due to README.md not making its way to pypi 23 | """ 24 | try: 25 | return open(os.path.join(os.path.dirname(__file__), fname)).read() 26 | except: 27 | return DESCRIPTION 28 | 29 | setup( 30 | name="ondelta", 31 | version="0.6.0", 32 | author="Adam Haney", 33 | author_email="adam.haney@getbellhops.com", 34 | description=DESCRIPTION, 35 | license="MIT", 36 | keywords="Django, observer", 37 | url="https://github.com/adamhaney/django-ondelta", 38 | packages=['ondelta'], 39 | long_description=read('README.md'), 40 | dependency_links=[], 41 | install_requires=[ 42 | 'django>=1.5' 43 | ], 44 | classifiers=[ 45 | 'Development Status :: 4 - Beta', 46 | 'Environment :: Web Environment', 47 | 'Framework :: Django', 48 | 'Intended Audience :: Developers', 49 | 'License :: OSI Approved :: MIT License', 50 | 'Operating System :: OS Independent', 51 | 'Programming Language :: Python', 52 | 'Programming Language :: Python :: 2', 53 | 'Programming Language :: Python :: 2.7', 54 | 'Programming Language :: Python :: 3', 55 | 'Programming Language :: Python :: 3.3', 56 | 'Programming Language :: Python :: 3.4', 57 | 'Programming Language :: Python :: Implementation :: CPython', 58 | 'Programming Language :: Python :: Implementation :: PyPy', 59 | 'Topic :: Internet :: WWW/HTTP', 60 | ], 61 | ) 62 | -------------------------------------------------------------------------------- /test_requirements.txt: -------------------------------------------------------------------------------- 1 | Django==1.11.23 2 | django-dynamic-fixture==1.8.1 3 | django-nose==1.3 4 | flake8==2.3.0 5 | ipdbplugin==1.4.1 6 | ipython==2.4.1 7 | mock==1.0.1 8 | nose==1.3.4 9 | -------------------------------------------------------------------------------- /testproject/manage.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python 2 | # -*- coding: utf-8 -*- 3 | 4 | import os 5 | import sys 6 | 7 | if __name__ == "__main__": 8 | os.environ.setdefault("DJANGO_SETTINGS_MODULE", "testproject.settings") 9 | 10 | from django.core.management import execute_from_command_line 11 | 12 | execute_from_command_line(sys.argv) 13 | -------------------------------------------------------------------------------- /testproject/testproject/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adamhaney/django-ondelta/470138fd72947f457fba3f458938f1b2b6f00d30/testproject/testproject/__init__.py -------------------------------------------------------------------------------- /testproject/testproject/settings.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | DEBUG = True 4 | 5 | DATABASES = { 6 | 'default': { 7 | 'ENGINE': 'django.db.backends.sqlite3', 8 | 'NAME': 'test.db', 9 | } 10 | } 11 | 12 | SECRET_KEY = 'foobarbaz' 13 | 14 | TEMPLATE_LOADERS = ( 15 | 'django.template.loaders.filesystem.Loader', 16 | 'django.template.loaders.app_directories.Loader', 17 | ) 18 | 19 | MIDDLEWARE_CLASSES = () 20 | 21 | INSTALLED_APPS = ( 22 | 'django_nose', 23 | 'testproject.testapp', 24 | ) 25 | 26 | TEST_RUNNER = 'django_nose.NoseTestSuiteRunner' 27 | -------------------------------------------------------------------------------- /testproject/testproject/testapp/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adamhaney/django-ondelta/470138fd72947f457fba3f458938f1b2b6f00d30/testproject/testproject/testapp/__init__.py -------------------------------------------------------------------------------- /testproject/testproject/testapp/models.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | from ondelta.models import OnDeltaMixin 4 | 5 | from django.db import models 6 | 7 | 8 | class Foo(OnDeltaMixin): 9 | 10 | char_field = models.CharField(max_length=150) 11 | char_field_delta_count = models.IntegerField(default=0) 12 | 13 | def ondelta_char_field(self, old_value, new_value): 14 | self.char_field_delta_count += 1 15 | 16 | 17 | class Bar(OnDeltaMixin): 18 | 19 | one_to_one = models.OneToOneField(Foo, related_name='one_to_one_reverse', null=True) 20 | foreign_key = models.ForeignKey(Foo, related_name='foreign_key_reverse', null=True) 21 | many_to_many = models.ManyToManyField(Foo, related_name='many_to_many_reverse') 22 | 23 | def ondelta_one_to_one(self, old, new): 24 | pass 25 | 26 | def ondelta_foreign_key(self, old, new): 27 | pass 28 | -------------------------------------------------------------------------------- /testproject/testproject/testapp/tests.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | 3 | from mock import Mock, patch, call 4 | 5 | from django.test import TestCase 6 | 7 | from django_dynamic_fixture import G, N 8 | 9 | from .models import Foo, Bar 10 | 11 | 12 | class OndeltaMethodCallUnitTests(TestCase): 13 | 14 | @patch('ondelta.models.OnDeltaMixin.ondelta_all') 15 | def setUp(self, ondelta_all_mock): 16 | 17 | self.ondelta_all_mock = ondelta_all_mock 18 | 19 | self.delta_model = Foo.objects.create(char_field='original_value') 20 | self.delta_model.ondelta_char_field = Mock() 21 | self.delta_model.char_field = 'second_value' 22 | self.delta_model.save() 23 | self.delta_model.char_field = 'third_value' 24 | 25 | # Save intentionally called twice here so we can test for idempotency 26 | self.delta_model.save() 27 | self.delta_model.save() 28 | 29 | # Intentionally not saved to test pre-save object state 30 | self.delta_model.char_field = 'fourth_value' 31 | 32 | def test_shadow_does_not_contain_unsaved_values(self): 33 | self.assertEqual(self.delta_model._ondelta_shadow.char_field, 'third_value') 34 | 35 | def test_get_differences(self): 36 | self.assertEqual( 37 | self.delta_model._ondelta_get_differences(), 38 | { 39 | 'char_field': { 40 | 'old': 'third_value', 41 | 'new': 'fourth_value', 42 | } 43 | } 44 | ) 45 | 46 | def test_dispatch_calls_single_methods_with_correct_args(self): 47 | self.delta_model.ondelta_char_field.assert_has_calls( 48 | [ 49 | call('original_value', 'second_value'), 50 | call('second_value', 'third_value') 51 | ] 52 | ) 53 | 54 | def test_dispatch_calls_ondelta_all_with_correct_args(self): 55 | self.ondelta_all_mock.assert_has_calls( 56 | [ 57 | call( 58 | fields_changed={ 59 | 'char_field': { 60 | 'old': 'original_value', 61 | 'new': 'second_value' 62 | } 63 | } 64 | ), 65 | call( 66 | fields_changed={ 67 | 'char_field': { 68 | 'old': 'second_value', 69 | 'new': 'third_value' 70 | } 71 | } 72 | ), 73 | ] 74 | ) 75 | 76 | 77 | class WorkFlowTests(TestCase): 78 | 79 | def setUp(self): 80 | self.foo = G(Foo, char_field='foo') 81 | 82 | def test_get_from_db(self): 83 | foo = Foo.objects.get(char_field='foo') 84 | foo.char_field = 'bar' 85 | foo.save() 86 | foo.char_field = 'baz' 87 | foo.save() 88 | self.assertEqual(foo.char_field_delta_count, 2) 89 | 90 | def test_create(self): 91 | foo = Foo.objects.create(char_field='foo') 92 | foo.char_field = 'bar' 93 | foo.save() 94 | foo.char_field = 'baz' 95 | foo.save() 96 | self.assertEqual(foo.char_field_delta_count, 2) 97 | 98 | def test_construct(self): 99 | foo = Foo(char_field='foo') 100 | foo.char_field = 'bar' 101 | foo.save() 102 | foo.char_field = 'baz' 103 | foo.save() 104 | self.assertEqual(foo.char_field_delta_count, 1) 105 | 106 | def test_g(self): 107 | foo = G(Foo, char_field='foo') 108 | foo.char_field = 'bar' 109 | foo.save() 110 | foo.char_field = 'baz' 111 | foo.save() 112 | self.assertEqual(foo.char_field_delta_count, 2) 113 | 114 | def test_n(self): 115 | foo = N(Foo, char_field='foo') 116 | foo.char_field = 'bar' 117 | foo.save() 118 | foo.char_field = 'baz' 119 | foo.save() 120 | self.assertEqual(foo.char_field_delta_count, 1) 121 | 122 | 123 | class SaveChangesMadeByOndeltaMethodTests(TestCase): 124 | 125 | @patch('ondelta.models.OnDeltaMixin.ondelta_all') 126 | def setUp(self, ondelta_all_mock): 127 | 128 | self.ondelta_all_mock = ondelta_all_mock 129 | 130 | self.delta_model = Foo.objects.create(char_field='original_value') 131 | self.delta_model.char_field = 'second_value' 132 | self.delta_model.save() 133 | self.delta_model.char_field = 'third_value' 134 | 135 | # Save intentionally called twice here so we can test for idempotency 136 | self.delta_model.save() 137 | self.delta_model.save() 138 | 139 | # Intentionally not saved to test pre-save object state 140 | self.delta_model.char_field = 'fourth_value' 141 | 142 | def test_model_start_unmodified(self): 143 | self.assertEqual(Foo.objects.get().char_field_delta_count, 2) 144 | self.delta_model.save() 145 | self.assertEqual(Foo.objects.get().char_field_delta_count, 3) 146 | 147 | def test_dispatch_calls_ondelta_all_with_correct_args(self): 148 | self.ondelta_all_mock.assert_has_calls( 149 | [ 150 | call( 151 | fields_changed={ 152 | 'char_field': { 153 | 'old': 'original_value', 154 | 'new': 'second_value', 155 | } 156 | } 157 | ), 158 | call( 159 | fields_changed={ 160 | 'char_field_delta_count': { 161 | 'old': 0, 162 | 'new': 1, 163 | } 164 | } 165 | ), 166 | call( 167 | fields_changed={ 168 | 'char_field': { 169 | 'old': 'second_value', 170 | 'new': 'third_value', 171 | } 172 | } 173 | ), 174 | call( 175 | fields_changed={ 176 | 'char_field_delta_count': { 177 | 'old': 1, 178 | 'new': 2, 179 | } 180 | } 181 | ), 182 | ] 183 | ) 184 | 185 | 186 | class PostOnDeltaSignalTests(TestCase): 187 | 188 | def setUp(self): 189 | self.foo = Foo.objects.create(char_field='original_value') 190 | 191 | @patch('ondelta.signals.post_ondelta_signal.send') 192 | def test_signal_generated_with_correct_kwargs_on_any_delta(self, signal_mock): 193 | signal_mock.reset_mock() 194 | self.foo.char_field='second_value' 195 | self.foo.save() 196 | signal_mock.assert_called_once_with( 197 | fields_changed={ 198 | 'char_field': { 199 | 'old': 'original_value', 200 | 'new': 'second_value', 201 | } 202 | }, 203 | instance=self.foo, 204 | sender=Foo, 205 | ) 206 | 207 | @patch('ondelta.signals.post_ondelta_signal.send') 208 | def test_signal_not_generated_when_no_changes(self, signal_mock): 209 | self.foo.save() 210 | self.assertFalse(signal_mock.called) 211 | 212 | 213 | class SupportedRelatedFieldTypeTests(TestCase): 214 | 215 | def setUp(self): 216 | self.foo = Foo.objects.create() 217 | self.bar = Bar.objects.create() 218 | 219 | @patch('testproject.testapp.models.Bar.ondelta_foreign_key') 220 | def test_foreign_key(self, fk_mock): 221 | self.bar.foreign_key = self.foo 222 | self.bar.save() 223 | fk_mock.assert_called_once_with(None, self.foo) 224 | 225 | @patch('testproject.testapp.models.Bar.ondelta_one_to_one') 226 | def test_one_to_one(self, o2o_mock): 227 | self.bar.one_to_one = self.foo 228 | self.bar.save() 229 | o2o_mock.assert_called_once_with(None, self.foo) 230 | 231 | 232 | class UnsupportedRelatedFieldTypeTests(TestCase): 233 | 234 | class add_mock_attr(object): 235 | 236 | def __init__(self, thing, attr_name): 237 | self.thing = thing 238 | self.attr_name = attr_name 239 | 240 | def __enter__(self): 241 | m = Mock() 242 | setattr(self.thing, self.attr_name, m) 243 | return m 244 | 245 | def __exit__(self, exc_type, exc_val, exc_tb): 246 | delattr(self.thing, self.attr_name) 247 | 248 | def setUp(self): 249 | self.foo = Foo.objects.create() 250 | self.bar = Bar.objects.create() 251 | 252 | def test_many_to_many(self): 253 | with self.add_mock_attr(Bar, 'ondelta_many_to_many') as m: 254 | self.bar.many_to_many.add(self.foo) 255 | self.bar.save() 256 | assert not m.called 257 | 258 | def test_foreign_key_reverse(self): 259 | with self.add_mock_attr(Foo, 'ondelta_foreign_key_reverse') as m: 260 | self.bar.foreign_key = self.foo 261 | self.bar.save() 262 | assert not m.called 263 | 264 | def test_one_to_one_reverse(self): 265 | with self.add_mock_attr(Foo, 'ondelta_one_to_one_reverse') as m: 266 | self.bar.one_to_one = self.foo 267 | self.bar.save() 268 | assert not m.called 269 | 270 | def test_many_to_many_reverse(self): 271 | with self.add_mock_attr(Foo, 'ondelta_many_to_many_reverse') as m: 272 | self.bar.many_to_many.add(self.foo) 273 | self.bar.save() 274 | assert not m.called 275 | -------------------------------------------------------------------------------- /tox.ini: -------------------------------------------------------------------------------- 1 | [tox] 2 | envlist = py27,py34 3 | 4 | [testenv] 5 | deps = -rtest_requirements.txt 6 | commands=cd testproject && python manage.py test 7 | --------------------------------------------------------------------------------