Metadata-Version: 2.4
Name: drf-api-role-permissions
Version: 1.0.0
Summary: Role-based API and model field permissions for Django REST Framework
Author-email: Arash Eghdam <arash.eghdam.84@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/arasheghdam84/drf-api-role-permissions
Project-URL: Repository, https://github.com/arasheghdam84/drf-api-role-permissions
Project-URL: Issues, https://github.com/arasheghdam84/drf-api-role-permissions/issues
Keywords: django,drf,rest-framework,rbac,permissions,roles
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: django-filter>=23.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# drf-api-role-permissions

Role-based access control for Django REST Framework. Assign users to roles, grant API endpoint access by URL name and HTTP method, and restrict model field visibility and object access at the serializer and queryset level.

## Features

- **API permissions** — sync discovered URL patterns and enforce access by `url_name` + HTTP method
- **Model permissions** — field-level and object-level restrictions for view, edit, and create actions
- **Automatic DRF integration** — optional monkey-patches for `ModelSerializer` and `GenericAPIView`
- **Management API** — REST endpoints to manage roles, permissions, and user assignments
- **Django admin** — manage roles and model permissions from the admin site

## Installation

```bash
pip install drf-api-role-permissions
```

Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "django_filters",
    "role_permissions",
]
```

Run migrations:

```bash
python manage.py migrate role_permissions
```

## Quick start

### 1. Wire up URLs

```python
# urls.py
from django.urls import include, path

urlpatterns = [
    path("api/v1/rbac/", include("role_permissions.urls")),
]
```

### 2. Enable API permission checks

Every protected endpoint must have a named URL pattern. Then set the default DRF permission class:

```python
REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "role_permissions.permissions.HasAPIRolePermission",
    ],
}
```

### 3. Sync API permissions

Discover all named URL routes and store them in the database:

```bash
python manage.py sync_api_permissions
```

### 4. Assign roles

Use the management API or Django admin to:

1. Create a `Role`
2. Attach `APIPermission` and `ModelPermission` records
3. Assign the role to a user via `UserRole`

## Configuration

Optional settings under `RBAC` in `settings.py`:

```python
RBAC = {
    # Auto-patch ModelSerializer and GenericAPIView (default: True)
    "AUTO_PATCH_SERIALIZERS": True,

    # Apps excluded from model/field discovery
    "EXCLUDE_APPS": ["admin", "auth", "contenttypes", "sessions", "messages", "staticfiles", "role_permissions"],

    # URL path regexes excluded from API permission sync
    "EXCLUDE_URL_REGEXES": [r"^admin/.*$", r"^docs/.*$", r"^static/.*$", r"^media/.*$"],

    # Role permission cache TTL in seconds
    "CACHE_TTL": 3600,

    # Fields shown in nested user serializers
    "USER_DETAIL_FIELDS": ("id", "username", "first_name", "last_name", "email"),

    # Pagination class for management API list views
    "PAGINATION_CLASS": "role_permissions.pagination.DefaultLimitOffsetPagination",
}
```

### Middleware (optional)

If serializers are created without request context, enable thread-local request storage:

```python
MIDDLEWARE = [
    # ...
    "role_permissions.middleware.CurrentRequestMiddleware",
]
```

## Serializer integration

### Automatic patching (default)

When `AUTO_PATCH_SERIALIZERS` is enabled, all `ModelSerializer` instances automatically enforce field permissions, and list/retrieve/update views filter objects by `object_ids`.

### Explicit mixin

Disable auto-patching and use the mixin on specific serializers:

```python
from role_permissions.serializer_mixins import RolePermissionsModelSerializer

class ProductSerializer(RolePermissionsModelSerializer):
    class Meta:
        model = Product
        fields = "__all__"
```

Opt out per serializer:

```python
class PublicSerializer(RolePermissionsModelSerializer):
    class Meta:
        model = Product
        fields = ("id", "name")
        disable_rbac = True
```

## License

MIT
