django-plugin-system 1.0.0__tar.gz

django_plugin_system-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Alireza Tabatabaeian
+
+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_plugin_system-1.0.0/PKG-INFO

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: django-plugin-system
+Version: 1.0.0
+Summary: A lightweight plugin registry for Django with admin management and registry→DB sync.
+Author-email: Alireza Tabatabaeian <alireza.tabatabaeian@gmail.com>
+Project-URL: Homepage, https://github.com/Alireza-Tabatabaeian/django-plugin-system
+Project-URL: Issues, https://github.com/Alireza-Tabatabaeian/django-plugin-system/issues
+Keywords: django,plugins,registry,otp,extensibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.8.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: django-stubs>=5.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# Django Plugin System
+
+A lightweight, batteries-included plugin registry for Django apps.  
+Use it to expose **swappable implementations** (e.g., multiple OTP providers) behind a stable interface, select the active plugin in **Django Admin**, and keep the database in sync with in‑code registrations via a **management command**.
+
+---
+
+## ✨ Features
+
+- **Simple interface-first design** — define an abstract base class (ABC), register implementations.
+- **Registry → DB sync** — `pluginsync` management command (and optional `post_migrate` signal).
+- **Admin UX** — filter/search, bulk enable/disable, and quick priority nudges.
+- **Deterministic selection** — pick a single plugin by `status` and `priority`, with caching.
+- **Safe defaults** — `get_or_create` syncing preserves admin-edited fields.
+- **Uniqueness guarantees** — unique constraints for types and items.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install django-plugin-system
+```
+
+Add the app to `INSTALLED_APPS`:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "django_plugin_system",
+]
+```
+
+> The app creates two models: `PluginType` and `PluginItem`.
+
+---
+
+## 🔌 Core Concepts
+
+### 1) Define an **interface** (ABC)
+
+```python
+# apps/otp/interfaces.py
+from abc import ABC, abstractmethod
+
+class AbstractOTP(ABC):
+    @abstractmethod
+    def send_otp(self, number: str, code: str) -> None: ...
+```
+
+### 2) Register a **plugin type**
+
+```python
+# apps/otp/apps.py (or any module imported at startup)
+from django.apps import AppConfig
+from django_plugin_system.register import register_plugin_type
+
+class OtpConfig(AppConfig):
+    name = "apps.otp"
+    def ready(self):
+        register_plugin_type({
+            "name": "otp",
+            "manager": self.name,  # the app providing the type
+            "interface": AbstractOTP,
+            "description": "One-time password (OTP) delivery channel",
+        })
+```
+
+### 3) Implement and register **plugin items**
+
+```python
+# apps/otp_sms/plugins.py
+from django_plugin_system.register import register_plugin_item
+from .interfaces import AbstractOTP
+
+class SmsIrOTP(AbstractOTP):
+    def send_otp(self, number: str, code: str) -> None:
+        # call provider api...
+        pass
+
+# Register this implementation
+register_plugin_item({
+    "name": "sms_ir",
+    "module": "apps.otp_sms",     # the app providing the item
+    "type_name": "otp",
+    "manager_name": "apps.otp",   # the app providing the type
+    "plugin_class": SmsIrOTP,
+    "priority": 10,
+    "description": "Send OTP using Sms.ir provider",
+})
+```
+
+> You can register multiple items with different priorities. Lower number means **higher** priority.
+
+---
+
+## 🗄️ Database Models
+
+```python
+# django_plugin_system.models
+class PluginType(models.Model):
+    id          = UUID PK
+    name        = CharField
+    manager     = CharField   # the app that defines the interface
+    description = TextField
+
+class PluginItem(models.Model):
+    id          = UUID PK
+    plugin_type = FK -> PluginType
+    module      = CharField   # the app that provides the implementation
+    name        = CharField
+    status      = TextChoices('active', 'reserve', 'disable')
+    priority    = SmallIntegerField  # lower is better
+    description = TextField
+```
+
+### Uniqueness
+
+- `PluginType(name, manager)` is unique.  
+- `PluginItem(name, module, plugin_type)` is unique.
+
+---
+
+## 🧠 Selection Logic
+
+- **Active first:** pick the lowest-priority `active` item.
+- **Fallback:** if no `active`, pick the lowest-priority `reserve` item.
+- **Cache:** the chosen item is cached per `PluginType` and auto‑invalidated on save/delete.
+
+### Helper
+
+```python
+from django_plugin_system.helpers import get_plugin_instance
+
+otp = get_plugin_instance("otp", "apps.otp")
+if otp:
+    otp.send_otp("+31123456789", "123456")
+```
+
+> Or call `PluginType.get_single_plugin()` then `.load_class()` to instantiate manually.
+
+---
+
+## 🛠️ Syncing the Registry
+
+You have **two** ways to keep the DB aligned with the in‑memory registry:
+
+1) **Automatically after migrations** (default)
+   - The `post_migrate` signal syncs in *create-only* mode (preserves admin edits).
+
+2) **Manually via command**
+   ```bash
+   python manage.py pluginsync
+   # or to refresh defaults from registry (overwrites description/priority on conflicts):
+   python manage.py pluginsync --mode update
+   # skip pruning of stale rows:
+   python manage.py pluginsync --no-prune
+   ```
+
+**Modes:**
+
+- `create` → uses `get_or_create` (safe: won’t overwrite `status`/`priority` changed in Admin)
+- `update` → uses `update_or_create` (refresh `description`/`priority` from code)
+
+---
+
+## 🧭 Admin Panel
+
+- **PluginType** list shows counts per status.
+- **PluginItem** list lets you:
+  - quick-edit `status` and `priority`,
+  - bulk mark **ACTIVE/RESERVED/DISABLED**,
+  - **Increase/Decrease priority** in-place,
+  - view a “Class loads” boolean to catch broken registrations.
+
+> Changing status/priority automatically clears the single‑plugin selection cache.
+
+---
+
+## 🔄 Overriding selection
+
+You can override the selection logic per type by providing a `get_plugin` callable in the type registry entry:
+
+```python
+def my_selector(plugin_type_model_obj):
+    # your custom logic (possibly data-driven)
+    return plugin_type_model_obj.get_active_plugins()[0]
+
+register_plugin_type({
+    "name": "otp",
+    "manager": "apps.otp",
+    "interface": AbstractOTP,
+    "description": "OTP delivery",
+    "get_plugin": my_selector,  # <- override
+})
+```
+
+---
+
+## 🧪 Testing tips
+
+- Ensure your registry code paths are imported in test settings (e.g., via `AppConfig.ready`).
+- Use `pluginsync --mode create` in test setup to materialize rows.
+- Toggle item `status` in tests to verify fallback and cache invalidation.
+
+---
+
+## 📐 Design Notes & Guarantees
+
+- Registry data lives in memory at import time; DB represents a **materialized view** used by Admin and runtime selection.
+- Syncing is **idempotent** and safe to run many times.
+- Items are validated to **implement the declared interface**.
+- Errors on registration are not swallowed — mis-registrations fail early and loudly.
+
+---
+
+## 🤔 Why Use Django Plugin System?
+
+When you build extensible Django apps — like payment gateways, OTP senders, or notification systems — you often need pluggable backends that can be swapped or prioritized without touching your core logic.
+
+This library lets you define interfaces, register multiple implementations, and let users (or admins) pick which ones are active — all without breaking code, and with database-level configurability.
+
+---
+
+### 🧩 Example: Notification System
+
+Imagine you have multiple ways to notify users:
+
+- Email
+
+- SMS
+
+- Push notification
+
+Each of these is handled by a different piece of code — maybe even from different apps.
+
+### 🚫 **Without** Django Plugin System
+
+- You hardcode your imports and logic:
+
+```python
+# notifications/core.py
+from notifications.email_sender import send_email
+from notifications.sms_sender import send_sms
+from notifications.push_sender import send_push
+
+def notify_user(user, message):
+    if user.prefers_email:
+        send_email(user.email, message)
+    elif user.prefers_sms:
+        send_sms(user.phone, message)
+    elif user.prefers_push:
+        send_push(user.device_token, message)
+```
+- Every time you add a new provider, you must:
+  - Write new import statements
+  - Modify your logic
+  - Re-deploy your code
+  - Possibly break something that used to work
+
+And there’s no way for an admin to change behavior dynamically — everything is baked into code.
+
+---
+### ✅ **With** Django Plugin System
+
+1. You define one interface:
+
+```python
+from abc import ABC, abstractmethod
+
+class AbstractNotifier(ABC):
+    @abstractmethod
+    def send(self, user, message): ...
+```
+
+2. You register it as a plugin type:
+
+```python
+from django_plugin_system.register import register_plugin_type
+
+register_plugin_type({
+    "name": "notifier",
+    "manager": "apps.notifications",
+    "interface": AbstractNotifier,
+    "description": "Notification channels for users",
+})
+```
+
+3. You implement as many plugin items as you want (completely independent of the rest of the code):
+
+```python
+from django_plugin_system.register import register_plugin_item
+from .interfaces import AbstractNotifier
+
+class EmailNotifier(AbstractNotifier):
+    def send(self, user, message):
+        print(f"Sending email to {user.email}: {message}")
+
+register_plugin_item({
+    "name": "email",
+    "module": "apps.notifications.email",
+    "type_name": "notifier",
+    "manager_name": "apps.notifications",
+    "plugin_class": EmailNotifier,
+    "priority": 5,
+    "description": "Send notification via Email",
+})
+```
+
+4. You can now dynamically select from Admin which notifiers are active, in reserve, or disabled — even reorder them by priority.
+5. Your code doesn’t change at all:
+
+```python
+from django_plugin_system.helpers import get_plugin_instance
+
+notifier = get_plugin_instance("notifier", "apps.notifications")
+notifier.send(user, "Your OTP is 1234")
+```
+
+💡 You can even expose multiple active notifiers and let users subscribe to their favorites — Email + Push for one user, Push only for another — all configurable through database records instead of code edits.
+
+```python
+# models.py
+from typing import List
+
+from django.db import models
+from django.contrib.auth.models import User
+
+from django_plugin_system.models import PluginItem
+
+
+class UserNotifyPref(models.Model):
+    user = models.ForeignKey(User, on_delete=models.CASCADE)
+    favourite_plugins = models.ManyToManyField(PluginItem)
+
+    @staticmethod
+    def get_user_plugins(user: User) -> List[PluginItem]:
+        try:
+            return list(UserNotifyPref.objects.get(user=user).favourite_plugins.all())
+        except UserNotifyPref.DoesNotExist:
+            return []
+```
+
+Now the following code will notify user through all selected plugins:
+```python
+from myapp.models import UserNotifyPref
+
+...
+
+favourite_plugins = UserNotifyPref.get_user_plugins(user)
+for plugin in favourite_plugins:
+    plugin_service = plugin.load_class()
+    plugin_service.send(user, message)
+
+...
+
+```
+just as simple as you see, **with** django-plugin-system, you can let users decide which plugin they prefer to use.
+
+---
+
+## 📄 License
+
+MIT [Alireza Tabatabaeian](https://github.com/Alireza-Tabatabaeian)