Django Ninja 1.0 est sorti
par Makersquad ·
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.