Django Extensions

Le guide technique de référence. Commandes, configuration avancée et astuces de production.

Installation & Setup

Installation avancée, configuration `settings.py`, gestion des dépendances optionnelles (Graphviz, Werkzeug) et environnements.

Setup Configuration

Shell Plus (Avancé)

Maîtriser le REPL : SQL printing, intégration IPython/Jupyter, configuration des imports automatiques et alias.

Productivité Debug

Graph Models (ERD)

Générer des diagrammes UML/ERD de vos bases de données. Options de filtrage, héritage et formats de sortie (.dot, .png).

Architecture Documentation

RunServer Plus

Le serveur de dev sous stéroïdes : Débogueur Werkzeug interactif, support SSL (HTTPS) local, et profiling de requêtes.

DevOps SSL

Code Generators

Ne codez plus à la main : admin_generator, scaffold de commandes, modèles et formulaires automatiques.

Scaffolding Admin

Data Ops & Scripts

Commandes critiques : reset_db, sqldiff, runscript pour exécuter des logiques métier complexes.

Ops Maintenance

Audit & Introspection

Comprendre son projet : show_urls, notes (TODOs), describe_form et validation des templates.

Quality Routing

Jobs Scheduling

Système de tâches planifiées (Cron-like) intégré. DailyJob, HourlyJob : implémentation et exécution.

Automation Cron

Exports & Utils

Extraction de données (emails), synchronisation S3, et autres utilitaires méconnus mais puissants.

Tools S3

1. Installation & Configuration Avancée

Méthodes d'Installation

Django Extensions est un paquet stable qui suit les releases de Django. Il est recommandé de l'installer uniquement dans les environnements de développement et de staging, bien que certaines commandes (comme les Jobs) puissent servir en production.

Via Pip (Standard)

BASH

pip install django-extensions

Via Poetry (Recommandé)

Séparez clairement vos dépendances de développement.

BASH

poetry add django-extensions --group dev

Fichier requirements.txt

Si vous utilisez des fichiers séparés :

requirements-dev.txt

django-extensions==3.2.3 Werkzeug==3.0.1 # Requis pour runserver_plus pygraphviz==1.11 # Requis pour graph_models

Configuration Django

L'ajout dans INSTALLED_APPS suffit pour activer les commandes, mais il faut être prudent sur l'environnement.

Configuration Basique

settings.py

INSTALLED_APPS = [ 'django.contrib.admin', # ... 'django_extensions', ]

Configuration "Best Practice" (Env Dev Uniquement)

Pour éviter d'exposer des commandes dangereuses (comme reset_db) en production :

settings.py

if DEBUG: INSTALLED_APPS += ['django_extensions'] # Configuration spécifique Shell Plus SHELL_PLUS = "ipython" # Imports automatiques supplémentaires SHELL_PLUS_IMPORTS = [ 'from my_app.utils import my_utility_function', 'import json', ]

Dépendances Externes & Optionnelles

Django Extensions est modulaire. Beaucoup de commandes échoueront si les libs sous-jacentes ne sont pas là.

Werkzeug : Obligatoire pour runserver_plus. C'est lui qui fournit le débogueur interactif.
pip install werkzeug
IPython / Jupyter : Obligatoire pour un shell coloré et l'autocomplétion avancée.
pip install ipython jupyter
PyGraphviz : Obligatoire pour graph_models.
Requires system-level install : sudo apt-get install graphviz libgraphviz-dev (Linux) ou via Brew (Mac).
Puis : pip install pygraphviz

2. Shell Plus : Le REPL Ultime

Pourquoi utiliser Shell Plus ?

La commande python manage.py shell native est vide. Vous devez importer manuellement vos modèles à chaque fois. shell_plus résout cela.

TERMINAL

$ python manage.py shell_plus # Output automatique au lancement : # Importe User, Group, Permission... # Importe vos apps : Blog, Author, Comment... # Detecte IPython et l'utilise automatiquement. In [1]: Author.objects.first() # Fonctionne immédiatement !

Collisions de noms

Si deux apps ont un modèle Category, shell_plus les renommera automatiquement : App1Category et App2Category et vous avertira.

Voir le SQL en temps réel (--print-sql)

C'est l'outil pédagogique et de débogage ultime pour comprendre l'ORM Django. Il affiche la requête SQL brute générée pour chaque commande Python.

TERMINAL

$ python manage.py shell_plus --print-sql In [1]: User.objects.filter(is_active=True).count() SELECT COUNT(*) AS "__count" FROM "auth_user" WHERE "auth_user"."is_active" = True Execution time: 0.00124s [Database: default] Out[1]: 42

Idéal pour détecter les problèmes de N+1 queries lors de l'accès aux relations (ForeignKeys).

Intégration Jupyter Notebook

Transformez votre projet Django en environnement de Data Science. Cela lance un serveur Jupyter où le contexte Django (modèles, DB) est déjà chargé.

BASH

# Nécessite pip install jupyter python manage.py shell_plus --notebook

Le navigateur s'ouvre. Vous pouvez créer des graphiques (Matplotlib) basés sur vos données Django directement dans le notebook.

3. Graph Models : Visualisation ERD

Générer un diagramme de classe

Cette commande inspecte tous vos modèles et génère un fichier DOT (Graphviz). Elle peut convertir directement en PNG si les librairies sont installées.

BASH

# Génère un fichier .dot (texte) python manage.py graph_models -a > my_project.dot # Génère directement une image (nécessite pygraphviz) python manage.py graph_models -a -g -o my_project.png

Le résultat : Une image montrant chaque modèle comme une boîte, avec ses champs, ses types, et des flèches représentant les ForeignKeys et ManyToMany.

Cibler des applications

Sur un gros projet, le graphe complet est illisible ("Spaghetti diagram"). Il faut cibler.

BASH

# Uniquement l'app 'ecommerce' et 'users' python manage.py graph_models ecommerce users -o shop_schema.png # Exclure certains modèles spécifiques python manage.py graph_models ecommerce -X AuditLog,History -o clean_schema.png

4. RunServer Plus

Débogueur Interactif dans le navigateur

Remplace la page jaune d'erreur standard de Django par celle de Werkzeug.

BASH

python manage.py runserver_plus

Fonctionnalité clé

Lors d'un crash, vous voyez la stack trace. À droite de chaque ligne, une petite icône de console apparaît. Cliquez dessus : vous avez un shell Python interactif DANS le navigateur, à l'endroit exact du crash.

Vous pouvez taper print(my_variable) pour inspecter l'état local.

Développement en HTTPS

Certaines APIs (Stripe, OAuth, Webhooks, Géolocalisation) requièrent HTTPS même en local.

BASH

# Utilise un certificat ad-hoc (auto-généré, le navigateur va râler mais ça marche) python manage.py runserver_plus --cert-file cert.crt # Si vous avez 'pip install pyOpenSSL', c'est encore plus simple : python manage.py runserver_plus --cert cert

Le serveur écoute maintenant sur https://localhost:8000.

5. Générateurs de Code

admin_generator

Écrire les ModelAdmin est ennuyeux. Cette commande inspecte vos modèles et produit un code admin complet et optimisé.

BASH

python manage.py admin_generator my_app > my_app/admin.py

Exemple de sortie générée :

PYTHON

@admin.register(Product) class ProductAdmin(admin.ModelAdmin): list_display = ('id', 'name', 'slug', 'price', 'created', 'updated') list_filter = ('created', 'updated', 'category') search_fields = ('name', 'slug') prepopulated_fields = {'slug': ('name',)} date_hierarchy = 'created'

Elle détecte automatiquement les dates pour date_hierarchy, les FK pour list_filter, et les champs textes pour search_fields.

6. Data Ops & Scripts

runscript

Permet d'exécuter des scripts Python arbitraires dans le contexte Django sans avoir à créer une "Management Command" complète.

Structure

Créez un dossier scripts/ à la racine (ou dans une app) avec un __init__.py.

scripts/import_users.py

from my_app.models import User def run(): print("Début import...") # Logique métier User.objects.create(username="Test")

Exécution

BASH

python manage.py runscript import_users

sqldiff

Compare vos modèles Django (code) avec l'état réel de la base de données. Très utile pour détecter les migrations manquantes ou les modifications manuelles en DB.

python manage.py sqldiff my_app

⚠️ Commande Destructive

Cette commande détruit tout. À utiliser uniquement en début de projet ou en CI/CD.

reset_db

Supprime la base de données (DROP DATABASE), la recrée (CREATE DATABASE) et réapplique les migrations (si configuré).

python manage.py reset_db

7. Audit & Introspection

show_urls

Affiche la liste complète de toutes les routes URL définies dans votre projet. Indispensable pour déboguer les erreurs 404 ou les conflits de regex.

BASH

python manage.py show_urls

Affiche un tableau avec : URL Pattern, View Function, Name.

describe_form

Génère la définition d'une classe django.forms.Form à partir d'un modèle existant. Copiez-collez le résultat pour créer vos formulaires rapidement.

python manage.py describe_form my_app.MyModel

notes (TODO scanner)

Scanne tout votre code source pour extraire les commentaires TODO, FIXME, XXX, HACK.

python manage.py notes

validate_templates

Vérifie la syntaxe de tous vos fichiers HTML. Détecte les balises non fermées ou les tags Django invalides avant la mise en prod.

python manage.py validate_templates

8. Jobs Scheduling

Créer un Job

Créez un dossier jobs/ dans votre app. Créez un fichier python (ex: daily_cleanup.py).

PYTHON

from django_extensions.management.jobs import DailyJob class Job(DailyJob): help = "Nettoyage quotidien" def execute(self): # Votre logique ici print("Job exécuté !")

Types disponibles : HourlyJob, DailyJob, WeeklyJob, MonthlyJob.

Lister et Lancer

BASH

# Lister les jobs disponibles python manage.py runjobs -l # Lancer un job spécifique python manage.py runjob daily_cleanup # Lancer tous les jobs quotidiens python manage.py runjobs daily

Dans la Crontab système

Ajoutez simplement une ligne dans votre crontab Linux pour exécuter la commande de management.

CRONTAB

# Exécute les jobs "Hourly" à la minute 0 de chaque heure 0 * * * * cd /path/to/project && python manage.py runjobs hourly

9. Exports & Utils

export_emails

Exporte les adresses email, noms et prénoms de tous les utilisateurs dans différents formats (CSV, HTML, etc.).

python manage.py export_emails --format=csv > emails.csv

sync_s3

Synchronise le dossier MEDIA_ROOT local vers un bucket Amazon S3 (requiert boto).

python manage.py sync_s3 my-bucket-name

clear_cache

Vide entièrement le cache défini dans vos settings Django.

python manage.py clear_cache

print_settings

Affiche la valeur d'une variable de configuration. Pratique dans les scripts CI/CD.

python manage.py print_settings INSTALLED_APPS