django-permission-engine 0.1.0__tar.gz

django_permission_engine-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release
+- Permission registry engine
+- Database models (Permission, Module, UserPermission)
+- Declarative permission definitions with decorators
+- DRF integration with PermissionRequired class
+- Permission catalog API
+- Management commands (upr_sync, upr_validate, upr_list)
+- Comprehensive test suite
+- Documentation
+
+## [0.1.0] - 2024-01-15
+
+### Added
+- Core permission models
+- Registry engine for permission synchronization
+- Module and action decorators
+- Runtime permission resolution
+- DRF PermissionRequired class
+- Permission catalog API endpoints
+- Management commands for sync, validate, and list
+- Test infrastructure and test suite
+- Sphinx documentation setup
+
+[Unreleased]: https://github.com/yourusername/django-permission-engine/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourusername/django-permission-engine/releases/tag/v0.1.0

django_permission_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Your Name
+
+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_permission_engine-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include django_permission_engine *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

django_permission_engine-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: django-permission-engine
+Version: 0.1.0
+Summary: Unified Permission Registry (UPR) for Django & DRF
+Home-page: https://github.com/sarthaksnh5/django_permission_engine
+Author: Sarthak
+Author-email: sarthaksnh5@gmail.com
+License: MIT
+Project-URL: Documentation, https://django-permission-engine.readthedocs.io/
+Project-URL: Source, https://github.com/sarthaksnh5/django_permission_engine
+Project-URL: Tracker, https://github.com/sarthaksnh5/django_permission_engine/issues
+Keywords: django permissions drf rest-framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Requires-Dist: djangorestframework>=3.12
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Django Permission Engine
+
+Unified Permission Registry (UPR) for Django & DRF
+
+## Overview
+
+Django Permission Engine provides a single-source, action-aware, declarative permission system for Django and Django REST Framework. It eliminates permission drift and provides a maintainable foundation for complex permission requirements.
+
+## Features
+
+- 🎯 **Single Source of Truth** - Define permissions once, everything else is derived
+- 🔑 **Permission Keys** - Simple, immutable, string-based permission identifiers
+- 🎬 **Action-Aware** - DRF actions automatically map to permissions
+- 📊 **Frontend-Ready** - Permission catalog API for frontend consumption
+- 🚫 **Drift Prevention** - Startup validation ensures code and database never drift
+- ⚡ **Performance** - O(1) permission checks with optional caching
+
+## Installation
+
+```bash
+pip install django-permission-engine
+```
+
+**Note:** This library uses flexible version requirements (minimum versions only) to avoid conflicts with your existing Django and DRF installations. It will work with any compatible version you already have installed.
+
+## Quick Start
+
+### 1. Add to INSTALLED_APPS
+
+```python
+INSTALLED_APPS = [
+    # ... other apps
+    'rest_framework',
+    'django_permission_engine',
+]
+```
+
+### 2. Configure
+
+```python
+UPR_CONFIG = {
+    'validate_on_startup': True,
+    'strict_mode': True,
+    'auto_sync': False,
+}
+```
+
+### 3. Define Permissions
+
+```python
+# upr_config.py
+from django_permission_engine import module, action
+
+@module('users', label='User Management')
+class UsersModule:
+    crud = ['view', 'create', 'update', 'delete']
+    actions = ['reset_password']
+```
+
+### 4. Sync to Database
+
+```bash
+python manage.py upr_sync
+```
+
+### 5. Assign Permissions to Users
+
+Use the Permission Management API (admin only):
+
+```bash
+# Assign permission to user
+POST /api/permissions/users/1/assign/
+{
+    "permission_key": "users.view"
+}
+
+# Bulk assign to multiple users
+POST /api/permissions/bulk-assign/
+{
+    "permission_keys": ["users.view", "users.create"],
+    "user_ids": [1, 2, 3]
+}
+```
+
+Or programmatically:
+
+```python
+from django_permission_engine.models import Permission, UserPermission
+
+user = User.objects.get(username='john')
+permission = Permission.objects.get(key='users.view')
+UserPermission.objects.get_or_create(user=user, permission=permission)
+```
+
+### 6. Use in ViewSets
+
+```python
+from rest_framework import viewsets
+from django_permission_engine.permissions import PermissionRequired
+
+class UserViewSet(viewsets.ModelViewSet):
+    permission_classes = [PermissionRequired]
+    module = 'users'
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` folder:
+
+- [Architecture](docs/architecture.md)
+- [Core Concepts](docs/core-concepts.md)
+- [Permission Definition](docs/permission-definition.md)
+- [DRF Integration](docs/drf-integration.md)
+- [API Reference](docs/catalog-api.md)
+
+## Requirements
+
+- Python 3.8+
+- Django 3.2+
+- Django REST Framework 3.12+
+
+## License
+
+MIT License

django_permission_engine-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Django Permission Engine
+
+Unified Permission Registry (UPR) for Django & DRF
+
+## Overview
+
+Django Permission Engine provides a single-source, action-aware, declarative permission system for Django and Django REST Framework. It eliminates permission drift and provides a maintainable foundation for complex permission requirements.
+
+## Features
+
+- 🎯 **Single Source of Truth** - Define permissions once, everything else is derived
+- 🔑 **Permission Keys** - Simple, immutable, string-based permission identifiers
+- 🎬 **Action-Aware** - DRF actions automatically map to permissions
+- 📊 **Frontend-Ready** - Permission catalog API for frontend consumption
+- 🚫 **Drift Prevention** - Startup validation ensures code and database never drift
+- ⚡ **Performance** - O(1) permission checks with optional caching
+
+## Installation
+
+```bash
+pip install django-permission-engine
+```
+
+**Note:** This library uses flexible version requirements (minimum versions only) to avoid conflicts with your existing Django and DRF installations. It will work with any compatible version you already have installed.
+
+## Quick Start
+
+### 1. Add to INSTALLED_APPS
+
+```python
+INSTALLED_APPS = [
+    # ... other apps
+    'rest_framework',
+    'django_permission_engine',
+]
+```
+
+### 2. Configure
+
+```python
+UPR_CONFIG = {
+    'validate_on_startup': True,
+    'strict_mode': True,
+    'auto_sync': False,
+}
+```
+
+### 3. Define Permissions
+
+```python
+# upr_config.py
+from django_permission_engine import module, action
+
+@module('users', label='User Management')
+class UsersModule:
+    crud = ['view', 'create', 'update', 'delete']
+    actions = ['reset_password']
+```
+
+### 4. Sync to Database
+
+```bash
+python manage.py upr_sync
+```
+
+### 5. Assign Permissions to Users
+
+Use the Permission Management API (admin only):
+
+```bash
+# Assign permission to user
+POST /api/permissions/users/1/assign/
+{
+    "permission_key": "users.view"
+}
+
+# Bulk assign to multiple users
+POST /api/permissions/bulk-assign/
+{
+    "permission_keys": ["users.view", "users.create"],
+    "user_ids": [1, 2, 3]
+}
+```
+
+Or programmatically:
+
+```python
+from django_permission_engine.models import Permission, UserPermission
+
+user = User.objects.get(username='john')
+permission = Permission.objects.get(key='users.view')
+UserPermission.objects.get_or_create(user=user, permission=permission)
+```
+
+### 6. Use in ViewSets
+
+```python
+from rest_framework import viewsets
+from django_permission_engine.permissions import PermissionRequired
+
+class UserViewSet(viewsets.ModelViewSet):
+    permission_classes = [PermissionRequired]
+    module = 'users'
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` folder:
+
+- [Architecture](docs/architecture.md)
+- [Core Concepts](docs/core-concepts.md)
+- [Permission Definition](docs/permission-definition.md)
+- [DRF Integration](docs/drf-integration.md)
+- [API Reference](docs/catalog-api.md)
+
+## Requirements
+
+- Python 3.8+
+- Django 3.2+
+- Django REST Framework 3.12+
+
+## License
+
+MIT License

django_permission_engine-0.1.0/django_permission_engine/__init__.py

@@ -0,0 +1,32 @@
+"""
+Django Permission Engine - Unified Permission Registry (UPR) for Django & DRF
+"""
+from .registry import (
+    PermissionRegistry,
+    PermissionDefinition,
+    get_registry,
+    registry,
+    module,
+    action,
+)
+from .permissions import (
+    PermissionResolver,
+    PermissionRequired,
+)
+
+__version__ = "0.1.0"
+__author__ = "Your Name"
+__email__ = "your.email@example.com"
+
+default_app_config = "django_permission_engine.apps.PermissionEngineConfig"
+
+__all__ = [
+    "PermissionRegistry",
+    "PermissionDefinition",
+    "get_registry",
+    "registry",
+    "module",
+    "action",
+    "PermissionResolver",
+    "PermissionRequired",
+]

django_permission_engine-0.1.0/django_permission_engine/apps.py

@@ -0,0 +1,37 @@
+"""
+Django app configuration for Permission Engine
+"""
+from django.apps import AppConfig
+
+
+class PermissionEngineConfig(AppConfig):
+    """Django app configuration for Permission Engine"""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_permission_engine"
+    verbose_name = "Permission Engine"
+
+    def ready(self):
+        """Called when Django starts"""
+        from django.conf import settings
+
+        # Get UPR config
+        upr_config = getattr(settings, "UPR_CONFIG", {})
+        validate_on_startup = upr_config.get("validate_on_startup", False)
+        auto_sync = upr_config.get("auto_sync", False)
+
+        # Initialize registry if configured
+        if validate_on_startup or auto_sync:
+            from .registry import get_registry
+            registry = get_registry()
+
+            # Validate
+            if validate_on_startup:
+                errors = registry.validate()
+                if errors and registry.strict_mode:
+                    from django.core.exceptions import ValidationError
+                    raise ValidationError(f"Registry validation failed: {errors}")
+
+            # Auto-sync if configured
+            if auto_sync:
+                registry.sync()

django_permission_engine-0.1.0/django_permission_engine/management/commands/upr_list.py

@@ -0,0 +1,92 @@
+"""
+Management command to list permissions
+"""
+from django.core.management.base import BaseCommand
+import json
+
+from django_permission_engine.models import Permission
+
+
+class Command(BaseCommand):
+    help = 'List all registered permissions'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            '--module',
+            type=str,
+            help='Filter by module',
+        )
+        parser.add_argument(
+            '--type',
+            type=str,
+            choices=['crud', 'action'],
+            help='Filter by type',
+        )
+        parser.add_argument(
+            '--format',
+            type=str,
+            choices=['table', 'json', 'simple'],
+            default='table',
+            help='Output format',
+        )
+
+    def handle(self, *args, **options):
+        """Execute list command"""
+        module_filter = options.get('module')
+        type_filter = options.get('type')
+        format_type = options['format']
+
+        # Get permissions
+        if module_filter:
+            permissions = Permission.objects.filter(module=module_filter)
+        else:
+            permissions = Permission.objects.all()
+
+        if type_filter:
+            if type_filter == 'crud':
+                permissions = permissions.filter(capability__in=['view', 'create', 'update', 'delete'])
+            else:
+                permissions = permissions.exclude(capability__in=['view', 'create', 'update', 'delete'])
+
+        permissions = permissions.order_by('module', 'capability')
+
+        # Display
+        if format_type == 'json':
+            self._display_json(permissions)
+        elif format_type == 'simple':
+            self._display_simple(permissions)
+        else:
+            self._display_table(permissions)
+
+    def _display_table(self, permissions):
+        """Display permissions in table format"""
+        self.stdout.write('\nRegistered Permissions:\n')
+        self.stdout.write('-' * 80)
+        self.stdout.write('{:<40} {:<20} {:<20}'.format('Key', 'Module', 'Capability'))
+        self.stdout.write('-' * 80)
+
+        for perm in permissions:
+            self.stdout.write(
+                '{:<40} {:<20} {:<20}'.format(perm.key, perm.module, perm.capability)
+            )
+
+        self.stdout.write('-' * 80)
+        self.stdout.write(f'\nTotal: {permissions.count()} permissions')
+
+    def _display_simple(self, permissions):
+        """Display permissions in simple format"""
+        for perm in permissions:
+            self.stdout.write(perm.key)
+
+    def _display_json(self, permissions):
+        """Display permissions in JSON format"""
+        data = [
+            {
+                'key': perm.key,
+                'module': perm.module,
+                'capability': perm.capability,
+                'label': perm.label,
+            }
+            for perm in permissions
+        ]
+        self.stdout.write(json.dumps(data, indent=2))

django_permission_engine-0.1.0/django_permission_engine/management/commands/upr_sync.py

@@ -0,0 +1,144 @@
+"""
+Management command to sync permissions with database
+"""
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+
+from django_permission_engine import get_registry
+
+
+class Command(BaseCommand):
+    help = 'Synchronize permission definitions with database'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            '--dry-run',
+            action='store_true',
+            help='Show what would change without making changes',
+        )
+        parser.add_argument(
+            '--force',
+            action='store_true',
+            help='Force sync even with warnings',
+        )
+        parser.add_argument(
+            '--clean-orphans',
+            action='store_true',
+            help='Delete orphaned permissions',
+        )
+        parser.add_argument(
+            '--verbose',
+            action='store_true',
+            help='Show detailed output',
+        )
+
+    def handle(self, *args, **options):
+        """Execute sync command"""
+        dry_run = options['dry_run']
+        force = options['force']
+        clean_orphans = options['clean_orphans']
+        verbose = options['verbose']
+
+        # Get registry
+        registry = get_registry()
+
+        # Set orphan action
+        if clean_orphans:
+            registry.orphan_action = 'delete'
+        elif not force:
+            registry.orphan_action = 'warn'
+
+        try:
+            # Validate first
+            if verbose:
+                self.stdout.write('Validating permissions...')
+
+            errors = registry.validate()
+            if errors:
+                self.stdout.write(
+                    self.style.ERROR(f'Validation errors found: {len(errors)}')
+                )
+                for error in errors:
+                    self.stdout.write(self.style.ERROR(f'  - {error}'))
+
+                if not force:
+                    raise CommandError('Validation failed. Use --force to continue.')
+
+            # Sync
+            if dry_run:
+                self.stdout.write(self.style.WARNING('DRY RUN - No changes will be made'))
+                plan = registry.sync(dry_run=True)
+                self._display_plan(plan, verbose)
+            else:
+                self.stdout.write('Syncing permissions...')
+                result = registry.sync()
+                self._display_result(result, verbose)
+                self.stdout.write(
+                    self.style.SUCCESS('Sync complete.')
+                )
+
+        except Exception as e:
+            raise CommandError(f'Sync failed: {e}')
+
+    def _display_plan(self, plan, verbose):
+        """Display sync plan"""
+        self.stdout.write('\nSync Plan:')
+
+        if plan['create']:
+            self.stdout.write(
+                self.style.SUCCESS(f'  Would create: {len(plan["create"])} permissions')
+            )
+            if verbose:
+                for perm in plan['create']:
+                    self.stdout.write(f'    - {perm.key}')
+
+        if plan['update']:
+            self.stdout.write(
+                self.style.WARNING(f'  Would update: {len(plan["update"])} permissions')
+            )
+            if verbose:
+                for perm in plan['update']:
+                    self.stdout.write(f'    - {perm.key}')
+
+        if plan['orphaned']:
+            self.stdout.write(
+                self.style.ERROR(f'  Orphaned: {len(plan["orphaned"])} permissions')
+            )
+            if verbose:
+                for perm in plan['orphaned']:
+                    self.stdout.write(f'    - {perm.key}')
+
+        unchanged = len(get_registry().get_all_permissions()) - len(plan['create']) - len(plan['update'])
+        if unchanged > 0:
+            self.stdout.write(f'  Unchanged: {unchanged} permissions')
+
+    def _display_result(self, result, verbose):
+        """Display sync result"""
+        if result['created']:
+            self.stdout.write(
+                self.style.SUCCESS(f'  Created: {len(result["created"])} permissions')
+            )
+            if verbose:
+                for key in result['created']:
+                    self.stdout.write(f'    - {key}')
+
+        if result['updated']:
+            self.stdout.write(
+                self.style.WARNING(f'  Updated: {len(result["updated"])} permissions')
+            )
+            if verbose:
+                for key in result['updated']:
+                    self.stdout.write(f'    - {key}')
+
+        if result['orphaned']:
+            self.stdout.write(
+                self.style.ERROR(f'  Orphaned: {len(result["orphaned"])} permissions')
+            )
+            if verbose:
+                for key in result['orphaned']:
+                    self.stdout.write(f'    - {key}')
+
+        total = len(get_registry().get_all_permissions())
+        unchanged = total - len(result['created']) - len(result['updated'])
+        if unchanged > 0:
+            self.stdout.write(f'  Unchanged: {unchanged} permissions')