Django Ninja 1.4 est sorti
par Makersquad ·
Date de sortie : 26 mars 2025
Release officielle : Django Ninja 1.4.0
Django Ninja 1.4 s’attaque à des limitations concrètes que les équipes rencontrent en production : les champs Django personnalisés non reconnus par l’ORM mapper, le throttling limité à des intervalles d’une seule unité (5/s, 100/d), et les uploads de fichiers en PUT ou PATCH qui échouaient sans explication faute du middleware nécessaire.
Les nouveautés principales
Enregistrement de champs Django personnalisés
Si votre projet utilise des champs Django personnalisés, Django Ninja ne savait pas comment les mapper vers un type Pydantic. La version 1.4 apporte une façon standard d’enregistrer cette correspondance avec register_field.
from ninja.orm import register_field
register_field("MyCustomField", int)
Le premier argument est le nom du champ Django (son type interne, tel que le renvoie get_internal_type()), pas la classe ; le second est le type Python associé.
Throttling multi-période
Les versions précédentes n’acceptaient que des intervalles d’une seule unité, comme 5/s ou 100/d, ce qui limitait la finesse des règles. Le throttling accepte désormais des intervalles multi-périodes, comme 5/30s, 10/5m et 100/2h : un nombre d’unités suivi d’une unité de temps (s, m, h ou d), les secondes par défaut quand l’unité est omise.
from ninja.throttling import UserRateThrottle
@api.get('/some', throttle=[UserRateThrottle('100/5m')])
def some(request):
...
Ici, 100/5m représente 100 requêtes par tranche de 5 minutes.
Uploads de fichiers en PUT et PATCH via middleware
Envoyer des fichiers via multipart/form-data en POST fonctionne nativement dans Django. En revanche, Django ne renseigne pas request.FILES pour des méthodes comme PUT et PATCH. Les utilisateurs ne comprenaient pas pourquoi leurs endpoints ne validaient pas, et devaient ajouter un middleware spécial qui corrige ce comportement.
Avec la version 1.4, Django Ninja prévient automatiquement l’utilisateur dans ce cas et lui demande d’ajouter ce middleware lorsqu’il utilise des méthodes autres que POST.
# settings.py
MIDDLEWARE = [
"ninja.compatibility.files.fix_request_files_middleware",
...
]
Avec ce middleware en place, les endpoints PATCH et PUT peuvent recevoir des fichiers exactement comme les endpoints POST.
from ninja import File, UploadedFile
@api.patch("/products/{product_id}/image")
def update_product_image(request, product_id: int, image: UploadedFile = File(...)):
product = get_object_or_404(Product, id=product_id)
product.image.save(image.name, image)
return {"status": "updated"}
Sérialisation de IPNetwork et URL
Les types Python ipaddress.IPv4Network, ipaddress.IPv6Network et les URL Pydantic sont désormais correctement sérialisés dans les réponses JSON. Plus besoin de convertir manuellement ces types en chaînes de caractères dans les schémas de sortie.
PageNumberPagination avec page_size dynamique
PageNumberPagination accepte maintenant un paramètre page_size dans la requête, ce qui permet au client de choisir le nombre d’éléments par page dans une plage définie par le serveur.
from ninja.pagination import paginate, PageNumberPagination
@api.get("/items", response=list[ItemOut])
@paginate(PageNumberPagination, page_size=20, max_page_size=100) # le client ne peut pas dépasser 100
def list_items(request):
return Item.objects.all()
À retenir
Django Ninja 1.4 résout des limitations qui forçaient parfois à des contournements peu élégants. L’enregistrement de champs personnalisés et le throttling multi-période sont les deux fonctionnalités qui auront le plus d’impact sur les projets un peu avancés. À mettre à jour en priorité si vous utilisez des champs ORM custom ou si vous avez du rate limiting en production.