django-plugin-system 1.0.0__py3-none-any.whl

django_plugin_system-1.0.0.dist-info/METADATA

@@ -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)

django_plugin_system-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+django_plugin_system-1.0.0.dist-info/licenses/LICENSE,sha256=8b-RN6LQqwfo9RRVLtvavkY3dmygWPluGUZ8VlsVK_E,1073
+src/django_plugin_system/__init__.py,sha256=LFz4Y0iRCg50-iLDfdofQrmc_vdjurmjUqa1Yqki9lk,221
+src/django_plugin_system/admin.py,sha256=W8nqESmoAUF6snJrww8zIah0ugs_a_6UX6m__d36IPg,2537
+src/django_plugin_system/apps.py,sha256=AiVsyMEYNbNHjMUkYI4YfnkQQdMybmYbgKCu7Rv4y1E,295
+src/django_plugin_system/helpers.py,sha256=8BGb3mkJifQPX4rAS3cQLnAHXhdJQau5D1AaPqM8X7U,774
+src/django_plugin_system/models.py,sha256=_hU62NRAZTuUalmnuOO8kYfgffq0wT0Uf6pgxAgvvjE,4687
+src/django_plugin_system/register.py,sha256=HCzuUmkF2LxVu5-QC01VQbvk9SsiDVSWTnNEh-1bfp4,1957
+src/django_plugin_system/signals.py,sha256=fHhMDyrRYzk31BAaYukX2Q0vsRZJa0IBCp3BCG3frn0,458
+src/django_plugin_system/storage.py,sha256=_sGBA6dVklJiZkOt8CHjrOT6QzC9Sa8Eaek-YQfhcZg,730
+src/django_plugin_system/managment/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/django_plugin_system/managment/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/django_plugin_system/managment/commands/pluginsync.py,sha256=sDs-aXGIAc6rJP8JfB9Vw1VeOPL1_xiIkcR08Uqvpd4,1383
+src/django_plugin_system/services/__init__.py,sha256=E69UsyvwHNwEip-va5qqkzgb0Av-hhzSO9Lrrj8eNUk,47
+src/django_plugin_system/services/sync.py,sha256=bgfY_Qzq7JgMUKC9UofoNMHeayCLzTd1GuhhqxGgQow,2955
+django_plugin_system-1.0.0.dist-info/METADATA,sha256=USWx5bVf0pbjSVwocBG9FZdREJJzSm_xckmno4c4F90,12341
+django_plugin_system-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+django_plugin_system-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+django_plugin_system-1.0.0.dist-info/RECORD,,

django_plugin_system-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_plugin_system-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/django_plugin_system/__init__.py

@@ -0,0 +1,4 @@
+from .models import PluginStatus
+from .register import register_plugin_item, register_plugin_type
+from .storage import PluginTypeRegistry, PluginItemRegistry
+from .helpers import get_plugin_instance, get_plugin_class

src/django_plugin_system/admin.py

@@ -0,0 +1,64 @@
+from django.contrib import admin
+from django.db.models import F
+from .models import PluginType, PluginItem, PluginStatus
+
+
+@admin.register(PluginType)
+class PluginTypeAdmin(admin.ModelAdmin):
+    list_display = ("name", "manager", "description", "active_count", "reserved_count", "disabled_count")
+    list_filter = ("manager",)
+    search_fields = ("name", "manager", "description")
+    ordering = ("name", "manager")
+
+    def _count_with_status(self, obj, status):
+        return PluginItem.objects.filter(plugin_type=obj, status=status).count()
+
+    def active_count(self, obj): return self._count_with_status(obj, PluginStatus.ACTIVE)
+
+    def reserved_count(self, obj): return self._count_with_status(obj, PluginStatus.RESERVED)
+
+    def disabled_count(self, obj): return self._count_with_status(obj, PluginStatus.DISABLED)
+
+    active_count.short_description = "Active"
+    reserved_count.short_description = "Reserved"
+    disabled_count.short_description = "Disabled"
+
+
+@admin.action(description="Mark selected as ACTIVE")
+def mark_active(modeladmin, request, queryset):
+    queryset.update(status=PluginStatus.ACTIVE)
+
+
+@admin.action(description="Mark selected as RESERVED")
+def mark_reserved(modeladmin, request, queryset):
+    queryset.update(status=PluginStatus.RESERVED)
+
+
+@admin.action(description="Mark selected as DISABLED")
+def mark_disabled(modeladmin, request, queryset):
+    queryset.update(status=PluginStatus.DISABLED)
+
+
+@admin.action(description="Increase priority (lower number)")
+def increase_priority(modeladmin, request, queryset):
+    # Lower number => higher priority
+    queryset.update(priority=F('priority') - 1)
+
+
+@admin.action(description="Decrease priority (higher number)")
+def decrease_priority(modeladmin, request, queryset):
+    queryset.update(priority=F('priority') + 1)
+
+
+@admin.register(PluginItem)
+class PluginItemAdmin(admin.ModelAdmin):
+    list_display = ("name", "plugin_type", "module", "status", "priority", "loaded_ok")
+    list_filter = ("status", "module", "plugin_type__name", "plugin_type__manager")
+    search_fields = ("name", "module", "description", "plugin_type__name")
+    ordering = ("plugin_type__name", "priority", "name")
+    list_editable = ("status", "priority")
+    actions = [mark_active, mark_reserved, mark_disabled, increase_priority, decrease_priority]
+
+    @admin.display(boolean=True, description="Class loads")
+    def loaded_ok(self, obj: PluginItem):
+        return obj.load_class() is not None

src/django_plugin_system/apps.py

@@ -0,0 +1,10 @@
+from django.apps import AppConfig
+
+
+class PluginSystemConfig(AppConfig):
+    name = 'django_plugin_system'
+    verbose_name = 'Django Plugin System'
+
+    def ready(self):
+        from .signals import sync_registered_plugins_to_db
+        from .models import _clear_single_plugin_cache

src/django_plugin_system/helpers.py

@@ -0,0 +1,28 @@
+from typing import Type, TypeVar, Optional
+
+from .models import PluginType
+
+T = TypeVar("T")
+
+
+def get_plugin_instance(type_name: str, manager: str) -> Optional[object]:
+    try:
+        pt = PluginType.objects.get(name=type_name, manager=manager)
+    except PluginType.DoesNotExist:
+        return None
+    item = pt.get_single_plugin()
+    if not item:
+        return None
+    cls = item.load_class()
+    return cls() if cls else None
+
+
+def get_plugin_class(type_name: str, manager: str) -> Optional[Type[T]]:
+    try:
+        pt = PluginType.objects.get(name=type_name, manager=manager)
+    except PluginType.DoesNotExist:
+        return None
+    item = pt.get_single_plugin()
+    if not item:
+        return None
+    return item.load_class()

src/django_plugin_system/managment/commands/pluginsync.py

@@ -0,0 +1,32 @@
+from django.core.management.base import BaseCommand, CommandParser
+
+from ...services import sync_registered_plugins_to_db
+
+
+class Command(BaseCommand):
+    help = "Synchronize registered plugin types/items into the database."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument(
+            "--mode",
+            choices=["create", "update"],
+            default="create",
+            help='How to persist registry data. "create" = get_or_create (preserve admin edits). "update" = update_or_create.',
+        )
+        parser.add_argument(
+            "--no-prune",
+            action="store_true",
+            help="Do not prune plugin types/items whose manager/module is no longer installed.",
+        )
+
+    def handle(self, *args, **options):
+        mode = options["mode"]
+        prune = not options["no_prune"]
+
+        result = sync_registered_plugins_to_db(mode=mode, prune=prune)
+
+        self.stdout.write(self.style.SUCCESS("Plugin registry sync completed"))
+        self.stdout.write(f"- Types created: {result['types_created']}, found: {result['types_found']}")
+        self.stdout.write(f"- Items created: {result['items_created']}, found: {result['items_found']}")
+        if prune:
+            self.stdout.write(f"- Pruned types: {result['pruned_types']}, pruned items: {result['pruned_items']}")

src/django_plugin_system/models.py

@@ -0,0 +1,126 @@
+import uuid
+from typing import ClassVar, List, Type, Dict
+
+from django.core.cache import cache
+from django.db import models
+from django.db.models import UniqueConstraint, Index
+from django.db.models.signals import post_save, post_delete
+from django.dispatch import receiver
+
+from .register import load_plugin_item, load_plugin_type
+
+
+class PluginStatus(models.TextChoices):
+    ACTIVE = 'active'
+    RESERVED = 'reserve'  # used if no active plugin is available
+    DISABLED = 'disable'
+
+
+class PluginType(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=100, db_index=True)
+    manager = models.CharField(max_length=100)  # app providing the plugin type
+    description = models.TextField()
+
+    class Meta:
+        constraints = [
+            UniqueConstraint(fields=["name", "manager"], name="uniq_plugin_type_name_manager"),
+        ]
+        indexes = [
+            Index(fields=["name"]),
+            Index(fields=["manager"]),
+        ]
+
+    def __str__(self):
+        return f"Plugin type {self.name}"
+
+    def get_all_plugins(self) -> Dict[str, List['PluginItem']]:
+        return PluginItem.get_all_plugins(self)
+
+    def get_active_plugins(self) -> 'List[PluginItem]':
+        return PluginItem.get_available_plugins(self)
+
+    def get_single_plugin(self) -> 'PluginItem | None':
+        try:
+            plugin_type = load_plugin_type(self.name, self.manager)
+            get_plugin = plugin_type.get('get_plugin')
+            if get_plugin:
+                return get_plugin(self)
+        except KeyError:
+            return None
+        return PluginItem.default_get_single_plugin(self)
+
+
+class PluginItem(models.Model):
+    # CacheKey
+    CACHE_KEY_PLUGIN_TYPE_SINGLE: ClassVar[str] = 'plugin-single-item-type-{}'
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    plugin_type = models.ForeignKey(PluginType, on_delete=models.CASCADE)
+    module = models.CharField(max_length=100)  # app providing the plugin item
+    name = models.CharField(max_length=100, db_index=True)
+    status = models.CharField(
+        max_length=10,
+        choices=PluginStatus.choices,
+        default=PluginStatus.ACTIVE,
+        db_index=True,
+    )
+    priority = models.SmallIntegerField(default=0)  # lower is better
+    description = models.TextField(null=True, blank=True)
+
+    class Meta:
+        constraints = [
+            UniqueConstraint(
+                fields=["name", "module", "plugin_type"],
+                name="uniq_plugin_item_name_module_type",
+            )
+        ]
+        indexes = [
+            Index(fields=["plugin_type", "status", "priority"]),
+            Index(fields=["module"]),
+        ]
+
+    def __str__(self):
+        return f"Plugin {self.name} for {self.plugin_type} provided by {self.module}.({self.status})"
+
+    def load_class(self) -> Type | None:
+        try:
+            plugin_item = load_plugin_item(self.name, self.module, self.plugin_type.name)
+            return plugin_item['plugin_class']
+        except Exception:
+            return None
+
+    @staticmethod
+    def default_get_single_plugin(plugin_type: PluginType) -> 'PluginItem | None':
+        key = PluginItem.CACHE_KEY_PLUGIN_TYPE_SINGLE.format(plugin_type.id)
+        plugin = cache.get(key)
+        if plugin:
+            return plugin
+        qs = PluginItem.objects.filter(plugin_type=plugin_type, status=PluginStatus.ACTIVE).order_by('priority')
+        first = qs.first()
+        if first:
+            cache.set(key, first)
+            return first
+        qs = PluginItem.objects.filter(plugin_type=plugin_type, status=PluginStatus.RESERVED).order_by('priority')
+        return qs.first()
+
+    @staticmethod
+    def get_all_plugins(plugin_type: PluginType) -> Dict[str, List['PluginItem']]:
+        result = {}
+        for plugin in PluginItem.objects.filter(plugin_type=plugin_type).order_by('priority'):
+            result.setdefault(plugin.status, []).append(plugin)
+        return result
+
+    @staticmethod
+    def get_available_plugins(plugin_type: PluginType) -> 'List[PluginItem]':
+        return list(
+            PluginItem.objects.filter(plugin_type=plugin_type, status=PluginStatus.ACTIVE).order_by('priority')
+        )
+
+
+# Cache invalidation when items change
+@receiver(post_save, sender=PluginItem)
+@receiver(post_delete, sender=PluginItem)
+def _clear_single_plugin_cache(sender, instance: PluginItem, **kwargs):
+    key = PluginItem.CACHE_KEY_PLUGIN_TYPE_SINGLE.format(instance.plugin_type.id)
+    cache.delete(key)

src/django_plugin_system/register.py

@@ -0,0 +1,47 @@
+import logging
+from abc import ABC
+
+from .storage import (
+    _registry_plugin_items,
+    _registry_plugin_types,
+    PluginTypeRegistry,
+    PluginItemRegistry,
+    PLUGIN_TYPE_PLACEHOLDER,
+    PLUGIN_ITEM_PLACEHOLDER,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def register_plugin_type(plugin_type: PluginTypeRegistry):
+    if not issubclass(plugin_type['interface'], ABC):
+        raise TypeError("Interface must be a subclass of ABC")
+    if not getattr(plugin_type['interface'], '__abstractmethods__', None):
+        raise TypeError("Interface must have at least one abstractmethod")
+
+    name = PLUGIN_TYPE_PLACEHOLDER.format(plugin_type['name'], plugin_type['manager'])
+    _registry_plugin_types[name] = plugin_type
+
+
+def load_plugin_type(type_name: str, manager: str) -> PluginTypeRegistry:
+    name = PLUGIN_TYPE_PLACEHOLDER.format(type_name, manager)
+    if name in _registry_plugin_types:
+        return _registry_plugin_types[name]
+    raise KeyError(f"Plugin type '{name}' not found")
+
+
+def register_plugin_item(plugin_item: PluginItemRegistry):
+    plugin_type: PluginTypeRegistry = load_plugin_type(plugin_item['type_name'], plugin_item['manager_name'])
+    if not issubclass(plugin_item['plugin_class'], plugin_type['interface']):
+        raise TypeError(
+            f"Plugin '{plugin_item['name']}' does not implement interface {plugin_type['interface'].__name__}")
+    name = PLUGIN_ITEM_PLACEHOLDER.format(plugin_item['name'], plugin_item['module'], plugin_item['type_name'])
+    _registry_plugin_items[name] = plugin_item
+    logger.debug("Registered plugin item %s", name)
+
+
+def load_plugin_item(plugin_name: str, module_name: str, type_name: str) -> PluginItemRegistry:
+    name = PLUGIN_ITEM_PLACEHOLDER.format(plugin_name, module_name, type_name)
+    if name in _registry_plugin_items:
+        return _registry_plugin_items[name]
+    raise KeyError(f"Plugin item '{name}' not found")

src/django_plugin_system/services/__init__.py

@@ -0,0 +1 @@
+from .sync import sync_registered_plugins_to_db

src/django_plugin_system/services/sync.py

@@ -0,0 +1,84 @@
+from typing import Literal
+
+from django.conf import settings
+from django.db import transaction
+from django.db.models import Q
+
+from ..models import PluginType, PluginItem, PluginStatus
+from ..storage import _registry_plugin_types, _registry_plugin_items
+
+Mode = Literal["create", "update"]
+
+
+def _app_list() -> set[str]:
+    return set(settings.INSTALLED_APPS)
+
+
+@transaction.atomic
+def sync_registered_plugins_to_db(
+        *,
+        mode: Mode = "create",
+        prune: bool = True,
+) -> dict:
+    """
+    Sync in-memory registry -> DB.
+
+    Mode="create": uses get_or_create (won't overwrite admin-edited fields)
+    mode="update": uses update_or_create (will refresh description/priority from registry)
+
+    prune: remove DB rows for managers/modules that are no longer installed
+    """
+    result = {"types_created": 0, "types_found": 0, "items_created": 0, "items_found": 0, "pruned_types": 0,
+              "pruned_items": 0}
+
+    app_list = _app_list()
+
+    if prune:
+        # remove rows for uninstalled apps
+        result["pruned_types"] = PluginType.objects.filter(~Q(manager__in=app_list)).delete()[0]
+        result["pruned_items"] = PluginItem.objects.filter(~Q(module__in=app_list)).delete()[0]
+
+    # TYPES
+    for _, pt in _registry_plugin_types.items():
+        defaults = {"description": pt.get("description") or ""}
+        if mode == "update":
+            obj, created = PluginType.objects.update_or_create(
+                name=pt["name"], manager=pt["manager"], defaults=defaults
+            )
+        else:
+            obj, created = PluginType.objects.get_or_create(
+                name=pt["name"], manager=pt["manager"], defaults=defaults
+            )
+        if created:
+            result["types_created"] += 1
+        else:
+            result["types_found"] += 1
+
+    # ITEMS
+    for _, pi in _registry_plugin_items.items():
+        try:
+            pt_obj = PluginType.objects.get(name=pi["type_name"], manager=pi["manager_name"])
+        except PluginType.DoesNotExist:
+            # Type isn't synced (or missing) — skip
+            continue
+
+        defaults = {
+            "description": pi.get("description") or "",
+            # prefer registry priority on first creation; won’t override in "create" mode
+            "priority": pi.get("priority") or 0,
+            # first-time status ACTIVE; admin changes later will stick
+            "status": PluginStatus.ACTIVE,
+        }
+
+        lookup = {"name": pi["name"], "module": pi["module"], "plugin_type": pt_obj}
+        if mode == "update":
+            obj, created = PluginItem.objects.update_or_create(defaults=defaults, **lookup)
+        else:
+            obj, created = PluginItem.objects.get_or_create(defaults=defaults, **lookup)
+
+        if created:
+            result["items_created"] += 1
+        else:
+            result["items_found"] += 1
+
+    return result

src/django_plugin_system/signals.py

@@ -0,0 +1,14 @@
+from django.db.models.signals import post_migrate
+from django.dispatch import receiver
+
+from .services.sync import sync_registered_plugins_to_db
+
+APP_LABEL = "django_plugin_system"
+
+
+@receiver(post_migrate)
+def sync_registered_plugins_signal(sender, **kwargs):
+    if getattr(sender, "name", None) != APP_LABEL:
+        return
+    # create-only; do not overwrite admin-edited fields
+    sync_registered_plugins_to_db(mode="create", prune=True)

src/django_plugin_system/storage.py

@@ -0,0 +1,27 @@
+from abc import ABC
+from typing import TypedDict, Callable, Type, Dict, NotRequired
+
+PLUGIN_TYPE_PLACEHOLDER = 'plugin-type-{}-by-{}'
+PLUGIN_ITEM_PLACEHOLDER = 'plugin-item-{}-by-{}-for-{}'
+
+
+class PluginTypeRegistry(TypedDict):
+    name: str
+    interface: type[ABC]
+    manager: str
+    get_plugin: NotRequired[Callable | None]
+    description: NotRequired[str | None]
+
+
+class PluginItemRegistry(TypedDict):
+    name: str
+    type_name: str
+    manager_name: str
+    plugin_class: Type
+    module: str
+    description: NotRequired[str | None]
+    priority: NotRequired[int | None]
+
+
+_registry_plugin_types: Dict[str, PluginTypeRegistry] = {}
+_registry_plugin_items: Dict[str, PluginItemRegistry] = {}