{"id":34498081,"url":"https://github.com/loopwerk/django-generic-notifications","last_synced_at":"2025-12-24T01:52:49.772Z","repository":{"id":1817959,"uuid":"2742152","full_name":"loopwerk/django-generic-notifications","owner":"loopwerk","description":"A flexible, multi-channel notification system for Django applications with built-in support for email digests, user preferences, and extensible delivery channels.","archived":false,"fork":false,"pushed_at":"2025-11-18T11:04:45.000Z","size":197,"stargazers_count":84,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-11-18T15:10:33.042Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"facebook/react-native","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loopwerk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"loopwerk","buy_me_a_coffee":"loopwerk"}},"created_at":"2011-11-09T14:46:52.000Z","updated_at":"2025-11-18T11:04:39.000Z","dependencies_parsed_at":"2025-10-18T18:06:48.958Z","dependency_job_id":null,"html_url":"https://github.com/loopwerk/django-generic-notifications","commit_stats":null,"previous_names":["loopwerk/django-generic-notifications"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/loopwerk/django-generic-notifications","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwerk%2Fdjango-generic-notifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwerk%2Fdjango-generic-notifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwerk%2Fdjango-generic-notifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwerk%2Fdjango-generic-notifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loopwerk","download_url":"https://codeload.github.com/loopwerk/django-generic-notifications/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopwerk%2Fdjango-generic-notifications/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27992768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-23T02:00:07.087Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T01:52:49.142Z","updated_at":"2025-12-24T01:52:49.739Z","avatar_url":"https://github.com/loopwerk.png","language":"Python","readme":"# Django Generic Notifications\n\nA flexible, multi-channel notification system for Django applications with built-in support for email digests, user preferences, and extensible delivery channels.\n\n## Features\n\n- **Multi-channel delivery**: Send notifications through multiple channels (website, email, and custom channels)\n- **Flexible delivery frequencies**: Support for real-time and digest delivery (daily, or custom schedules)\n- **Notification grouping**: Prevent repeated notifications by grouping notifications based on your own custom logic\n- **User preferences**: Fine-grained control over notification types and delivery channels\n- **Extensible architecture**: Easy to add custom notification types, channels, and frequencies\n- **Generic relations**: Link notifications to any Django model\n- **Template support**: Customizable email templates for each notification type\n- **Developer friendly**: Simple API for sending notifications with automatic channel routing\n- **Full type hints**: Complete type annotations for better IDE support and type checking\n\n## Requirements\n\n- Python \u003e= 3.10\n- Django \u003e= 4.2.0\n- `django.contrib.contenttypes` must be in `INSTALLED_APPS`\n\n## Installation\n\nAll instruction in this document use [uv](https://github.com/astral-sh/uv), but of course pip or Poetry will also work just fine.\n\n```bash\nuv add django-generic-notifications\n```\n\nAdd to your `INSTALLED_APPS`:\n\n```python\nINSTALLED_APPS = [\n    ...\n    \"django.contrib.contenttypes\",  # Required dependency\n    \"generic_notifications\",\n    ...\n]\n```\n\nRun migrations:\n\n```bash\nuv run ./manage.py migrate generic_notifications\n```\n\n## Settings\n\n### `NOTIFICATION_BASE_URL`\n\nConfigure the base URL for generating absolute URLs in email notifications:\n\n```python\n# With protocol (recommended)\nNOTIFICATION_BASE_URL = \"https://www.example.com\"\nNOTIFICATION_BASE_URL = \"http://localhost:8000\"\n\n# Without protocol (auto-detects based on DEBUG setting)\nNOTIFICATION_BASE_URL = \"www.example.com\"\n```\n\n**Protocol handling**: If you omit the protocol, it's automatically added:\n\n- `https://` in production (`DEBUG = False`)\n- `http://` in development (`DEBUG = True`)\n\n**Fallback order** if `NOTIFICATION_BASE_URL` is not set:\n\n1. `BASE_URL` setting\n2. `SITE_URL` setting\n3. Django Sites framework (if `django.contrib.sites` is installed)\n4. URLs remain relative if no base URL is found (not ideal in emails!)\n\n## Quick Start\n\n### 1. Define a notification type\n\n```python\n# myapp/notifications.py\nfrom generic_notifications.types import NotificationType, register\n\n@register\nclass CommentNotification(NotificationType):\n    key = \"comment\"\n    name = \"Comment Notifications\"\n    description = \"When someone comments on your posts\"\n```\n\n### 2. Send a notification\n\n```python\nfrom generic_notifications import send_notification\nfrom myapp.notifications import CommentNotification\n\n# Send a notification (only `recipient` and `notification_type` are required)\nnotification = send_notification(\n    recipient=post.author,\n    notification_type=CommentNotification,\n    actor=comment.user,\n    target=post,\n    subject=f\"{comment.user.get_full_name()} commented on your post\",\n    text=f\"{comment.user.get_full_name()} left a comment: {comment.text[:100]}\",\n    url=f\"/posts/{post.id}#comment-{comment.id}\",\n)\n```\n\n### 3. Working with notifications\n\n```python\nfrom generic_notifications.channels import WebsiteChannel\nfrom generic_notifications.models import Notification\nfrom generic_notifications.lib import get_unread_count, get_notifications, mark_notifications_as_read\n\n# Get unread count for a user\nunread_count = get_unread_count(user=user, channel=WebsiteChannel)\n\n# Get unread notifications for a user\nunread_notifications = get_notifications(user=user, channel=WebsiteChannel, unread_only=True)\n\n# Get notifications by channel\nwebsite_notifications = Notification.objects.prefetch().for_channel(WebsiteChannel)\n\n# Mark as read\nnotification = website_notifications.first()\nnotification.mark_as_read()\n\n# Mark all as read\nmark_notifications_as_read(user=user)\n```\n\n### 4. Set up email digest sending\n\nCreate a cron job to send daily digests:\n\n```bash\n# Send daily digests at 9 AM\n0 9 * * * cd /path/to/project \u0026\u0026 uv run ./manage.py send_notification_digests --frequency daily\n```\n\nIf you already have a way to run scheduled jobs in your Django app and don't want to start a management command via a cron job, you can call the `send_notification_digests` function directly:\n\n```python\nfrom generic_notifications.digest import send_notification_digests\nfrom generic_notifications.frequencies import DailyFrequency\n\nsend_notification_digests(frequency=DailyFrequency, dry_run=False)\n```\n\n## Example App\n\nAn example app is provided, which shows how to create a custom notification type, how to send a notification, it has a nice looking notification center with unread notifications as well as an archive of all read notifications, plus a settings view where you can manage notification preferences.\n\n```bash\ncd example\nuv run ./manage.py migrate\nuv run ./manage.py runserver\n```\n\nThen open http://127.0.0.1:8000/.\n\n## Admin Integration\n\nWhile the library doesn't register admin classes by default, the example app includes [admin configuration](https://github.com/loopwerk/django-generic-notifications/tree/main/example/notifications/admin.py) that you can copy into your project for debugging and monitoring purposes.\n\n## Further Documentation\n\n- [Migrate to a newer version of this library](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/migrate.md)\n- [Customization: custom channels, frequencies, and email templates](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/customizing.md)\n- [Performance considerations and tips](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/performance.md)\n- [Notification grouping: prevent notification spam by grouping similar notifications together](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/grouping.md)\n- [Supporting multilingual notifications](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/multilingual.md)\n- [User preferences: how to manage user preferences](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/preferences.md)\n- [Development: workflows for working on this library](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/development.md)\n\n## Sponsored By\n\nA huge thanks goes to https://dskrpt.de/ for sponsoring development of django-generic-notifications.\n\n## License\n\nMIT License - see LICENSE file for details.\n","funding_links":["https://github.com/sponsors/loopwerk","https://buymeacoffee.com/loopwerk"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwerk%2Fdjango-generic-notifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floopwerk%2Fdjango-generic-notifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopwerk%2Fdjango-generic-notifications/lists"}