notification-kit 1.0.0__tar.gz

notification_kit-1.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: notification-kit
+Version: 1.0.0
+Summary: Reusable, extensible Django notification framework
+License: MIT
+Keywords: django,notifications,email,sms,push,celery,django-app
+Author: Sercan Tatar
+Author-email: sercan@everionconsulting.com
+Requires-Python: >=3.10,<4.0
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: celery (>=5.3,<6.0)
+Requires-Dist: django (>=4.2)
+Requires-Dist: djangorestframework (>=3.14,<4.0)
+Project-URL: Documentation, https://github.com/gulergokce/django-notification-kit
+Project-URL: Homepage, https://github.com/gulergokce/django-notification-kit
+Project-URL: Repository, https://github.com/gulergokce/django-notification-kit
+Description-Content-Type: text/markdown
+
+🚀 Django Notification Kit
+Django Notification Kit, Django projeleri için tasarlanmış; çok kanallı (Email / SMS / Push) bildirim gönderimini yöneten, modüler ve genişletilebilir bir altyapıdır. Sistemin temel amacı; bildirim gönderim süreçlerini API – Service – Backend – Task katmanlarına ayırarak yüksek test edilebilirlik ve sürdürülebilirlik sağlamaktır.
+
+
+
+🎯 Kapsam (v1.0.0 – MVP)
+Bu versiyon, profesyonel bir bildirim sistemi için gerekli olan şu temel bileşenleri sunar:
+
+✅ Abstract Model Yapısı: Genişletilmeye hazır taban modeller.
+
+✅ Concrete Modeller: Notification, Template, Preference ve Log yapıları.
+
+✅ SMTP Email Backend: Standart e-posta gönderim desteği.
+
+✅ Base Notification Service: İş mantığını yöneten merkezi servis.
+
+✅ Celery Task Factory: Ölçeklenebilir, asenkron gönderim desteği.
+
+✅ DRF API: Standartlara uygun API uçları ve Serializer'lar.
+
+✅ Merkezi Ayar Yönetimi: NOTIFICATION_KIT üzerinden tam kontrol.
+
+✅ Full Testing: Unit, API ve Performans testleri.
+
+
+
+🏛 Mimari Genel Bakış
+Sistem, sorumlulukların net ayrıştırıldığı Layered Architecture (Katmanlı Mimari) prensibiyle tasarlanmıştır.Katmanların SorumluluklarıKatmanSorumluluk AlanıAPIRequest validation, permission kontrolü, throttling.Serviceİş kuralları, kanal seçimi, retry logic yönetimi.BackendKanal spesifik (Email, SMS vb.) düşük seviyeli implementasyon.TaskAsenkron (Async) ve toplu (Batch) işlem yönetimi (Celery).ModelsVeri şeması; Notification, Template ve Kullanıcı tercihleri.SettingsMerkezi ve projeye özel override edilebilir konfigürasyon.
+
+
+
+⚙️ Ayar Yönetimi
+Paket içi ayarlar notification_kit/settings.py dosyasında tanımlıdır. Proje bazlı özelleştirmeler için ana settings.py dosyanızda NOTIFICATION_KIT sözlüğünü kullanabilirsiniz.
+
+Python
+# project/settings.py
+
+NOTIFICATION_KIT = {
+    "ASYNC": True,
+    "MAX_RETRIES": 5,
+    "EMAIL": {
+        "FROM_EMAIL": "noreply@example.com",
+        "RATE_LIMIT": 200,
+    },
+}
+Not: Hassas veriler (API Key, Şifre vb.) her zaman çevre değişkenleri (environment variables) üzerinden yönetilmelidir.
+
+
+
+🛠 Teknik Implementasyon
+1. Backend Yapısı
+Her kanal (SMS, Email, Push) için bir backend sınıfı bulunur. Yeni bir sağlayıcı eklemek oldukça basittir:
+
+Python
+class BaseBackend:
+    def send(self, notification):
+        raise NotImplementedError("Bu metod implemente edilmelidir.")
+2. Service Katmanı
+İş mantığının kalbidir. API'den gelen isteği alır, hangi kanalın kullanılacağına karar verir ve gerekirse işi Celery'ye devreder.
+
+Kanal Seçimi: Template üzerinden dinamik kanal yönetimi.
+
+Soyutlama: Backend implementasyonundan bağımsız çalışma.
+
+3. API Katmanı
+Yalnızca bildirim oluşturma ve tetikleme sorumluluğunu taşır.
+
+Validation: Serializer'lar ile veri doğruluğu garanti edilir.
+
+Security: Permission sınıfları ile yetkisiz erişim engellenir.
+
+
+
+🔒 Güvenlik Yaklaşımı
+Veri Gizliliği: Kişisel veriler (PII) kesinlikle loglanmaz.
+
+Hız Sınırı: API düzeyinde Throttling ile brute-force ve aşırı yüklenme engellenir.
+
+Denetim: Tüm gönderim denemeleri ve sonuçları NotificationLog üzerinden izlenebilir.
+
+
+
+🧪 Test Stratejisi
+Sistem, Pytest altyapısı kullanılarak aşağıdaki seviyelerde test edilmektedir:
+
+Model: Veri bütünlüğü ve ilişki testleri.
+
+Service: İş mantığı ve kanal yönlendirme testleri.
+
+Backend: Provider entegrasyon (mock) testleri.
+
+API: Endpoint erişim ve veri formatı testleri.
+
+
+
+🤝 Katkıda Bulunma
+Projeyi fork edin.
+
+Yeni bir feature branch oluşturun (git checkout -b feature/yeniOzellik).
+
+Değişikliklerinizi commit edin (git commit -m 'Ekle: Yeni SMS Backend').
+
+Branch'inizi push edin (git push origin feature/yeniOzellik).
+
+Bir Pull Request açın.

notification_kit-1.0.0/README.md

@@ -0,0 +1,105 @@
+🚀 Django Notification Kit
+Django Notification Kit, Django projeleri için tasarlanmış; çok kanallı (Email / SMS / Push) bildirim gönderimini yöneten, modüler ve genişletilebilir bir altyapıdır. Sistemin temel amacı; bildirim gönderim süreçlerini API – Service – Backend – Task katmanlarına ayırarak yüksek test edilebilirlik ve sürdürülebilirlik sağlamaktır.
+
+
+
+🎯 Kapsam (v1.0.0 – MVP)
+Bu versiyon, profesyonel bir bildirim sistemi için gerekli olan şu temel bileşenleri sunar:
+
+✅ Abstract Model Yapısı: Genişletilmeye hazır taban modeller.
+
+✅ Concrete Modeller: Notification, Template, Preference ve Log yapıları.
+
+✅ SMTP Email Backend: Standart e-posta gönderim desteği.
+
+✅ Base Notification Service: İş mantığını yöneten merkezi servis.
+
+✅ Celery Task Factory: Ölçeklenebilir, asenkron gönderim desteği.
+
+✅ DRF API: Standartlara uygun API uçları ve Serializer'lar.
+
+✅ Merkezi Ayar Yönetimi: NOTIFICATION_KIT üzerinden tam kontrol.
+
+✅ Full Testing: Unit, API ve Performans testleri.
+
+
+
+🏛 Mimari Genel Bakış
+Sistem, sorumlulukların net ayrıştırıldığı Layered Architecture (Katmanlı Mimari) prensibiyle tasarlanmıştır.Katmanların SorumluluklarıKatmanSorumluluk AlanıAPIRequest validation, permission kontrolü, throttling.Serviceİş kuralları, kanal seçimi, retry logic yönetimi.BackendKanal spesifik (Email, SMS vb.) düşük seviyeli implementasyon.TaskAsenkron (Async) ve toplu (Batch) işlem yönetimi (Celery).ModelsVeri şeması; Notification, Template ve Kullanıcı tercihleri.SettingsMerkezi ve projeye özel override edilebilir konfigürasyon.
+
+
+
+⚙️ Ayar Yönetimi
+Paket içi ayarlar notification_kit/settings.py dosyasında tanımlıdır. Proje bazlı özelleştirmeler için ana settings.py dosyanızda NOTIFICATION_KIT sözlüğünü kullanabilirsiniz.
+
+Python
+# project/settings.py
+
+NOTIFICATION_KIT = {
+    "ASYNC": True,
+    "MAX_RETRIES": 5,
+    "EMAIL": {
+        "FROM_EMAIL": "noreply@example.com",
+        "RATE_LIMIT": 200,
+    },
+}
+Not: Hassas veriler (API Key, Şifre vb.) her zaman çevre değişkenleri (environment variables) üzerinden yönetilmelidir.
+
+
+
+🛠 Teknik Implementasyon
+1. Backend Yapısı
+Her kanal (SMS, Email, Push) için bir backend sınıfı bulunur. Yeni bir sağlayıcı eklemek oldukça basittir:
+
+Python
+class BaseBackend:
+    def send(self, notification):
+        raise NotImplementedError("Bu metod implemente edilmelidir.")
+2. Service Katmanı
+İş mantığının kalbidir. API'den gelen isteği alır, hangi kanalın kullanılacağına karar verir ve gerekirse işi Celery'ye devreder.
+
+Kanal Seçimi: Template üzerinden dinamik kanal yönetimi.
+
+Soyutlama: Backend implementasyonundan bağımsız çalışma.
+
+3. API Katmanı
+Yalnızca bildirim oluşturma ve tetikleme sorumluluğunu taşır.
+
+Validation: Serializer'lar ile veri doğruluğu garanti edilir.
+
+Security: Permission sınıfları ile yetkisiz erişim engellenir.
+
+
+
+🔒 Güvenlik Yaklaşımı
+Veri Gizliliği: Kişisel veriler (PII) kesinlikle loglanmaz.
+
+Hız Sınırı: API düzeyinde Throttling ile brute-force ve aşırı yüklenme engellenir.
+
+Denetim: Tüm gönderim denemeleri ve sonuçları NotificationLog üzerinden izlenebilir.
+
+
+
+🧪 Test Stratejisi
+Sistem, Pytest altyapısı kullanılarak aşağıdaki seviyelerde test edilmektedir:
+
+Model: Veri bütünlüğü ve ilişki testleri.
+
+Service: İş mantığı ve kanal yönlendirme testleri.
+
+Backend: Provider entegrasyon (mock) testleri.
+
+API: Endpoint erişim ve veri formatı testleri.
+
+
+
+🤝 Katkıda Bulunma
+Projeyi fork edin.
+
+Yeni bir feature branch oluşturun (git checkout -b feature/yeniOzellik).
+
+Değişikliklerinizi commit edin (git commit -m 'Ekle: Yeni SMS Backend').
+
+Branch'inizi push edin (git push origin feature/yeniOzellik).
+
+Bir Pull Request açın.

notification_kit-1.0.0/notification_kit/__init__.py

@@ -0,0 +1,5 @@
+"""
+Reusable Django Notification Kit
+"""
+
+__version__ = "1.0.0"

notification_kit-1.0.0/notification_kit/admin.py

@@ -0,0 +1,137 @@
+from django.contrib import admin
+
+from notification_kit.models.concrete import (
+    Notification,
+    NotificationTemplate,
+    NotificationPreference,
+    NotificationLog,
+)
+
+
+@admin.register(Notification)
+class NotificationAdmin(admin.ModelAdmin):
+    """
+    Ana Notification modeli için admin ayarları
+    """
+
+    list_display = (
+        "id",
+        "user",
+        "channel",
+        "status",
+        "priority",
+        "created_at",
+    )
+
+    list_filter = (
+        "channel",
+        "status",
+        "priority",
+    )
+
+    search_fields = (
+        "title",
+        "body",
+        "user__username",
+        "user__email",
+    )
+
+    readonly_fields = (
+        "sent_at",
+        "read_at",
+        "created_at",
+        "updated_at",
+    )
+
+    ordering = ("-created_at",)
+
+
+@admin.register(NotificationTemplate)
+class NotificationTemplateAdmin(admin.ModelAdmin):
+    """
+    Bildirim şablonları için admin ayarları
+    """
+
+    list_display = (
+        "code",
+        "name",
+        "channel",
+        "is_active",
+    )
+
+    list_filter = (
+        "channel",
+        "is_active",
+    )
+
+    search_fields = (
+        "code",
+        "name",
+        "description",
+    )
+
+    ordering = ("code",)
+
+
+@admin.register(NotificationPreference)
+class NotificationPreferenceAdmin(admin.ModelAdmin):
+    """
+    Kullanıcı bildirim tercihleri admin ayarları
+    """
+
+    list_display = (
+        "id",
+        "user",
+        "channel",
+        "is_enabled",
+        "frequency",
+    )
+
+    list_filter = (
+        "channel",
+        "is_enabled",
+        "frequency",
+    )
+
+    search_fields = (
+        "user__username",
+        "user__email",
+    )
+
+
+@admin.register(NotificationLog)
+class NotificationLogAdmin(admin.ModelAdmin):
+    """
+    Bildirim logları admin ayarları
+    """
+
+    list_display = (
+        "notification_id",
+        "action",
+        "old_status",
+        "new_status",
+        "created_at",
+    )
+
+    list_filter = (
+        "action",
+        "created_at",
+    )
+
+    search_fields = (
+        "notification_id",
+        "action",
+    )
+
+    readonly_fields = (
+        "notification_id",
+        "action",
+        "old_status",
+        "new_status",
+        "details",
+        "ip_address",
+        "user_agent",
+        "created_at",
+    )
+
+    ordering = ("-created_at",)

notification_kit-1.0.0/notification_kit/api/permissions.py

@@ -0,0 +1,16 @@
+from rest_framework.permissions import BasePermission, SAFE_METHODS
+
+
+class IsAdminOrReadOnly(BasePermission):
+    """
+    Okuma işlemleri herkese açık olabilir.
+    Yazma / silme işlemleri sadece admin (staff) kullanıcıya izinlidir.
+    """
+
+    def has_permission(self, request, view):
+        # GET, HEAD, OPTIONS serbest
+        if request.method in SAFE_METHODS:
+            return True
+
+        # Yazma işlemleri için admin şartı
+        return bool(request.user and request.user.is_staff)

notification_kit-1.0.0/notification_kit/api/serializers.py

@@ -0,0 +1,12 @@
+from rest_framework import serializers
+from ..models.concrete import Notification, NotificationPreference
+
+class NotificationSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Notification
+        fields = "__all__"
+
+class NotificationPreferenceSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = NotificationPreference
+        fields = "__all__"

notification_kit-1.0.0/notification_kit/api/urls.py

@@ -0,0 +1,16 @@
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from .views import NotificationViewSet, NotificationPreferenceViewSet, admin_send_notification
+
+router = DefaultRouter()
+router.register(r"notifications", NotificationViewSet, basename="notification")
+router.register(r"preferences", NotificationPreferenceViewSet, basename="preference")
+
+urlpatterns = [
+    path("api/", include(router.urls)),
+    path(
+        "admin/notifications/send/",
+        admin_send_notification,
+        name="admin-notifications-send",
+    ),
+]

notification_kit-1.0.0/notification_kit/api/views.py

@@ -0,0 +1,85 @@
+from rest_framework import viewsets, status
+from rest_framework.decorators import action
+from rest_framework.response import Response
+from .serializers import NotificationSerializer, NotificationPreferenceSerializer
+from ..models.concrete import Notification, NotificationPreference
+from notification_kit.api.permissions import IsAdminOrReadOnly
+from django.contrib.auth import get_user_model
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import IsAuthenticated
+
+from ..models import Notification  # concrete Notification
+
+class NotificationViewSet(viewsets.ModelViewSet):
+    queryset = Notification.objects.all()
+    serializer_class = NotificationSerializer
+    permission_classes = [IsAdminOrReadOnly]
+
+    @action(detail=True, methods=["post"])
+    def read(self, request, pk=None):
+        notification = self.get_object()
+        notification.mark_as_read()
+        return Response({"status": "ok"})
+
+    @action(detail=False, methods=["post"])
+    def read_all(self, request):
+        notifications = Notification.objects.all()  # filtreleme eklenebilir
+        for n in notifications:
+            n.mark_as_read()
+        return Response({"status": "ok"})
+
+    @action(detail=False, methods=["get"])
+    def unread_count(self, request):
+        count = Notification.objects.filter(read_at__isnull=True).count()
+        return Response({"unread_count": count})
+
+class NotificationPreferenceViewSet(viewsets.ModelViewSet):
+    queryset = NotificationPreference.objects.all()
+    serializer_class = NotificationPreferenceSerializer
+
+User = get_user_model()
+
+
+@api_view(["POST"])
+@permission_classes([IsAuthenticated])
+def admin_send_notification(request):
+    """
+    Admin/System endpoint:
+    recipient_id + title + body alır, Notification kaydı üretir.
+    Testin aradığı url-name: admin-notifications-send
+    """
+    recipient_id = request.data.get("recipient_id")
+    title = request.data.get("title")
+    body = request.data.get("body")
+
+    if not recipient_id or not title or not body:
+        return Response(
+            {"detail": "recipient_id, title ve body zorunlu."},
+            status=status.HTTP_400_BAD_REQUEST,
+        )
+
+    try:
+        user = User.objects.get(id=recipient_id)
+    except User.DoesNotExist:
+        return Response(
+            {"detail": "recipient bulunamadı."},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+
+    channel = request.data.get("channel", "email")
+    priority = request.data.get("priority", getattr(Notification, "PRIORITY_NORMAL", "normal"))
+
+    n = Notification.objects.create(
+        user=user,  # <- sizin modelde NOT NULL olan alan bu
+        channel=channel,
+        status=getattr(Notification, "STATUS_PENDING", "pending"),
+        title=title,
+        body=body,
+        priority=priority,
+        metadata=request.data.get("metadata", {}),
+    )
+
+    return Response(
+        {"id": n.id, "status": n.status},
+        status=status.HTTP_201_CREATED,
+    )

notification_kit-1.0.0/notification_kit/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class NotificationKitConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "notification_kit"
+    verbose_name = "Notification Kit"

notification_kit-1.0.0/notification_kit/backends/base.py

@@ -0,0 +1,136 @@
+# notification_kit/backends/base.py
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC
+from typing import Any
+
+from notification_kit.settings import get_settings
+from notification_kit.utils.validators import mask_pii
+
+logger = logging.getLogger(__name__)
+
+
+class BaseNotificationBackend(ABC):
+    """
+    Tüm bildirim backend'lerinin uyması gereken temel arayüz.
+    Email, SMS ve Push backend'leri bu sınıftan türetilmelidir.
+    """
+
+    name: str = ""
+    channel: str = ""
+
+    def __init__(self) -> None:
+        settings = get_settings()
+
+        self.max_retries: int = settings.get("MAX_RETRIES", 3)
+        self.retry_delay: int = settings.get("RETRY_DELAY", 300)
+
+        channel_settings = settings.get(self.channel.upper(), {})
+        self.batch_size: int = channel_settings.get("BATCH_SIZE", 1)
+        self.rate_limit: int = channel_settings.get("RATE_LIMIT", 60)
+
+    # -------------------------------------------------
+    # Interface (Varsayılan: override edilmesi beklenir)
+    # Not: abstract bırakmıyoruz ki testlerde DummyBackend
+    # rahat instantiate olabilsin.
+    # -------------------------------------------------
+    def send(self, notification: Any) -> bool:
+        """
+        Bildirimi gönderir.
+        Başarılıysa True, başarısızsa False döner.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__}.send() implement edilmedi")
+
+    def validate_recipient(self, recipient: Any) -> bool:
+        """
+        Alıcı bilgisini doğrular.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.validate_recipient() implement edilmedi"
+        )
+
+    def get_delivery_status(self, notification: Any) -> str:
+        """
+        Bildirimin teslim durumunu sorgular.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.get_delivery_status() implement edilmedi"
+        )
+
+    # --------------------
+    # Ortak yardımcı metodlar
+    # --------------------
+    def format_message(self, template: str, context: dict) -> str:
+        """
+        Template ve context kullanarak mesaj içeriğini oluşturur.
+        (Bu format, str.format bazlıdır. Django Template değil.)
+        """
+        try:
+            return template.format(**context)
+        except KeyError as exc:
+            raise ValueError(f"Eksik template değişkeni: {exc}") from exc
+
+    def sanitize_content(self, content: str) -> str:
+        """
+        İçeriği güvenli hale getirir.
+        Zararlı karakterler ve gereksiz boşluklar temizlenir.
+        """
+        return (content or "").strip()
+
+    # --------------------
+    # Log + Retry helpers
+    # --------------------
+    def log_send_attempt(self, notification: Any, success: bool, error: Exception | None = None) -> None:
+        """
+        Bildirim gönderim denemesini loglar.
+        PII veriler maskelenerek yazılır.
+        """
+        recipient = ""
+        if hasattr(notification, "get_recipient_identifier"):
+            try:
+                recipient = str(notification.get_recipient_identifier())
+            except Exception:
+                recipient = ""
+
+        safe_recipient = mask_pii(recipient) if recipient else ""
+
+        payload = {
+            "backend": self.name or self.__class__.__name__,
+            "channel": self.channel,
+            "recipient": safe_recipient,
+            "success": success,
+            "error": str(error) if error else None,
+        }
+
+        # stdout yerine logger kullanalım (testlerde de temiz)
+        logger.info("[NOTIFICATION LOG] %s", payload)
+
+    def handle_error(self, notification: Any, error: Exception) -> None:
+        """
+        Hata durumunda loglama + notification state günceller.
+        """
+        self.log_send_attempt(notification, success=False, error=error)
+
+        if hasattr(notification, "mark_as_failed"):
+            try:
+                notification.mark_as_failed(str(error))
+            except Exception:
+                # notification mark_as_failed patlarsa testleri kırmayalım
+                logger.exception("mark_as_failed çağrısı hata verdi")
+
+    def should_retry(self, notification: Any, error: Exception) -> bool:
+        """
+        Bildirim tekrar denenmeli mi?
+        """
+        retry_count = getattr(notification, "retry_count", None)
+        if retry_count is None:
+            return False
+
+        if retry_count >= self.max_retries:
+            return False
+
+        # basit backoff (settings.RETRY_DELAY)
+        time.sleep(self.retry_delay)
+        return True

notification_kit-1.0.0/notification_kit/backends/custom.py

@@ -0,0 +1,21 @@
+from .email import BaseSMTPBackend
+from .sms import BaseSMSBackend
+from .push import BasePushBackend
+
+class EmailBackend(BaseSMTPBackend):
+    def build_email_message(self, notification):
+        message = super().build_email_message(notification)
+        # Proje özel footer ekle
+        message.body += "\n\n-- Proje Footer --"
+        return message
+
+class SMSBackend(BaseSMSBackend):
+    def send_sms(self, phone_number, message):
+        # Örnek: Twilio API entegrasyonu
+        return super().send_sms(phone_number, message)
+
+class PushBackend(BasePushBackend):
+    def build_payload(self, notification):
+        payload = super().build_payload(notification)
+        payload["custom"] = "Proje özel data"
+        return payload