django-role-permissions

3.2.0 verified Fri May 01 auth: no python

A Django app for role-based permissions. Version 3.2.0 is the latest; release cadence is irregular. It provides a simple way to manage user roles and their associated permissions.

pip install django-role-permissions

Common errors

error django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet. ↓

cause Using role-related imports or functions at module level before Django is fully configured.

fix

Move role assignments into Django signal handlers or inside functions that are called after app setup (e.g., in apps.py ready() method).

error No module named 'rolepermissions' ↓

cause Missing import or not installed or not included in INSTALLED_APPS.

fix

Run pip install django-role-permissions and add 'rolepermissions' to INSTALLED_APPS in settings.py.

error AttributeError: module 'rolepermissions.roles' has no attribute 'assign_role' ↓

cause Outdated version (before 3.0) where assign_role was added.

fix

Upgrade to latest version: pip install --upgrade django-role-permissions or use add_role if using older version.

Warnings

gotcha Role classes must be defined in a file named `roles.py` in your Django app. The autodiscovery only looks for `roles.py`. If your file has a different name, roles won't be loaded. ↓

fix Create a `roles.py` file in your app directory and define roles there.

breaking In version 3.0, the `get_user_roles()` function was removed. Use `retrieve_role(user)` or check the role directly. ↓

fix Use `retrieve_role(user)` instead of `get_user_roles(user)`.

deprecated The `add_role` function is deprecated in favor of `assign_role`. `assign_role` works identically. ↓

fix Replace `add_role(user, role_name)` with `assign_role(user, role_name)`.

Imports

Role

wrong

from rolepermissions.role import Role

correct

from rolepermissions.roles import Role

Module is `roles`, not `role`.

Quickstart

Assign a role to a user.

from rolepermissions.roles import assign_role
from django.contrib.auth import get_user_model
User = get_user_model()
user = User.objects.create_user('john', 'john@example.com', 'password')
assign_role(user, 'admin')