Struttura del Progetto

Comprendere la struttura di un progetto Django è fondamentale per orientarsi nel codice e sapere dove inserire ogni componente. Analizziamo nel dettaglio ciascun file generato da django-admin startproject.

Panoramica della Struttura

Dopo aver creato un progetto chiamato miosito, la struttura è la seguente:

miosito/
    manage.py
    miosito/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

manage.py

manage.py è lo script di gestione del progetto. Viene posizionato nella directory radice e funge da interfaccia a riga di comando per tutte le operazioni Django.

#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys

def main():
    """Run administrative tasks."""
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'miosito.settings')
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django."
        ) from exc
    execute_from_command_line(sys.argv)

if __name__ == '__main__':
    main()

La variabile DJANGO_SETTINGS_MODULE indica quale file di configurazione usare. Non è necessario modificare questo file, ma è utile sapere che collega il progetto al modulo settings.

init.py

Questo file vuoto indica a Python che la directory miosito/ è un pacchetto Python importabile. Senza questo file, Python non riconoscerebbe la directory come modulo.

# Solitamente vuoto, ma può contenere codice di inizializzazione

settings.py

Il file settings.py è il cuore della configurazione di Django. Contiene tutte le impostazioni del progetto:

from pathlib import Path

# Percorso base del progetto
BASE_DIR = Path(__file__).resolve().parent.parent

# Chiave segreta per le operazioni crittografiche
SECRET_KEY = 'django-insecure-...'

# Modalità di debug (True solo in sviluppo)
DEBUG = True

# Host consentiti in produzione
ALLOWED_HOSTS = []

# Applicazioni installate
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

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

Questo file verrà approfondito in un capitolo dedicato alla configurazione.

urls.py

Il file urls.py del progetto definisce la mappa delle URL principali dell’applicazione. Funziona come una tabella di routing che associa percorsi URL a views specifiche:

from django.contrib import admin
from django.urls import path

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

# Esempio con URL aggiuntive
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('blog/', include('blog.urls')),
    path('api/', include('api.urls')),
]

Ogni app Django avrà tipicamente il proprio file urls.py che viene incluso nel file principale tramite include().

wsgi.py

WSGI (Web Server Gateway Interface) è lo standard Python per la comunicazione tra server web e applicazioni. Questo file è il punto d’ingresso per il deployment con server tradizionali come Gunicorn o uWSGI:

import os
from django.core.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'miosito.settings')

application = get_wsgi_application()

L’oggetto application viene utilizzato dal server web per gestire le richieste HTTP in modo sincrono.

asgi.py

ASGI (Asynchronous Server Gateway Interface) è l’evoluzione asincrona di WSGI. Questo file supporta WebSocket, HTTP/2 e operazioni asincrone con server come Daphne o Uvicorn:

import os
from django.core.asgi import get_asgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'miosito.settings')

application = get_asgi_application()

Django 5.x offre un supporto migliorato per le views asincrone, rendendo ASGI particolarmente utile per applicazioni che richiedono comunicazione in tempo reale.

Struttura Completa con App

Un progetto Django reale include anche una o più app. Ecco come appare la struttura con un’app blog:

miosito/
    manage.py
    db.sqlite3
    miosito/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    blog/
        __init__.py
        admin.py
        apps.py
        models.py
        views.py
        urls.py
        tests.py
        migrations/
            __init__.py
    templates/
    static/

Conclusione

Ogni file nella struttura di un progetto Django ha un ruolo ben definito. Conoscere la funzione di ciascun componente ti permette di navigare il codice con sicurezza e di organizzare il progetto in modo pulito e manutenibile. Nel prossimo capitolo vedremo come creare un’app Django.