Django Ninja 1.4

Date de sortie : 26 mars 2025

Documentation officielle : https://django-ninja.dev

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 trop rigide limité à une seule fenêtre temporelle, et l’impossibilité d’uploader des fichiers via des requêtes PUT ou PATCH. Trois problèmes résolus, trois raisons de mettre à jour.

Les nouveautés principales

Enregistrement de champs Django personnalisés

Si votre projet utilise des champs Django personnalisés — un ColorField, un MoneyField, un EncryptedField — vous avez probablement rencontré l’erreur ImproperlyConfigured au moment de générer un ModelSchema. Django Ninja ne savait pas comment mapper ces champs vers un type Pydantic.

La version 1.4 introduit register_field pour déclarer explicitement cette correspondance.

from ninja.orm import register_field

class ColorField(models.CharField):
    ...

# Associer le champ Django à un type Pydantic
register_field(ColorField, str)

Pour les cas plus complexes, il est possible de passer un type Pydantic personnalisé ou un validateur annoté à la place de str. L’intégration est propre et ne nécessite pas de surcharger le moteur de génération de schémas.

Throttling multi-période

Le rate limiting dans les versions précédentes ne supportait qu’une seule règle par throttle : par exemple, 100 requêtes par heure. En pratique, on a souvent besoin de règles combinées : pas plus de 5 requêtes en 30 secondes, pas plus de 10 en 5 minutes, pas plus de 100 en 2 heures.

Django Ninja 1.4 permet de définir plusieurs fenêtres dans une seule déclaration.

from ninja.throttling import UserRateThrottle

class APIThrottle(UserRateThrottle):
    THROTTLE_RATES = {"api_limit": "5/30s, 10/5m, 100/2h"}

Les fenêtres sont évaluées indépendamment. Une requête est rejetée dès qu’elle dépasse l’une des limites. C’est exactement le comportement attendu pour protéger une API contre les pics courts sans bloquer les usages légitimes sur la durée.

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 n’analyse pas le corps des requêtes PUT et PATCH de la même façon, ce qui rendait les uploads de fichiers impossibles dans ces méthodes HTTP avec Django Ninja.

La version 1.4 contourne ce comportement via un middleware dédié.

# 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

class FlexiblePagination(PageNumberPagination):
    page_size = 20
    max_page_size = 100  # le client ne peut pas dépasser cette valeur

@api.get("/items", response=list[ItemOut])
@paginate(FlexiblePagination)
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.