pax_global_header00006660000000000000000000000064141063706010014510gustar00rootroot0000000000000052 comment=4e7ccad5fd6f51da9d1b65e26099aa76cb49918f django-fieldsignals-0.7.0/000077500000000000000000000000001410637060100154205ustar00rootroot00000000000000django-fieldsignals-0.7.0/.gitignore000066400000000000000000000001071410637060100174060ustar00rootroot00000000000000build/ dist/ *.egg-info/ __pycache__/ *.pyc *.pyo .tox .python-version django-fieldsignals-0.7.0/.travis.yml000066400000000000000000000006541410637060100175360ustar00rootroot00000000000000sudo: false language: python python: # All supported djangoes work with python 3.7, so let's just use that. # Running tests in all supported pythons feels like overkill. # Run with `tox` locally if you really want to test other pythons; they're all listed in tox.ini - "3.7" env: - DJANGO="Django~=2.2.8" - DJANGO="Django~=3.1.9" - DJANGO="Django~=3.2.0" install: pip install $DJANGO script: python setup.py test django-fieldsignals-0.7.0/LICENSE000066400000000000000000000021161410637060100164250ustar00rootroot00000000000000django-fieldsignals ------------------- Copyright (c) 2011, Craig de Stigter Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. django-fieldsignals-0.7.0/MANIFEST.in000066400000000000000000000001661410637060100171610ustar00rootroot00000000000000include LICENSE include README.rst recursive-include fieldsignals/static * recursive-include fieldsignals/templates * django-fieldsignals-0.7.0/README.md000066400000000000000000000045121410637060100167010ustar00rootroot00000000000000[![Build Status](https://travis-ci.org/craigds/django-fieldsignals.svg?branch=master)](https://travis-ci.org/craigds/django-fieldsignals) # Introduction django-fieldsignals simply makes it easy to tell when the fields on your model have changed. Often model updates are quite expensive. Sometimes the expensive operations are very rare. This makes it tempting to put the update logic in a view, rather than in a save() method or in a signal receiver: ```python # A bad example. Don't do this! def edit_poll(request, poll_id): # ... if form.cleaned_data['poll_name'] != poll.name: poll.update_slug(form.cleaned_data['poll_name']) poll.save() ``` That's a bad idea, because your model consistency is now dependent on your view. Instead, use django-fieldsignals: ```python from fieldsignals import pre_save_changed def update_poll_slug(sender, instance, **kwargs): instance.slug = slugify(instance.name) pre_save_changed.connect(update_poll_slug, sender=Poll, fields=['name']) ``` In case you want to know what changed, django-fieldsignals even tells you the old and new values of your fields: ```python from fieldsignals import pre_save_changed def print_all_field_changes(sender, instance, changed_fields, **kwargs): for field, (old, new) in changed_fields.items(): print(f'{field.name} changed from {old} to {new}') pre_save_changed.connect(print_all_field_changes, sender=Poll) ``` # Installation 1. This library is on PyPI so you can install it with: ```bash pip install django-fieldsignals ``` or from github: ```bash pip install 'git+https://github.com/craigds/django-fieldsignals.git#egg=django-fieldsignals' ``` 2. Add `"fieldsignals"` to your `INSTALLED_APPS` setting like this: ```python INSTALLED_APPS = ( ... 'fieldsignals', ) ``` 3. Add some signals! # Where should my signals code live? Field signals must be connected after the django apps are ready. So putting signal connectors at the bottom of your models file, or other random places won't work. The best place to connect fieldsignals is an [`AppConfig.ready()` handler](https://docs.djangoproject.com/en/1.11/ref/applications/#for-application-authors). # Notes * Currently no support for `ManyToManyField` or reverse side of `ForeignKey` (one to many). django-fieldsignals-0.7.0/fieldsignals/000077500000000000000000000000001410637060100200645ustar00rootroot00000000000000django-fieldsignals-0.7.0/fieldsignals/__init__.py000066400000000000000000000001321410637060100221710ustar00rootroot00000000000000from .signals import pre_save_changed, post_save_changed # noqa __version__ = (0, 6, 0) django-fieldsignals-0.7.0/fieldsignals/signals.py000066400000000000000000000160511410637060100221010ustar00rootroot00000000000000from copy import deepcopy from django.apps import apps from django.core.exceptions import AppRegistryNotReady from django.db.models.fields.related import ForeignObjectRel from django.db.models import signals as _signals from django.dispatch import Signal __all__ = ("pre_save_changed", "post_save_changed") IMMUTABLE_TYPES_WHITELIST = tuple([tuple, frozenset, float, str, int]) class ChangedSignal(Signal): """ A Signal which can be connected for a list of fields (or field names). The given receiver is only called when one or more of the given fields has changed. """ def connect(self, receiver, sender=None, fields=None, dispatch_uid=None, **kwargs): """ Connect a FieldSignal. Usage:: foo.connect(func, sender=MyModel, fields=['myfield1', 'myfield2']) """ if not apps.models_ready: # We require access to Model._meta.get_fields(), which isn't available yet. # (This error would be raised below anyway, but we want to add a more meaningful message) raise AppRegistryNotReady( "django-fieldsignals signals must be connected after the app cache is ready. " "Connect the signal in your AppConfig.ready() handler." ) # Validate arguments if kwargs.get("weak", False): # TODO: weak refs? I'm hella confused. # We can't go passing our proxy receivers around as weak refs, since they're # defined as closures and hence don't exist by the time they're called. # However, we can probably make _make_proxy_receiver() create weakrefs to # the original receiver if required. Patches welcome raise NotImplementedError("This signal doesn't yet handle weak refs") # Check it's a class, don't check if it's a model class (useful for tests) if not isinstance(sender, type): raise ValueError("sender should be a model class") def is_reverse_rel(f): return f.many_to_many or f.one_to_many or isinstance(f, ForeignObjectRel) if fields is None: fields = sender._meta.get_fields() fields = [f for f in fields if not is_reverse_rel(f)] else: fields = [f for f in sender._meta.get_fields() if f.name in set(fields)] for f in fields: if is_reverse_rel(f): raise ValueError( "django-fieldsignals doesn't handle reverse related fields " "({f.name} is a {f.__class__.__name__})".format(f=f) ) if not fields: raise ValueError("fields must be non-empty") proxy_receiver = self._make_proxy_receiver(receiver, sender, fields) super(ChangedSignal, self).connect( proxy_receiver, sender=sender, weak=False, dispatch_uid=dispatch_uid ) ### post_init : initialize the list of fields for each instance def post_init_closure(sender, instance, **kwargs): self.get_and_update_changed_fields(receiver, instance, fields) _signals.post_init.connect( post_init_closure, sender=sender, weak=False, dispatch_uid=(self, receiver) ) self.connect_source_signals(sender) def connect_source_signals(self, sender): """ Connects the source signals required to trigger updates for this ChangedSignal. (post_init has already been connected during __init__) """ # override in subclasses pass def _make_proxy_receiver(self, receiver, sender, fields): """ Takes a receiver function and creates a closure around it that knows what fields to watch. The original receiver is called for an instance iff the value of at least one of the fields has changed since the last time it was called. """ def pr(instance, *args, **kwargs): changed_fields = self.get_and_update_changed_fields( receiver, instance, fields ) if changed_fields: receiver( instance=instance, changed_fields=changed_fields, *args, **kwargs ) pr._original_receiver = receiver pr._fields = fields pr.__doc__ = receiver.__doc__ pr.__name__ = receiver.__name__ return pr def get_and_update_changed_fields(self, receiver, instance, fields): """ Takes a receiver and a model instance, and a list of field instances. Gets the old and new values for each of the given fields, and stores their new values for next time. Returns a dict like this: { "fieldname1" : ("old value", "new value"), } """ # instance._fieldsignals_originals looks like this: # { # (id(), id()) : {"field_name": "old value",}, # } key = (id(self), id(receiver)) if not hasattr(instance, "_fieldsignals_originals"): instance._fieldsignals_originals = {} if key not in instance._fieldsignals_originals: instance._fieldsignals_originals[key] = {} originals = instance._fieldsignals_originals[key] changed_fields = {} deferred_fields = instance.get_deferred_fields() for field in fields: if field.attname in deferred_fields: continue # using value_from_object instead of getattr() means we don't traverse foreignkeys new_value = field.to_python(field.value_from_object(instance)) old_value = originals.get(field.name, None) if old_value != new_value: if not isinstance(new_value, IMMUTABLE_TYPES_WHITELIST): # For mutable types, make a copy of the value before storing it. # Otherwise, the 'originals' dict may well get modified elsewhere, and # that's going to make change detection impossible new_value = deepcopy(new_value) changed_fields[field.name] = (old_value, new_value) # now update, for next time originals[field.name] = new_value return changed_fields class PreSaveChangedSignal(ChangedSignal): def _on_model_pre_save(self, sender, instance=None, **kwargs): return self.send(sender, instance=instance) def connect_source_signals(self, sender): _signals.pre_save.connect( self._on_model_pre_save, sender=sender, dispatch_uid=id(self) ) class PostSaveChangedSignal(ChangedSignal): def _on_model_post_save( self, sender, instance=None, created=None, using=None, **kwargs ): return self.send(sender, instance=instance, created=created, using=using) def connect_source_signals(self, sender): _signals.post_save.connect( self._on_model_post_save, sender=sender, dispatch_uid=id(self) ) ### API: pre_save_changed = PreSaveChangedSignal() post_save_changed = PostSaveChangedSignal() # TODO other signals? django-fieldsignals-0.7.0/fieldsignals/tests/000077500000000000000000000000001410637060100212265ustar00rootroot00000000000000django-fieldsignals-0.7.0/fieldsignals/tests/__init__.py000066400000000000000000000000461410637060100233370ustar00rootroot00000000000000import os from .test_signals import * django-fieldsignals-0.7.0/fieldsignals/tests/test_signals.py000066400000000000000000000203361410637060100243030ustar00rootroot00000000000000import datetime from contextlib import contextmanager from collections import namedtuple import pytest from django.apps import apps from django.core.exceptions import AppRegistryNotReady from django.db.models.fields.related import OneToOneRel from django.db.models.signals import post_save, post_init, pre_save from django.utils.dateparse import parse_datetime from django.utils.timezone import utc from fieldsignals.signals import post_save_changed, pre_save_changed _field = namedtuple("field", ["name"]) @contextmanager def must_be_called(must=True): x = {"called": False} def func(*args, **kwargs): x["called"] = True func.args = args func.kwargs = kwargs func.args = None func.kwargs = None yield func if x["called"] and not must: raise AssertionError("Function was called, shouldn't have been") elif must and not x["called"]: raise AssertionError("Function wasn't called, should have been") class Called(Exception): pass def func(*args, **kwargs): raise Called class Field(object): def __init__(self, name, m2m=False): self.name = name self.attname = name self.many_to_many = m2m self.one_to_many = False def value_from_object(self, instance): return getattr(instance, self.name) def to_python(self, value): return value class DateTimeField(Field): def to_python(self, value): # approximate a datetime field if value is None: return value if isinstance(value, datetime.datetime): return value return parse_datetime(value) class FakeModel(object): a_key = "a value" another = "something else" m2m = [] a_datetime = None class _meta(object): @staticmethod def get_fields(): return [ Field("a_key"), Field("another"), Field("m2m", m2m=True), DateTimeField("a_datetime"), ] def get_deferred_fields(self): return set() class DeferredModel(object): a = 1 class _meta(object): @staticmethod def get_fields(): return [ Field("a"), Field("b"), ] def get_deferred_fields(self): return {"b"} class MockOneToOneRel(OneToOneRel): def __init__(self, name): self.name = name self.many_to_many = False self.one_to_many = False class FakeModelWithOneToOne(object): f = "a value" o2o = 1 class _meta(object): @staticmethod def get_fields(): return [Field("f"), MockOneToOneRel("o2o")] class TestGeneral(object): @pytest.fixture(autouse=True) def ready(self): apps.models_ready = True def test_m2m_fields_error(self): with must_be_called(False) as func: with pytest.raises(ValueError): post_save_changed.connect(func, sender=FakeModel, fields=("m2m",)) def test_one_to_one_rel_field_error(self): with must_be_called(False) as func: with pytest.raises(ValueError): post_save_changed.connect( func, sender=FakeModelWithOneToOne, fields=("o2o", "f") ) def test_one_to_one_rel_excluded(self): with must_be_called(False) as func: post_save_changed.connect(func, sender=FakeModelWithOneToOne) def test_app_cache_not_ready(self): apps.models_ready = False with pytest.raises(AppRegistryNotReady): post_save_changed.connect(func, sender=FakeModel) def test_compare_after_to_python(self): """ Field values (e.g. datetimes) are equal even if set via string. Ensures that to_python() is called prior to comparison between old & new values. """ with must_be_called(False) as func: pre_save_changed.connect(func, sender=FakeModel, fields=("a_datetime",)) obj = FakeModel() obj.a_datetime = "2017-01-01T00:00:00.000000Z" post_init.send(instance=obj, sender=FakeModel) # This is identical to the above, even though the type is different, # so don't call the signal obj.a_datetime = datetime.datetime(2017, 1, 1, 0, 0, 0, 0, utc) pre_save.send(instance=obj, sender=FakeModel) def test_deferred_fields(self): pre_save_changed.connect(func, sender=DeferredModel) obj = DeferredModel() post_init.send(instance=obj, sender=DeferredModel) assert list(obj._fieldsignals_originals.values()) == [{"a": 1}] class TestPostSave(object): @pytest.fixture(autouse=True) def ready(self): apps.models_ready = True def test_post_save_unchanged(self): with must_be_called(False) as func: post_save_changed.connect(func, sender=FakeModel) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) # This *doesn't* call post_save_changed, because we haven't changed anything. post_save.send(instance=obj, sender=FakeModel) def test_post_save_changed(self): with must_be_called(True) as func: post_save_changed.connect(func, sender=FakeModel) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) obj.a_key = "another value" post_save.send(instance=obj, sender=FakeModel) assert func.kwargs["changed_fields"] == {"a_key": ("a value", "another value")} def test_post_save_with_fields_changed(self): with must_be_called(True) as func: post_save_changed.connect(func, sender=FakeModel, fields=("a_key",)) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) obj.a_key = "change a field that we care about" post_save.send(instance=obj, sender=FakeModel) assert func.kwargs["changed_fields"] == { "a_key": ("a value", "change a field that we care about") } def test_post_save_with_fields_unchanged(self): with must_be_called(False) as func: post_save_changed.connect(func, sender=FakeModel, fields=("a_key",)) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) obj.another = "dont care about this field" post_save.send(instance=obj, sender=FakeModel) class TestPreSave(object): @pytest.fixture(autouse=True) def unready(self): apps.models_ready = True def test_pre_save_unchanged(self): with must_be_called(False) as func: pre_save_changed.connect(func, sender=FakeModel) obj = FakeModel() # post_init sets list of initial values post_init.send(instance=obj, sender=FakeModel) # This *doesn't* call pre_save_changed, because we haven't changed anything. pre_save.send(instance=obj, sender=FakeModel) def test_pre_save_changed(self): with must_be_called(True) as func: pre_save_changed.connect(func, sender=FakeModel) obj = FakeModel() # post_init sets list of initial values post_init.send(instance=obj, sender=FakeModel) obj.a_key = "another value" pre_save.send(instance=obj, sender=FakeModel) assert func.kwargs["changed_fields"] == {"a_key": ("a value", "another value")} def test_pre_save_with_fields_changed(self): with must_be_called(True) as func: pre_save_changed.connect(func, sender=FakeModel, fields=("a_key",)) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) obj.a_key = "change a field that we care about" pre_save.send(instance=obj, sender=FakeModel) assert func.kwargs["changed_fields"] == { "a_key": ("a value", "change a field that we care about") } def test_pre_save_with_fields_unchanged(self): with must_be_called(False) as func: pre_save_changed.connect(func, sender=FakeModel, fields=("a_key",)) obj = FakeModel() post_init.send(instance=obj, sender=FakeModel) obj.another = "dont care about this field" pre_save.send(instance=obj, sender=FakeModel) django-fieldsignals-0.7.0/pyproject.toml000066400000000000000000000000471410637060100203350ustar00rootroot00000000000000[tool.black] target-version = ['py36'] django-fieldsignals-0.7.0/setup.cfg000066400000000000000000000000721410637060100172400ustar00rootroot00000000000000[flake8] max-line-length = 99 [bdist_wheel] universal = 1 django-fieldsignals-0.7.0/setup.py000066400000000000000000000025171410637060100171370ustar00rootroot00000000000000import os from setuptools import setup try: README = open(os.path.join(os.path.dirname(__file__), "README.md")).read() except: README = "" # allow setup.py to be run from any path os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) setup( name="django-fieldsignals", version="0.7.0", packages=["fieldsignals", "fieldsignals.tests"], include_package_data=True, test_suite="fieldsignals.tests.test_signals", description="Django fieldsignals simply makes it easy to tell when the fields on your model have changed.", long_description=README, long_description_content_type="text/markdown", url="https://github.com/craigds/django-fieldsignals", author="Craig de Stigter", author_email="craig.ds@gmail.com", classifiers=[ "Environment :: Web Environment", "Framework :: Django", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: Dynamic Content", ], ) django-fieldsignals-0.7.0/tox.ini000066400000000000000000000005211410637060100167310ustar00rootroot00000000000000[tox] envlist = # Any supported combination of python & django. # min/max python versions for each django version are listed here {py35,py39}-{dj22} {py36,py39}-{dj31} {py36,py39}-{dj32} [testenv] commands = pytest {posargs} deps = pytest dj22: Django~=2.2.17 dj31: Django~=3.1.9 dj32: Django~=3.2.0