Skip to main content

Django Ninja Extra - Class Based Utility and more for Django Ninja(Fast Django REST framework)

Project description

Test PyPI version PyPI version PyPI version PyPI version Codecov Downloads

Django Ninja Extra

Django Ninja Extra is a powerful extension for Django Ninja that enhances your Django REST API development experience. It introduces class-based views and advanced features while maintaining the high performance and simplicity of Django Ninja. Whether you're building a small API or a large-scale application, Django Ninja Extra provides the tools you need for clean, maintainable, and efficient API development.

Features

Core Features (Inherited from Django Ninja)

  • High Performance: Built on Pydantic for lightning-fast validation
  • 🔄 Async Support: First-class support for async/await operations
  • 📝 Type Safety: Comprehensive type hints for better development experience
  • 🎯 Django Integration: Seamless integration with Django's ecosystem
  • 📚 OpenAPI Support: Automatic API documentation with Swagger/ReDoc
  • 🔒 API Throttling: Rate limiting for your API

Extra Features

  • 🏗️ Class-Based Controllers:

    • Organize related endpoints in controller classes
    • Inherit common functionality
    • Share dependencies across endpoints
  • 🔒 Advanced Permission System (Similar to Django Rest Framework):

    • Controller-level permissions
    • Route-level permission overrides
    • Custom permission classes
  • 💉 Dependency Injection:

  • 🔧 Service Layer:

    • Injectable services for business logic
    • Better separation of concerns
    • Reusable components

Requirements

  • Python >= 3.6
  • Django >= 2.1
  • Pydantic >= 1.6
  • Django-Ninja >= 0.16.1

Installation

  1. Install the package:
pip install django-ninja-extra
  1. Add to INSTALLED_APPS:
INSTALLED_APPS = [
    ...,
    'ninja_extra',
]

Quick Start Guide

1. Basic API Setup

Create api.py in your Django project:

from ninja_extra import NinjaExtraAPI, api_controller, http_get

api = NinjaExtraAPI()

# Function-based endpoint example
@api.get("/hello", tags=['Basic'])
def hello(request, name: str = "World"):
    return {"message": f"Hello, {name}!"}

# Class-based controller example
@api_controller('/math', tags=['Math'])
class MathController:
    @http_get('/add')
    def add(self, a: int, b: int):
        """Add two numbers"""
        return {"result": a + b}

    @http_get('/multiply')
    def multiply(self, a: int, b: int):
        """Multiply two numbers"""
        return {"result": a * b}

# Register your controllers
api.register_controllers(MathController)

2. URL Configuration

In urls.py:

from django.urls import path
from .api import api

urlpatterns = [
    path("api/", api.urls),  # This will mount your API at /api/
]

Advanced Features

Authentication and Permissions

from ninja_extra import api_controller, http_get
from ninja_extra.permissions import IsAuthenticated, PermissionBase

# Custom permission
class IsAdmin(PermissionBase):
    def has_permission(self, context):
        return context.request.user.is_staff

@api_controller('/admin', tags=['Admin'], permissions=[IsAuthenticated, IsAdmin])
class AdminController:
    @http_get('/stats')
    def get_stats(self):
        return {"status": "admin only data"}
    
    @http_get('/public', permissions=[])  # Override to make public
    def public_stats(self):
        return {"status": "public data"}

Dependency Injection with Services

from injector import inject
from ninja_extra import api_controller, http_get


# Service class
class UserService:
    def get_user_details(self, user_id: int):
        return {"user_id": user_id, "status": "active"}


# Controller with dependency injection
@api_controller('/users', tags=['Users'])
class UserController:
    def __init__(self, user_service: UserService):
        self.user_service = user_service

    @http_get('/{user_id}')
    def get_user(self, user_id: int):
        return self.user_service.get_user_details(user_id)

API Documentation

Access your API's interactive documentation at /api/docs:

Swagger UI

Learning Resources

Tutorials

Community and Support

Contributing

We welcome contributions! Here's how you can help:

  1. Fork the repository
  2. Create a feature branch
  3. Write your changes
  4. Submit a pull request

Please ensure your code follows our coding standards and includes appropriate tests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support the Project

  • ⭐ Star the repository
  • 🐛 Report issues
  • 📖 Contribute to documentation
  • 🤝 Submit pull requests

DEPRECATION NOTICE

0.22.2

The service attribute in ModelController has been changed from a class object to an instance object. When creating a custom ModelService for a ModelController, you have to specify it as service_type.

This is because services are now injected as dependencies during controller instantiation. Service instantiation is delegated to the injector package, so ensure that any additional dependencies required by your ModelService are properly registered in the dependency injection container.

For more details, please refer to the documentation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_ninja_extra-0.22.3.tar.gz (51.1 kB view details)

Uploaded Source

Built Distribution

django_ninja_extra-0.22.3-py3-none-any.whl (67.9 kB view details)

Uploaded Python 3

File details

Details for the file django_ninja_extra-0.22.3.tar.gz.

File metadata

  • Download URL: django_ninja_extra-0.22.3.tar.gz
  • Upload date:
  • Size: 51.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for django_ninja_extra-0.22.3.tar.gz
Algorithm Hash digest
SHA256 2a7f53a6fd0c622987759c1eba865aa8eb5d56380b5a650cb3ce7220a3221870
MD5 d10652c7348ab27b54d583b5788635b8
BLAKE2b-256 fc7db0741cf886c7449250045d6c1fa52d581754e36a5b905e1b380aa8ddbeb1

See more details on using hashes here.

File details

Details for the file django_ninja_extra-0.22.3-py3-none-any.whl.

File metadata

File hashes

Hashes for django_ninja_extra-0.22.3-py3-none-any.whl
Algorithm Hash digest
SHA256 4a93337933e5dcc1ea742531ca68d77b718e2df0dcdadb12e60b67594189a720
MD5 ec2a940a278d5f653f35dd72a4d1fd7d
BLAKE2b-256 53d65c6e38ab6f9858fcc825ee5161139ba6719e6e27dc0ba1416bb9d4df4597

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page