Djvurn Rbac

RBAC with teams and DRF integration

Part of the djvurn package ecosystem.

Features

• 🎯 DRF-first - Complete REST API with ViewSets and serializers
• 🔐 JWT authentication - Works seamlessly with djangorestframework-simplejwt
• 📘 TypeScript support - Full type definitions (separate npm package)
• 🎨 Vue components - Ready-to-use UI components (separate npm package)
• 🧪 Well-tested - 90%+ test coverage
• 📚 Documented - Comprehensive guides and API reference

What This Wraps

This package wraps django-guardian with:

• DRF serializers, ViewSets, and permissions
• JWT authentication integration
• OpenAPI/Swagger schema generation
• Team/organization support
• Real-time updates (WebSocket)

If you're using the vanilla django-guardian, see the Migration Guide.

Installation

pip install djvurn-rbac

Or with Poetry:

poetry add djvurn-rbac

Quick Start

1. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # Django apps
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...

    # Third-party apps
    'rest_framework',
    'rest_framework_simplejwt',
    'django_guardian',  # Base package

    # djvurn packages
    'djvurn_rbac',  # This package
]

2. Configure REST Framework

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
    'PAGE_SIZE': 20,
}

3. Add URLs

# urls.py
from django.urls import path, include
from djvurn_rbac.api import router

urlpatterns = [
    path('api/', include(router.urls)),
    # ... other URLs
]

4. Run Migrations

python manage.py migrate

5. Start Using the API

# In your code
from djvurn_rbac import [TODO: Add usage example]

# Or via the API
# GET /api/[resource]/
# POST /api/[resource]/

API Documentation

Endpoints

Method	Endpoint	Description
GET	/api/[resource]/	List resources
POST	/api/[resource]/	Create resource
GET	/api/[resource]/{id}/	Retrieve resource
PUT	/api/[resource]/{id}/	Update resource
PATCH	/api/[resource]/{id}/	Partial update
DELETE	/api/[resource]/{id}/	Delete resource

Example Requests

List Resources

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://localhost:8000/api/[resource]/

Create Resource

curl -X POST \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"field": "value"}' \
     http://localhost:8000/api/[resource]/

For full API documentation, see API Reference.

Frontend Integration

TypeScript/JavaScript

Install the TypeScript package:

npm install @djvurn/rbac

Usage:

import { useResource } from '@djvurn/rbac'

const client = useResource({
  baseURL: 'http://localhost:8000/api',
  token: 'YOUR_JWT_TOKEN'
})

const items = await client.list()

Vue 3

<script setup lang="ts">
import { useResource } from '@djvurn/rbac'

const { items, loading, error, refresh } = useResource()
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">Error: {{ error }}</div>
  <div v-else>
    <div v-for="item in items" :key="item.id">
      {{ item.name }}
    </div>
  </div>
</template>

Configuration

Settings

# settings.py

# Djvurn Rbac settings
DJVURN_RBAC = {
    # Add any package-specific settings here
}

Migration from Vanilla Package

If you're currently using django-guardian:

1. Install this package alongside the base package
2. Add to INSTALLED_APPS (keep both packages)
3. Run migrations - No data migration needed
4. Update your views to use DRF ViewSets
5. Update your frontend to use the REST API

See Migration Guide for detailed steps.

Development

Setup

# Clone the mono-repo
git clone https://github.com/hmesfin/djvurn-packages.git
cd djvurn-packages/packages/djvurn-rbac

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov

Running Tests

# All tests
poetry run pytest

# Specific test file
poetry run pytest tests/test_models.py

# With coverage report
poetry run pytest --cov --cov-report=html
open htmlcov/index.html

Code Quality

# Format code
poetry run black src/ tests/
poetry run ruff check --fix src/ tests/

# Type checking
poetry run mypy src/

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Credits

• Built on top of django-guardian
• Part of the djvurn package ecosystem
• Created by Gojjo Tech

Support

• Documentation: Read the docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions