Django Ninja 1.5 est sorti
par Makersquad ·
Date de sortie : 13 novembre 2025
Release officielle : Django Ninja 1.5.0
Django Ninja 1.5 apporte deux nouveautés en tête de version, les décorateurs globaux et de routeur et le filtrage par annotation dans FilterSchema, ainsi que des changements cassants à anticiper avant de mettre à jour. Python 3.13 et Django 5.2 sont désormais supportés officiellement, la compatibilité Pydantic 2.12 est ajoutée, et le paramètre csrf de NinjaAPI disparaît. Une version à lire attentivement avant d’appliquer.
Les nouveautés principales
Décorateurs globaux et de routeur
Les décorateurs, aussi appelés middlewares, s’appliquent maintenant à tous les endpoints d’une API ou d’un routeur avec add_decorator :
from ninja import Router
router = Router()
def log_operation(func):
def wrapper(request, *args, **kwargs):
print(f"Calling {func.__name__}")
result = func(request, *args, **kwargs)
print(f"Result: {result}")
return result
return wrapper
router.add_decorator(log_operation) # mode "operation" par défaut
Le mode par défaut, "operation", s’applique après la validation de Django Ninja. Avec mode="view" (api.add_decorator(func, mode="view")), le décorateur enveloppe la vue Django entière et reçoit la requête brute, ce qui convient pour ajouter des en-têtes CORS à toutes les réponses ou pour de la mise en cache.
Filtrage par annotation dans FilterSchema
FilterSchema déclare ses expressions de filtre dans une annotation FilterLookup, plutôt que dans les arguments supplémentaires de Field :
class BookFilterSchema(FilterSchema):
name: Annotated[str | None, FilterLookup("name__icontains")] = None
L’ancienne forme, Field(None, q="name__icontains"), fonctionne encore mais elle est dépréciée.
Support de Python 3.13 et Django 5.2
La suite de tests tourne maintenant sur Python 3.13 et Django 5.2. Pas de changements d’API liés à ces mises à jour. Python 3.14 rejoint aussi la matrice de tests. C’est la garantie que le framework reste testé sur des versions récentes de Python et de Django. Si votre projet est déjà sur Python 3.13 ou Django 5.2, vous pouvez mettre à jour Django Ninja en toute confiance.
Compatibilité Pydantic 2.12
Django Ninja 1.5 ajoute la compatibilité avec Pydantic 2.12.
Suppression du paramètre csrf (changement cassant)
C’est l’un des changements les plus impactants de cette version. Le paramètre csrf de NinjaAPI est supprimé.
# Avant (1.4 et antérieur) — ne fonctionne plus
api = NinjaAPI(csrf=True)
# Après (1.5) — la protection CSRF est gérée via les backends d'authentification
api = NinjaAPI()
Depuis la version 1.0, la protection CSRF est automatiquement activée lorsqu’un backend d’authentification basé sur les cookies est utilisé. Mais csrf=True n’était pas pour autant redondant : il imposait en plus un jeton CSRF à toutes les requêtes non sûres (POST, PUT, PATCH, DELETE) de l’API. Depuis la 1.5, seule l’authentification par cookie déclenche la protection CSRF. La suppression du paramètre simplifie l’API publique, mais nécessite de mettre à jour le code existant avant de migrer.
Si vous utilisiez csrf=True explicitement, c’est là que se trouve le risque de migration : un endpoint public, par exemple en POST, qui s’appuyait sur csrf=True perd sa protection CSRF en passant en 1.5. Vérifiez que votre backend d’authentification gère correctement la protection CSRF. Si vous utilisiez SessionAuth, vous n’avez rien à faire, elle active la protection CSRF automatiquement.
Suppression de la classe Config des ModelSchema au profit de Meta (changement cassant)
La classe interne Config, dépréciée dans les ModelSchema depuis la version 1.0, n’est plus acceptée. Un ModelSchema qui la déclare lève désormais une ConfigError. Il faut déclarer la configuration dans la classe Meta, introduite en 1.0. De son côté, FilterSchema abandonne class Config au profit de model_config, le mécanisme de configuration de Pydantic.
class TxItem(ModelSchema):
class Meta:
model = Transaction
fields = ["id", "account", "amount", "timestamp"]
Si l’un de vos ModelSchema utilise encore la classe Config, migrez-le vers Meta avant de passer en 1.5. Pour un FilterSchema, déclarez la configuration avec model_config.
items_attribute personnalisable dans la pagination
PageNumberPagination et LimitOffsetPagination utilisaient items comme clé fixe dans la réponse paginée. Il est maintenant possible de personnaliser ce nom via items_attribute.
from ninja.pagination import PageNumberPagination
class CustomPagination(PageNumberPagination):
items_attribute = "products"
La réponse JSON contiendra alors products à la place de items. Utile pour maintenir la cohérence avec des APIs existantes ou des conventions de nommage propres au projet.
{
"count": 42,
"products": [...]
}
Correction de l’authentification sync avec des opérations async
Un backend d’authentification synchrone qui accède à la base de données, comme django_auth, provoquait une SynchronousOnlyOperation lorsqu’il protégeait une opération asynchrone. C’est corrigé.
Correction des valeurs par défaut dans ninja.Query
Un BaseModel Pydantic simple utilisé comme paramètre Query(...) ignorait les valeurs par défaut de ses attributs : une requête qui omettait l’un de ces paramètres était rejetée avec une erreur 422. Les Schema de Django Ninja n’étaient pas touchés. Le correctif traite les dictionnaires imbriqués de valeurs par défaut.
À retenir
Django Ninja 1.5 est une version de maturité qui nettoie l’API publique et met à jour les dépendances. Les deux changements cassants à vérifier avant de mettre à jour : la suppression du paramètre csrf et la suppression de la classe Config des ModelSchema au profit de Meta. Pour le reste, les améliorations sont progressives et bienvenues. Prenez le temps de lire les notes de migration, ce n’est pas une mise à jour qu’on applique à l’aveugle.