Aller au contenu
Makersquad

Django Ninja 1.0 est sorti

par Makersquad ·

Logo de Django Ninja sur fond dégradé

Date de sortie : 16 novembre 2023

Documentation officielle : Django Ninja 1.0

Django Ninja passe en 1.0 et devient un choix sérieux pour les APIs Django. Vous aimez FastAPI mais vous êtes sur Django ? C’est exactement ce qu’il vous faut : type hints, Pydantic, OpenAPI automatique, le tout intégré à Django.

Qu’est-ce que Django Ninja ?

Django Ninja est un framework pour construire des APIs avec Django, inspiré de FastAPI :

from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/hello")
def hello(request, name: str = "World"):
    return {"message": f"Hello {name}"}

Type hints + validation Pydantic + documentation OpenAPI automatique.

Les nouveautés de la version 1.0

Support de Pydantic v2

Pydantic v2 est réécrit en Rust avec des performances améliorées :

from ninja import Schema

class UserIn(Schema):
    username: str
    email: str
    age: int | None = None  # Syntaxe Python 3.10+

class UserOut(Schema):
    id: int
    username: str

Performances améliorées

  • ~10% de gain moyen sur les projets
  • Jusqu’à 4x plus rapide sur certains cas de parsing/serialization

Contexte de requête dans Pydantic

La requête est passée automatiquement au contexte Pydantic :

class Payload(Schema):
    id: int
    name: str
    request_path: str

    @staticmethod
    def resolve_request_path(data, context):
        request = context["request"]
        return request.get_full_path()

Pendant la réponse, le code de réponse (response_code) est lui aussi passé au contexte.

Migration depuis 0.x

Pydantic 1 et Pydantic 2 sont peu compatibles, et Django Ninja s’intègre trop profondément à Pydantic pour supporter les deux : la 1.0 abandonne Pydantic v1. Si vous utilisiez la classe Schema, la migration est simple. Sinon, suivez le guide de migration de Pydantic (s’ouvre dans un nouvel onglet).

Pour les ModelSchema, Pydantic déprécie la classe Config. Django Ninja introduit une classe Meta, qui fonctionne comme celle des ModelForm de Django (la classe Config reste supportée, mais dépréciée) :

class TxItem(ModelSchema):
    class Meta:
        model = Transaction
        fields = ["id", "account", "amount", "timestamp"]

Authentification asynchrone

Les authentificateurs asynchrones sont enfin supportés : il suffit d’ajouter async à la méthode authenticate.

class Auth(HttpBearer):
    async def authenticate(self, request, token):
        await asyncio.sleep(1)
        if token == "secret":
            return token

CSRF automatique

Avec une authentification par cookie, la protection CSRF est désormais activée automatiquement, sans l’exigence csrf=True de la 0.x. On peut donc combiner des authentificateurs protégés contre le CSRF et d’autres qui n’utilisent pas de cookie :

api = NinjaAPI(auth=[django_auth, Auth()])

Syntaxe Annotated et marqueurs de paramètres plus courts

typing.Annotated est supporté, et les marqueurs de paramètres s’écrivent plus simplement. L’ancienne syntaxe reste supportée :

@api.post('/some')
def some_form(request, username: Form[str], password: Form[str]):
    return True

@api.get("/annotated")
def annotated(request, data: Annotated[SomeData, Form()]):
    return {"data": data.dict()}

Routeurs ajoutés par chaîne d’import

add_router accepte un chemin sous forme de chaîne, sans import explicite :

api = NinjaAPI()

api.add_router('/app1', 'myproject.app1.router')
api.add_router('/app2', 'myproject.app2.router')

Évolution de la version

Django Ninja passe en 1.0 à cause du changement de version de Pydantic, qui peut apporter quelques dépréciations ou changements cassants au niveau de Pydantic. Pour une API standard, sans trop de « magie », la mise à jour devrait se faire sans changer le code.

Exemple complet

from ninja import NinjaAPI, Schema
from typing import List

api = NinjaAPI()

class BookIn(Schema):
    title: str
    author: str
    year: int

class BookOut(Schema):
    id: int
    title: str
    author: str

@api.post("/books", response=BookOut)
def create_book(request, book: BookIn):
    obj = Book.objects.create(**book.model_dump())
    return obj

@api.get("/books", response=List[BookOut])
def list_books(request):
    return Book.objects.all()

À retenir

Django Ninja 1.0 s’appuie sur Pydantic 2 et apporte l’authentification asynchrone, la protection CSRF automatique, la syntaxe Annotated et les routeurs ajoutés par chaîne d’import. Si vous construisez des APIs avec Django et que les annotations de type vous parlent, cette 1.0 mérite qu’on s’y intéresse.

Échanger avec un expert Django

De l’idée au marché. Makersquad conçoit des logiciels sur mesure, pensés pour durer, avec de petites équipes d’experts autonomes. Depuis 2018.