V1 rewrite (#2)

This is a complete rewrite of django-generic-notifications. It keeps the same generic idea but much more flexible and modern. The last release was before Django even had migrations - it still used South!

- The NotificationEngine has been renamed to NotificationRegistry but behaves mostly the same.
- Backends have been renamed to channels, and we now ship with 2: website and email.
- Notification types work in much the same way, except for `allowed_backends` we now have `required_channels`.

New features:

- The website channel means it's now very easy to show notifications on the website.
- Email digest with custom frequencies (daily, weekly).
- Notification grouping.
- Cleaned up and simplified. For example there's no more built-in queue, as it's not needed for the built-in channels. This allows people building custom channels to write their own processing functions that behave however they want.
- Unit tests 🎉
- Example project

Author: kevinrenskers

.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run type checking
+        run: uv run mypy .
+
+      - name: Run linting
+        run: uv run ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest
+
+  build-and-publish:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create changelog text
+        id: changelog
+        uses: loopwerk/tag-changelog@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          exclude_types: other,doc,chore,build
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.changes }}
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,20 @@
+name: Unit tests
+
+on:
+  push:
+    branches: ["*"]
+  pull_request:
+    branches: ["*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 4
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: astral-sh/setup-uv@v3
+      - run: uv python install
+      - run: uv sync --group dev
+      - run: uv run pytest

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.venv
+.claude
+.pytest_cache
+example/db.sqlite3
+/uv.lock

AUTHORS

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+
+```bash
+# Install dependencies (using uv)
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_models.py
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Type checking
+uv run .
+
+# Linting and formatting
+uv run ruff check .
+uv run ruff format .
+```
+
+## Architecture Overview
+
+This is a Django package for handling generic notifications across multiple channels (email, website, etc.) with configurable delivery frequencies.
+
+### Core Components
+
+1. **Registry Pattern** (`registry.py`): Central registry that manages notification types, channels, and frequencies. All components must be registered here to be available.
+
+2. **Notification Types** (`types.py`): Define different kinds of notifications (e.g., SystemMessage). Each type specifies:
+
+   - Default email frequency (realtime vs digest)
+   - Required channels that cannot be disabled
+   - Dynamic subject/text generation methods
+   - Custom channels can be added by subclassing `NotificationType`
+
+3. **Channels** (`channels.py`): Delivery mechanisms for notifications:
+
+   - `WebsiteChannel`: Stores in database for UI display
+   - `EmailChannel`: Sends via email (supports realtime + digest)
+   - Custom channels can be added by subclassing `NotificationChannel`
+
+4. **Frequencies** (`frequencies.py`): Email delivery timing options:
+
+   - `RealtimeFrequency`: Send immediately
+   - `DailyFrequency`: Bundle into daily digest
+   - Custom frequencies can be added by subclassing `NotificationFrequency`
+
+5. **Models** (`models.py`):
+   - `Notification`: Core notification instance with recipient, type, channels, content
+   - `DisabledNotificationTypeChannel`: Opt-out preferences (presence = disabled)
+   - `EmailFrequency`: Per-user email frequency preferences
+
+### Key Design Decisions
+
+- **Opt-out model**: Notifications are enabled by default; users disable specific type/channel combinations
+- **Channel determination at creation**: When a notification is created, enabled channels are determined and stored in the `channels` JSONField
+- **Digest processing**: Email digests are handled by a management command that queries unsent, unread notifications
+- **Generic relations**: Notifications can reference any Django model via ContentType/GenericForeignKey
+- **PostgreSQL optimization**: Uses GIN indexes for efficient JSONField queries
+
+### Common Workflows
+
+1. **Sending a notification**:
+
+   ```python
+   from generic_notifications import send_notification
+   from myapp.notifications import CommentNotification
+
+   send_notification(
+       recipient=user,
+       notification_type=CommentNotification,
+       actor=commenter,
+       target=post,
+       subject="New comment",
+       text="Someone commented on your post"
+   )
+   ```
+
+2. **Registering a new notification type**:
+
+   ```python
+   from generic_notifications.types import NotificationType, register
+
+   @register
+   class CommentNotification(NotificationType):
+       key = "comment"
+       name = "Comments"
+       description = "When someone comments on your content"
+       default_email_frequency = DailyFrequency
+   ```
+
+3. **User preferences**: Managed through `DisabledNotificationTypeChannel` and `EmailFrequency` models

CHANGELOG

@@ -1,27 +1,21 @@
-Copyright (c) 2011, Kevin Renskers and individual contributors.
-All rights reserved.
+MIT License
 
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
+Copyright (c) Loopwerk
 
-    1. Redistributions of source code must retain the above copyright notice,
-       this list of conditions and the following disclaimer.
+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:
 
-    2. Redistributions in binary form must reproduce the above copyright
-       notice, this list of conditions and the following disclaimer in the
-       documentation and/or other materials provided with the distribution.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-    3. Neither the name of django-generic-notifications nor the names of its
-       contributors may be used to endorse or promote products derived from
-       this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+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.