Merge pull request #26 from craigds/cds-modernization

Modernize packaging and add type hints

Author: craigds

.github/workflows/test.yml

@@ -1,27 +1,42 @@
 name: tests
 
 on:
-  - push
-  - pull_request
+  push:
+    branches: [master]
+  pull_request:
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ["3.6", "3.8", "3.10"]
+        python-version: ["3.8", "3.10", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox tox-gh-actions
+        run: uv pip install --system tox tox-uv tox-gh-actions
       - name: Test with tox
-        env:
-          FORCE_COLOR: "YES"
         run: tox
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: uv pip install --system ruff
+      - name: Run ruff
+        run: ruff check .

.gitignore

@@ -7,3 +7,7 @@ __pycache__/
 .tox
 .python-version
 .vscode/
+.ruff_cache/
+uv.lock
+
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+django-fieldsignals provides Django signals that fire when specific model fields change. It exposes two signals: `pre_save_changed` and `post_save_changed`, which work like Django's built-in `pre_save`/`post_save` but only trigger when specified fields have actually changed.
+
+## Commands
+
+```bash
+# Run tests (requires Django to be installed)
+pytest -v
+
+# Run tests across all supported Python/Django versions
+tox
+
+# Run a single test
+pytest -v fieldsignals/tests/test_signals.py::TestPreSave::test_pre_save_changed
+
+# Lint
+ruff check .
+
+# Type check
+tox -e mypy
+```
+
+## Architecture
+
+The library is small:
+- `fieldsignals/signals.py` - Core implementation with `ChangedSignal` base class and `PreSaveChangedSignal`/`PostSaveChangedSignal` subclasses
+- `fieldsignals/__init__.py` - Exports `pre_save_changed` and `post_save_changed` signal instances
+
+Key design points:
+- Signals must be connected after the Django app registry is ready (in `AppConfig.ready()`)
+- Field change tracking stores original values on the model instance in `_fieldsignals_originals`
+- Deferred fields are excluded from change detection
+- No support for `ManyToManyField` or reverse FK relations

MANIFEST.in

@@ -1,3 +1,6 @@
-from .signals import pre_save_changed, post_save_changed  # noqa
+from __future__ import annotations
 
-__version__ = (0, 6, 0)
+from .signals import post_save_changed, pre_save_changed
+
+__all__ = ["post_save_changed", "pre_save_changed"]
+__version__ = "0.8.0"

fieldsignals/__init__.py

@@ -1,16 +1,23 @@
+from __future__ import annotations
+
 from copy import deepcopy
+from typing import TYPE_CHECKING, Any
 
 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.db.models.fields.related import ForeignObjectRel
 from django.dispatch import Signal
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Hashable
+
+    from django.db import models
 
 __all__ = ("pre_save_changed", "post_save_changed")
 
 
-IMMUTABLE_TYPES_WHITELIST = tuple([tuple, frozenset, float, str, int])
+IMMUTABLE_TYPES_WHITELIST: tuple[type, ...] = (tuple, frozenset, float, str, int)
 
 
 class ChangedSignal(Signal):
@@ -19,7 +26,14 @@ class ChangedSignal(Signal):
     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):
+    def connect(  # type: ignore[override]
+        self,
+        receiver: Callable[..., Any],
+        sender: type[models.Model] | None = None,
+        fields: list[str] | None = None,
+        dispatch_uid: Hashable | None = None,
+        **kwargs: Any,
+    ) -> None:
         """
         Connect a FieldSignal. Usage::
 
@@ -28,7 +42,7 @@ def connect(self, receiver, sender=None, fields=None, dispatch_uid=None, **kwarg
 
         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)
+            # (This error would be raised below anyway, but we want 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."
@@ -48,40 +62,41 @@ def connect(self, receiver, sender=None, fields=None, dispatch_uid=None, **kwarg
         if not isinstance(sender, type):
             raise ValueError("sender should be a model class")
 
-        def is_reverse_rel(f):
+        def is_reverse_rel(f: Any) -> bool:
             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)]
+            resolved_fields = sender._meta.get_fields()
+            resolved_fields = [f for f in resolved_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:
+            resolved_fields = [f for f in sender._meta.get_fields() if f.name in set(fields)]
+            for f in resolved_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)
+                        f"({f.name} is a {f.__class__.__name__})"
                     )
 
-        if not fields:
+        if not resolved_fields:
             raise ValueError("fields must be non-empty")
 
-        proxy_receiver = self._make_proxy_receiver(receiver, sender, fields)
+        proxy_receiver = self._make_proxy_receiver(receiver, sender, resolved_fields)
 
-        super(ChangedSignal, self).connect(
-            proxy_receiver, sender=sender, weak=False, dispatch_uid=dispatch_uid
-        )
+        super().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)
+        def post_init_closure(sender: type, instance: models.Model, **kwargs: Any) -> None:
+            self.get_and_update_changed_fields(receiver, instance, resolved_fields)
 
         _signals.post_init.connect(
-            post_init_closure, sender=sender, weak=False, dispatch_uid=(self, receiver)
+            post_init_closure,
+            sender=sender,
+            weak=False,
+            dispatch_uid=(self, receiver),  # type: ignore[arg-type]
         )
         self.connect_source_signals(sender)
 
-    def connect_source_signals(self, sender):
+    def connect_source_signals(self, sender: type) -> None:
         """
         Connects the source signals required to trigger updates for this
         ChangedSignal.
@@ -91,30 +106,41 @@ def connect_source_signals(self, sender):
         # override in subclasses
         pass
 
-    def _make_proxy_receiver(self, receiver, sender, fields):
+    def _make_proxy_receiver(
+        self,
+        receiver: Callable[..., Any],
+        sender: type,
+        fields: list[Any],
+    ) -> Callable[..., Any]:
         """
         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
-            )
+        def pr(instance: Any, *args: Any, **kwargs: Any) -> None:
+            changed_fields = self.get_and_update_changed_fields(receiver, instance, fields)
             if changed_fields:
                 receiver(
-                    instance=instance, changed_fields=changed_fields, *args, **kwargs
+                    *args,
+                    instance=instance,
+                    changed_fields=changed_fields,
+                    **kwargs,
                 )
 
-        pr._original_receiver = receiver
-        pr._fields = fields
+        pr._original_receiver = receiver  # type: ignore[attr-defined]
+        pr._fields = fields  # type: ignore[attr-defined]
 
         pr.__doc__ = receiver.__doc__
         pr.__name__ = receiver.__name__
         return pr
 
-    def get_and_update_changed_fields(self, receiver, instance, fields):
+    def get_and_update_changed_fields(
+        self,
+        receiver: Callable[..., Any],
+        instance: Any,
+        fields: list[Any],
+    ) -> dict[str, tuple[Any, Any]]:
         """
         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
@@ -135,7 +161,7 @@ def get_and_update_changed_fields(self, receiver, instance, fields):
         if key not in instance._fieldsignals_originals:
             instance._fieldsignals_originals[key] = {}
         originals = instance._fieldsignals_originals[key]
-        changed_fields = {}
+        changed_fields: dict[str, tuple[Any, Any]] = {}
 
         deferred_fields = instance.get_deferred_fields()
 
@@ -159,24 +185,35 @@ def get_and_update_changed_fields(self, receiver, instance, fields):
 
 
 class PreSaveChangedSignal(ChangedSignal):
-    def _on_model_pre_save(self, sender, instance=None, **kwargs):
+    def _on_model_pre_save(
+        self, sender: type, instance: Any = None, **kwargs: Any
+    ) -> list[tuple[Callable[..., Any], Any]]:
         return self.send(sender, instance=instance)
 
-    def connect_source_signals(self, sender):
+    def connect_source_signals(self, sender: type) -> None:
         _signals.pre_save.connect(
-            self._on_model_pre_save, sender=sender, dispatch_uid=id(self)
+            self._on_model_pre_save,
+            sender=sender,
+            dispatch_uid=id(self),  # type: ignore[arg-type]
         )
 
 
 class PostSaveChangedSignal(ChangedSignal):
     def _on_model_post_save(
-        self, sender, instance=None, created=None, using=None, **kwargs
-    ):
+        self,
+        sender: type,
+        instance: Any = None,
+        created: bool | None = None,
+        using: str | None = None,
+        **kwargs: Any,
+    ) -> list[tuple[Callable[..., Any], Any]]:
         return self.send(sender, instance=instance, created=created, using=using)
 
-    def connect_source_signals(self, sender):
+    def connect_source_signals(self, sender: type) -> None:
         _signals.post_save.connect(
-            self._on_model_post_save, sender=sender, dispatch_uid=id(self)
+            self._on_model_post_save,
+            sender=sender,
+            dispatch_uid=id(self),  # type: ignore[arg-type]
         )
 
 

fieldsignals/py.typed

@@ -1,2 +1 @@
-import os
-from .test_signals import *
+# Tests are discovered by pytest, no need to export here

fieldsignals/signals.py

@@ -0,0 +1,3 @@
+SECRET_KEY = "test"
+INSTALLED_APPS = ["fieldsignals"]
+USE_TZ = True