Le chemin d'une requête

Comprendre le cycle de vie est crucial pour le débogage et la performance.

1. WSGI/ASGI : Le serveur web (Nginx/Gunicorn) passe la main à Django.
2. Middleware (Entrée) : La requête traverse les couches de sécurité, session, CSRF.
3. URL Resolution : Django cherche une correspondance dans urlpatterns.
4. View Processing : La fonction ou classe est exécutée.
5. Middleware (Sortie) : La réponse traverse les couches en sens inverse.

Le concept d'"Oignon" (Middleware)

                            Requête Entrante ⬇️      ⬆️ Réponse Sortante
                            ┌──────────────────────────────────────────┐
                            │ SecurityMiddleware                       │
                            │  ┌────────────────────────────────────┐  │
                            │  │ SessionMiddleware                  │  │
                            │  │  ┌──────────────────────────────┐  │  │
                            │  │  │ CommonMiddleware             │  │  │
                            │  │  │  ┌────────────────────────┐  │  │  │
                            │  │  │  │ CSRFViewMiddleware     │  │  │  │
                            │  │  │  │  ┌──────────────────┐  │  │  │  │
                            │  │  │  │  │ AuthMiddleware   │  │  │  │  │
                            │  │  │  │  │    YOUR VIEW     │  │  │  │  │
                            │  │  │  │  └──────────────────┘  │  │  │  │
                            │  │  │  └────────────────────────┘  │  │  │
                            │  │  └──────────────────────────────┘  │  │
                            │  └────────────────────────────────────┘  │
                            └──────────────────────────────────────────┘
                        

Arborescence Typique

                            my_project/             # Racine (Repo Git)
                            │
                            ├── manage.py           # CLI (Command Line Interface)
                            ├── requirements.txt    # Dépendances
                            ├── .env                # Secrets (ne pas commiter)
                            │
                            ├── my_project/         # Dossier de configuration
                            │   ├── __init__.py
                            │   ├── settings.py     # Config globale
                            │   ├── urls.py         # Routes principales
                            │   ├── wsgi.py         # Point d'entrée serveur Sync
                            │   └── asgi.py         # Point d'entrée serveur Async
                            │
                            └── core/               # Une "App" (Module métier)
                            ├── migrations/     # Versionning BDD
                            ├── admin.py        # Config Admin
                            ├── apps.py         # Config App
                            ├── models.py       # Structure des données
                            ├── tests.py        # Tests unitaires
                            ├── urls.py         # Routes de l'app
                            └── views.py        # Logique des vues
                        

Commandes Essentielles

Le fichier manage.py est votre baguette magique.

API & sérialisation

Tâches asynchrones & temps différé

Authentification avancée & Social Login

Debug, perf & tooling

1. Création

Placez-vous dans le dossier de votre projet.

                            # Créer le dossier "venv"
                            python -m venv venv
                            # ou
                            python3 -m venv venv
                        

2. Activation

Une fois activé, votre prompt terminal changera (ex: (venv) user@pc...).

Installation Standard

                            # Mettre à jour pip (bon réflexe)
                            python -m pip install --upgrade pip

                            # Installer la dernière version stable
                            pip install django

                            # Vérifier l'installation
                            python -m django --version
                        

Version Spécifique & Requirements

                            # Installer une version précise (ex: LTS)
                            pip install django==4.2.7

                            # Figer les versions pour la prod
                            pip freeze > requirements.txt

                            # Installer depuis un fichier
                            pip install -r requirements.txt
                        

Erreur : "Scripts is disabled on this system" (Windows)

PowerShell bloque l'exécution de scripts par défaut.

                            # Solution : Autoriser l'exécution (Admin)
                            Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
                        

Erreur : "pip command not found"

Python n'est pas dans le PATH ou pip n'est pas installé.

                            # Essayez d'utiliser le module python directement
                            python -m pip install django
                            # Au lieu de juste "pip install ..."
                        

1. Création du Projet (La bonne méthode)

L'erreur classique est de créer des dossiers imbriqués inutiles.

                            # ❌ Mauvaise pratique (crée projet/projet/manage.py)
                            django-admin startproject mysite

                            # ✅ Bonne pratique (le point final est crucial)
                            mkdir ideolab_project
                            cd ideolab_project
                            django-admin startproject config . 
                        

Pourquoi appeler le dossier de config config au lieu du nom du projet ?

• C'est une convention moderne.
• Ça distingue clairement la configuration des applications métier.
• Ça simplifie les imports (ex: from config import settings).

2. Création des Apps

                            python manage.py startapp core
                            python manage.py startapp accounts
                            python manage.py startapp dashboard
                        

3. Le Registre des Apps (INSTALLED_APPS)

Si une app n'est pas ici, Django l'ignore (pas de migrations, pas de templates, pas de tests).

                            # config/settings.py

                            INSTALLED_APPS = [
                            # Apps natives Django (Batteries)
                            'django.contrib.admin',
                            'django.contrib.auth',
                            'django.contrib.contenttypes',
                            'django.contrib.sessions',
                            'django.contrib.messages',
                            'django.contrib.staticfiles',

                            # Apps Tiers (Libs installées via pip)
                            'rest_framework',
                            'debug_toolbar',

                            # Vos Apps Locales (Ordre important pour l'override)
                            'core.apps.CoreConfig',      # Recommandé: utiliser la config class
                            'accounts.apps.AccountsConfig',
                            'dashboard.apps.DashboardConfig',
                            ]
                        

📁 Niveau Racine (Root)

📁 Dossier de Config (config/)

📁 Dossier App (ex: core/)

                            core/
                            ├── migrations/      # Historique SQL (Versionning de la BDD)
                            │   └── 0001_initial.py
                            ├── __init__.py      # Fait du dossier un package Python
                            ├── admin.py         # Configuration de l'interface /admin/
                            ├── apps.py          # Métadonnées (Nom verbose, Signaux au démarrage)
                            ├── models.py        # ORM: Définition des tables et relations
                            ├── tests.py         # Tests unitaires (unittest/pytest)
                            ├── views.py         # Logique métier (Request -> Response)
                            ├── urls.py          # (Optionnel mais recommandé) Routes locales
                            ├── forms.py         # (À créer) Gestion des formulaires & validation
                            ├── signals.py       # (À créer) Hooks événementiels
                            └── management/      # (À créer) Commandes custom manage.py
                            └── commands/
                        

1. URL Globale (config/urls.py)

On "monte" les apps sur des préfixes.

                            from django.urls import path, include

                            urlpatterns = [
                            path('admin/', admin.site.urls),

                            # Délégation: Tout ce qui commence par "blog/" 
                            # est envoyé à l'app blog.
                            path('blog/', include('blog.urls')), 

                            # Délégation: La racine est gérée par core
                            path('', include('core.urls')), 
                            ]
                        

2. URL Locale (blog/urls.py)

On définit les routes finales et les variables.

                            from django.urls import path
                            from . import views

                            # app_name permet le reverse routing :  {% url 'blog:detail' %}   
                            app_name = 'blog' 

                            urlpatterns = [
                            # Match: /blog/
                            path('', views.post_list, name='list'),

                            # Match: /blog/42/ (Path converters)
                            path('<int:id>/', views.post_detail, name='detail'),

                            # Match: /blog/slug-titre/
                            path('<slug:slug>/', views.post_by_slug, name='slug_detail'),
                            ]
                        

Function Based View (FBV)

Simple, explicite, idéal pour débuter ou pour de la logique complexe spécifique.

                            from django.shortcuts import render, get_object_or_404
                            from .models import Post

                            def post_detail(request, id):
                            # Logique métier
                            post = get_object_or_404(Post, pk=id)
                            context = {'post': post}
                            return render(request, 'blog/detail.html', context)
                        

Class Based View (CBV)

Puissant, concis, orienté objet. Idéal pour les CRUD standards.

                            from django.views.generic import DetailView
                            from .models import Post

                            class PostDetailView(DetailView):
                            model = Post
                            template_name = 'blog/detail.html'
                            context_object_name = 'post'
                            # Gère automatiquement le 404 et la requête
                        

1. Séparer les Settings

Au lieu d'un seul settings.py, créez un package.

                            config/
                            └── settings/
                            ├── __init__.py
                            ├── base.py   # Config commune (Apps, Auth...)
                            ├── dev.py    # Debug=True, Console Email
                            └── prod.py   # Debug=False, S3, Sentry
                        

Lancer avec : python manage.py runserver --settings=config.settings.dev

2. Le fichier .gitignore (Vital)

Ne committez jamais ces fichiers :

                            # Python
                            __pycache__/
                            *.py[cod]
                            venv/
                            env/

                            # Django
                            *.log
                            local_settings.py
                            db.sqlite3
                            media/

                            # Environment variables
                            .env
                        

Fichiers Statiques (CSS, JS, IMG du thème)

                            # URL publique (ex: /static/css/style.css)
                            STATIC_URL = 'static/'

                            # Où Django cherche les fichiers en DEV
                            STATICFILES_DIRS = [
                            BASE_DIR / 'static', 
                            ]

                            # Où Django RASSEMBLE les fichiers en PROD
                            # (via la commande "collectstatic")
                            STATIC_ROOT = BASE_DIR / 'staticfiles'
                        

Fichiers Media (Uploads Users)

                            # URL publique (ex: /media/avatars/user1.jpg)
                            MEDIA_URL = 'media/'

                            # Dossier physique de stockage
                            MEDIA_ROOT = BASE_DIR / 'media'
                        

Note: En production, Nginx servira directement STATIC_ROOT et MEDIA_ROOT.

Base de Données (DATABASES)

Django supporte officiellement PostgreSQL, MariaDB, MySQL, Oracle et SQLite.

Option A: SQLite (Dev)

                            DATABASES = {
                            'default': {
                            'ENGINE': 'django.db.backends.sqlite3',
                            'NAME': BASE_DIR / 'db.sqlite3',
                            }
                            }
                        

Option B: PostgreSQL (Prod/Recommandé)

                            DATABASES = {
                            'default': {
                            'ENGINE': 'django.db.backends.postgresql',
                            'NAME': 'ideo_db',
                            'USER': 'ideo_user',
                            'PASSWORD': os.environ.get('DB_PASS'),
                            'HOST': 'localhost',
                            'PORT': '5432',
                            }
                            }
                        

Internationalisation (I18N)

                            # Code langue par défaut (français)
                            LANGUAGE_CODE = 'fr-fr'

                            # Fuseau horaire (Stockage UTC en base, affichage local)
                            TIME_ZONE = 'Europe/Paris'

                            # Activer la traduction
                            USE_I18N = True

                            # Activer le support des timezones (Recommandé: True)
                            USE_TZ = True
                        

Si USE_TZ = True, Django stocke tout en UTC. La conversion vers 'Europe/Paris' se fait uniquement à l'affichage dans le template.

1. python-dotenv (Le Standard Simple)

Charge les variables d'un fichier .env dans os.environ.

                            # Installation
                            pip install python-dotenv

                            # Dans manage.py et wsgi.py (au tout début)
                            from dotenv import load_dotenv
                            load_dotenv() # Cherche .env à la racine

                            # Dans settings.py
                            import os
                            SECRET_KEY = os.getenv('SECRET_KEY')
                        

2. django-environ (Le "Douze Factor App")

Plus puissant : gère le typage (bool, int, list) et les schémas de BDD (DATABASE_URL).

                            # Installation
                            pip install django-environ

                            # Dans settings.py
                            import environ
                            env = environ.Env(
                            # Valeurs par défaut
                            DEBUG=(bool, False)
                            )
                            environ.Env.read_env(BASE_DIR / '.env')

                            DEBUG = env('DEBUG') # Convertit auto "True" en bool
                            # Parse l'URL postgres://user:pass@host:port/db
                            DATABASES = {'default': env.db()} 
                        

Comment lier les fichiers ?

Dans dev.py et prod.py, on importe tout depuis base.

                            # settings/dev.py
                            from .base import *

                            DEBUG = True
                            ALLOWED_HOSTS = ['localhost']

                            # Outils de dev uniquement
                            INSTALLED_APPS += ['debug_toolbar']
                            MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
                        

Comment lancer Django ?

Il faut spécifier quel fichier de settings utiliser.

                            # En développement
                            python manage.py runserver --settings=my_project.settings.dev

                            # En production (Gunicorn/WSGI)
                            export DJANGO_SETTINGS_MODULE=my_project.settings.prod
                            gunicorn my_project.wsgi:application
                        

1. Modèles Abstraits (DRY)

Ne répétez jamais created_at et updated_at dans chaque modèle. Créez un modèle parent.

                            # core/models.py
                            from django.db import models

                            class TimeStampedModel(models.Model):
                            """
                            Classe de base abstraite qui ajoute
                            automatiquement les champs de date.
                            """
                            created_at = models.DateTimeField(auto_now_add=True)
                            updated_at = models.DateTimeField(auto_now=True)
                            is_active = models.BooleanField(default=True)

                            class Meta:
                            abstract = True # Django ne créera pas de table pour ceci
                        

2. Mixins de Vues

Ajoutez des fonctionnalités communes à vos Vues.

                            # core/mixins.py
                            from django.contrib.auth.mixins import UserPassesTestMixin

                            class SuperUserRequiredMixin(UserPassesTestMixin):
                            def test_func(self):
                            return self.request.user.is_superuser
                        

3. Templates Globaux

Structure recommandée :

                            templates/
                            ├── base.html           # Squelette (Header/Footer)
                            ├── partials/           # Fragments (Navbar, Sidebar)
                            │   ├── navbar.html
                            │   └── sidebar.html
                            └── core/               # Pages génériques
                            ├── home.html
                            └── 404.html
                        

1. Custom User Model (OBLIGATOIRE)

Toujours faire ça avant la première migration !

                            # accounts/models.py
                            from django.contrib.auth.models import AbstractUser
                            from django.db import models

                            class User(AbstractUser):
                            # On ajoute nos champs spécifiques
                            avatar = models.ImageField(upload_to='avatars/', null=True, blank=True)
                            bio = models.TextField(max_length=500, blank=True)
                            is_verified = models.BooleanField(default=False)

                            def __str__(self):
                            return self.username
                        

N'oubliez pas AUTH_USER_MODEL = 'accounts.User' dans settings.py.

2. Vues d'Authentification

                            # accounts/urls.py
                            from django.urls import path
                            from django.contrib.auth import views as auth_views
                            from . import views

                            urlpatterns = [
                            path('login/', auth_views.LoginView.as_view(
                            template_name='accounts/login.html'
                            ), name='login'),

                            path('logout/', auth_views.LogoutView.as_view(), name='logout'),

                            path('register/', views.SignUpView.as_view(), name='register'),
                            ]
                        

1. La Vue Principale (Protégée)

                            # dashboard/views.py
                            from django.contrib.auth.decorators import login_required
                            from django.shortcuts import render
                            from core.models import Metric # Exemple

                            @login_required # Sécurité basique
                            def dashboard_home(request):
                            context = {
                            'user_count': 150,
                            'recent_activities': [],
                            'page_title': 'Tableau de bord'
                            }
                            return render(request, 'dashboard/home.html', context)
                        

2. Structure des Templates

Le dashboard a souvent un layout différent du site public (Sidebar vs Topbar).

                            templates/dashboard/
                            ├── base_dashboard.html  # Étend base.html mais ajoute la Sidebar
                            ├── home.html            # Contenu spécifique
                            └── profile/
                            └── edit.html
                        

3. Exemple de template

                            {% extends "dashboard/base_dashboard.html" %}

                            {% block content %}
                            

                                
Bienvenue 
                            
                            {% endblock %}
                        

1. Commandes de Gestion (Management Commands)

Permet de lancer des tâches via python manage.py ...

                            # tools/management/commands/cleanup_logs.py
                            from django.core.management.base import BaseCommand

                            class Command(BaseCommand):
                            help = 'Nettoie les vieux logs'

                            def handle(self, *args, **kwargs):
                            # Logique de nettoyage
                            self.stdout.write(self.style.SUCCESS('Logs nettoyés !'))
                        

Usage : python manage.py cleanup_logs

2. Template Tags personnalisés

Ajoutez des fonctions utilisables dans les templates HTML.

                            # tools/templatetags/ideo_extras.py
                            from django import template
                            import datetime

                            register = template.Library()

                            @register.filter(name='days_until')
                            def days_until(date):
                            delta = date - datetime.date.today()
                            return delta.days
                        

Usage HTML : {{ project.deadline|days_until }} jours restants

Exemple Standard

                            # urls.py
                            path('user/<str:username>/', views.profile),
                            path('archive/<int:year>/<int:month>/', views.archive),

                            # views.py
                            def profile(request, username): # username est un str
                            ...
                            def archive(request, year, month): # year est un int
                            ...
                        

Regex Complexes (re_path)

Pour des besoins très spécifiques (ex: ID hexadécimal de longueur fixe).

                            from django.urls import re_path

                            # Match IDs de 4 caractères alphanumériques
                            re_path(r'^sku/(?P<sku>[0-9a-f]{4})/$', views.sku_detail),
                        

Dans les Templates ({% url ... %})

                            Accueil

                            Voir

                            {% url 'shop:cart' as cart_url %}
                            {% if cart_url %}
                            Panier
                            {% endif %}
                        

Dans le Code Python (reverse)

                            from django.urls import reverse
                            from django.shortcuts import redirect

                            def my_view(request):
                            # 1. Générer l'URL en string
                            url = reverse('blog:detail', kwargs={'pk': 42})
                            # Résultat : "/blog/articles/42/"

                            # 2. Rediriger directement
                            return redirect('blog:list')

                            # 3. Dans les tests
                            response = self.client.get(reverse('home'))
                        

Service systemd (classique)

# /etc/systemd/system/gunicorn_ideo.service
                            [Unit]
                            Description=Gunicorn daemon for IDEO‑Lab
                            After=network.target

                            [Service]
                            User=www-data
                            Group=www-data
                            WorkingDirectory=/opt/ideo-lab
                            EnvironmentFile=/opt/ideo-lab/.env
                            ExecStart=/opt/ideo-lab/venv/bin/gunicorn   --workers 4   --threads 2   --timeout 120   --bind unix:/run/gunicorn_ideo.sock   ideolab_site.wsgi:application
                            Restart=always

                            [Install]
                            WantedBy=multi-user.target

Service socket‑based

# /etc/systemd/system/gunicorn_ideo.socket
                            [Unit]
                            Description=Gunicorn IDEO‑Lab socket

                            [Socket]
                            ListenStream=/run/gunicorn_ideo.sock

                            [Install]
                            WantedBy=sockets.target

Commandes

sudo systemctl daemon-reload
                            sudo systemctl enable gunicorn_ideo
                            sudo systemctl start gunicorn_ideo
                            sudo systemctl status gunicorn_ideo

Si le socket n'existe pas → vérifier les permissions /run, l'utilisateur systemd et le chemin du venv.

Optimisation workers

# règle générale
                            workers = (2 * nombre_coeurs) + 1
                            threads = 2
                            timeout = 120

Exemple : serveur 4 vCPU → (2×4)+1 = 9 workers. Vérifier la RAM (100‑120 Mo / worker).

Tuning chemin Python

ExecStart=/opt/ideo-lab/venv/bin/gunicorn ...

Toujours pointer vers le binaire gunicorn du venv du projet.

Logging avancé

ExecStart=/opt/ideo-lab/venv/bin/gunicorn   --access-logfile /var/log/gunicorn/access.log   --error-logfile /var/log/gunicorn/error.log   ideolab_site.wsgi:application

Les logs Gunicorn peuvent être agrégés dans journald ou envoyés vers Loki/Promtail.