Création d’un projet¶

Si c’est la première fois que vous utilisez Django, vous devrez vous occuper de quelques éléments de configuration initiaux. Plus précisément, vous devrez lancer la génération automatique de code qui mettra en place un projet Django – un ensemble de règlages particuliers à une instance de Django, qui comprendra la configuration de la base de données, des options spécifiques à Django et d’autres propres à l’application.

Depuis un terminal en ligne de commande, cd dans un répertoire dans lequel vous souhaitez conserver votre code, puis lancez la commande django-admin.py startproject mysite. Cela va créer un répertoire mysite dans le répertoire courant.

django-admin.py (en) doit se trouver sur le chemin de recherche de votre système si vous avez installé Django en utilisant python setup.py. S’il n’est pas sur ce chemin, vous le trouverez dans site-packages/django/bin, où `site-packages` est un répertoire de votre installation Python. Dans ce cas vous devriez envisager de faire un lien symbolique de django-admin.py (en) vers un répertoire de votre chemin de recherche système, comme /usr/local/bin.

Voyons ce que startproject a créé :

mysite/
    __init__.py
    manage.py
    settings.py
    urls.py

Ces fichiers sont :

• __init__.py: Un fichier vide qui indique à Python que ce répertoire doit être considéré comme un package. (Lisez information sur les packages (en) dans la documentation officielle de Python si vous êtes un débutant de ce langage).
• manage.py: Un utilitaire en ligne de commande qui vous permet d'interagir avec ce projet Django de différente façons. Vous pouvez lire les détails sur manage.py dans : django-admin.py et manage.py (en).
• settings.py: Règlages et configuration de ce projet Django. Un survol des paramètres (en) vous en apprendra plus sur le fonctionnement des règlages.
• urls.py: Les déclarations des URLs de ce projet Django, une sorte de "table des matières" de votre site Django. Vous pouvez en lire plus sur les URLs dans URLconfs (en).

Validating models...
0 errors found.

Django version 1.1, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

python manage.py runserver 8080

python manage.py runserver 0.0.0.0:8000

python manage.py syncdb

Création des modèles¶

Maintenant que votre environnement -- un "projet" -- est en place, vous êtes prêt à commencer à travailler.

Chaque application que vous écrivez dans Django est en fait un package Python, quelquepart sur votre chemin de recherche Python (en), qui respecte certaines conventions. Django est livré avec un utilitaire qui génère automatiquement la structure de répertoire de base d'une application, ce qui vous permet de vous concentrer sur l'écriture du code, plutôt que sur la création de répertoires.

Dans ce tutoriel, nous allons créer notre application de sondage dans le répertoire mysite, par souci de simplicité. En conséquence, l'application sera liée au projet -- c'est à dire, le code Python dans l'application de sondage sera référencé par mysite.polls. Plus loin dans ce tutoriel, nous discuterons du découplage entre projet et application.

Pour créer votre application, assurez-vous d'être dans le répertoire mysite et entrez cette commande :

python manage.py startapp polls

Cela va créer un répertoire polls, qui se présente de la façon suivante :

polls/
    __init__.py
    models.py
    views.py

Cette structure de répertoire accueillera l'application de sondage.

La première étape dans l'écriture d'une application Web utilisant une base de données dans Django est la définition de vos modèles -- essentiellement, votre schéma de base de données, avec quelques métadonnées supplémentaires.

Dans notre application de sondage simple, nous allons créer deux modèles : un pour les sondages (polls) et un pour les possibilités de choix (choices). Un sondage possède une question et une date de mise en ligne. Une possibilité de choix a deux champs : le texte représentant le choix, et le décompte des votes. Chaque choix est associé à un sondage.

Ces concepts sont représentés par de simples classes Python. Éditez le fichier polls/models.py de façon à ce qu'il ressemble à ceci :

from django.db import models

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

Le code est trivial. Chaque modèle est représenté par une classe qui hérite de Model. Chaque modèle possède des variables de classe, chacune d'entre elles représentant un champ de la base de données pour ce modèle.

Chaque champ est représenté par une instance d'une classe Field -- par exemple, CharField pour les champs de type caractère, et DateTimeField pour les champs date et heure. Cela indique à Django quel type de données contient chaque champ.

Le nom de chaque instance de Field (par exemple, question ou pub_date) est le nom du champ en interne. Vous l'utiliserez dans votre code Python, et votre base de données l'utilisera comme nom de colonne.

Vous pouvez utilisez le premier argument de position (facultatif) d'un Field pour donner un nom plus lisible au champ. C'est utilisé par le système d'introspection de Django, et aussi pour la documentation. Si cet argument est absent, Django utilisera le nom du champ en interne. Dans l'exemple, nous n'avons défini qu'un seul nom plus lisible, pour Poll.pub_date. Pour tous les autres champs, nous avons considéré que le nom interne était suffisament lisible.

Certaines classes Field ont des attributs obligatoires. La classe CharField, par exemple, a besoin d'un attribut max_length. Ce n'est pas seulement utilisé dans le schéma de base de données, mais également pour valider les champs, comme nous allons voir prochainement.

Finalement, notez que nous définissons une relation, en utilisant ForeignKey. Cela indique à Django que chaque vote (Choice) n'est relié qu'à un seul sondage (Poll). Django propose tous les modèles classiques de relations : plusieurs-à-un, plusieurs-à-plusieurs, un-à-un.

Activation des modèles¶

Ce petit morceau de code décrivant les modèles fournit beaucoup d'information à Django. Avec, il est capable de :

• Créer un schéma de base de données (les instructions CREATE TABLE) pour cette application.
• Créer une API Python d'accès aux bases de données pour accéder aux objets sondages (Poll) et votes (Choices).

Mais il faut d'abord indiquer à notre projet que l'application de sondages polls est installée.

Éditez encore une fois le fichier settings.py, et modifiez le réglage INSTALLED_APPS pour qu'il contienne la chaîne de caractéres 'mysite.polls'. Il devrait donc ressembler à ceci :

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'mysite.polls'
)

Maintenant, Django sait que mysite doit inclure l'application polls. Exécutons une autre commande :

python manage.py sql polls

Vous devriez voir quelquechose de similaire à ceci (les instructions SQL CREATE TABLE pour l'application de sondage) :

BEGIN;
CREATE TABLE "polls_poll" (
    "id" serial NOT NULL PRIMARY KEY,
    "question" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
    "choice" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
COMMIT;

Notez les points suivants :

• Ce que vous verrez dépendra de la base de données que vous utilisez.
• Les noms de tables sont générés automatiquement en combinant le nom de l'application (polls) et le nom du modèle en minuscules -- poll et choice (vous pouvez modifier ce comportement).
• Les clés primaires (IDs) sont ajoutées automatiquement (vous pouvez modifier ceci également).
• Par convention, Django ajoute "_id" au nom de champ de la clé étrangère. Et oui, vous pouvez aussi changer ça.
• La relation de clé étrangère est rendue explicite par une instruction REFERENCES.
• Ce que vous voyez est adapté à la base de données que vous utilisez. Ainsi, des champs spécifiques à celle-ci comme auto_increment (MySQL), serial (PostgreSQL) ou integer primary key (SQLite) sont gérés pour vous automatiquement. La même chose est utilisée pour les apostrophes autour des noms de champs -- par exemple, en utiliser des simples ou des doubles. L'auteur de ce tutoriel utilise PostgreSQL, donc la sortie donnée en exemple correspond à la syntaxe de PostgreSQL.
• La commande sql n'exécute pas ces instructions dans votre base de données - elle se contente de l'afficher à l'écran de façon à vous permettre de voir ce que Django pense nécessaire. Si vous le voulez, vous pourriez copier et coller cette sortie dans le shell de votre client de base de données. Toutefois, comme nous allons le voir bientôt, Django fournit un moyen plus facile d'envoyer ces commandes à la base de données.

Si cela vous intéresse, vous pouvez aussi utiliser les commandes suivantes :

• python manage.py validate -- Vérifie qu'il n'y a pas d'erreurs dans vos modèles.
• python manage.py sqlcustom polls -- Affiche toutes les instructions SQL spécifiques (en) (comme des modifications de table ou des contraintes particulières) qui sont définies pour l'application.
• python manage.py sqlclear polls -- Affiche les instructions DROP TABLE nécessaires pour cette application, compte tenu des tables qui existent déjà dans votre base de données (s'il y en a).
• python manage.py sqlindexes polls -- Affiche les instructions CREATE INDEX pour cette application.
• python manage.py sqlall polls -- Une combinaison des instructions SQL des commandes sql, sqlcustom et sqlindexes.

L'examen de ce qu'affichent ces commandes peut vous aider à comprendre ce qui se passe en coulisses.

Maintenant, exécutez la commande syncdb pour créer les modèles dans votre base de données :

python manage.py syncdb

La commande syncdb exécute les instructions sql de 'sqlall' dans votre base de données, pour toutes les applications de INSTALLED_APPS qui n'existent pas encore dans celle-ci. Cela crée toutes les tables, les données initiales et les index pour toutes les applications que vous avez ajoutées à votre projet depuis la dernière fois que vous avez fait un 'syncdb'. syncdb peut être appellée aussi souvent que vous le souhaitez, et ne fera que créer les tables qui n'existent pas encore.

Lisez la documentation de django-admin.py (en) pour avoir toutes les informations sur ce que manage.py peut faire.

Jouer avec l'interface de programmation (API)¶

Maintenant, utilisons un shell interactif Python pour jouer avec l'API que Django met à votre disposition. Pour lancer un shell Python, utilisez cette commande :

python manage.py shell

Nous utilisons celle-ci au lieu de simplement taper "python", parce que manage.py met en place l'environnement du projet pour vous. "Mettre en place l'environnement" signifie deux choses :

• Mettre mysite dans sys.path. Pour des raisons de souplesse, plusieurs parties de Django se réfèrent aux projets dans la notation classique de Python, en utilisant des points comme séparateurs dans les chemins (par exemple, 'mysite.polls.models'). Pour que cela fonctionne, le package mysite doit être dans le sys.path.

  On a déjà vu un exemple de ceci : le réglage INSTALLED_APPS est une liste de packages dans cette notation avec les points.

• Renseigner la variable d'environnement DJANGO_SETTINGS_MODULE. Elle indique à Django le chemin de votre fichier settings.py.

Une fois dans le shell, explorez l'API de base de données (en) :

>>> from mysite.polls.models import Poll, Choice # Importation des classes de modèles que nous venons d'écrire.

# Il n'existe pas encore de sondage.
>>> Poll.objects.all()
[]

# Création d'un nouveau sondage.
>>> import datetime
>>> p = Poll(question="Quoi de neuf ?", pub_date=datetime.datetime.now())

# Sauvegarde de l'objet dans la base de donnéees. Vous devez appeler save()
explicitement.
>>> p.save()

# Maintenant, l'objet a une ID. Notez que le retour peut être "1L" au lieu
# de 1, suivant la base de données que vous utilisez. Ce n'est rien, cela
# signifie simplement que votre moteur de base de données renvoie les
# entiers à Python sous la forme d'entiers longs.
>>> p.id
1

# Accèdez aux colonnes de la base de données par des attributs Python.
>>> p.question
"Quoi de neuf ?"
>>> p.pub_date
datetime.datetime(2007, 7, 15, 12, 00, 53)

# Modifiez les valeurs en changeant les attributs, puis en appelant save().
>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
>>> p.save()

# objects.all() affiche tous les sondages de la base de données.
>>> Poll.objects.all()
[<Poll: Poll object>]

Une seconde. <Poll: Poll object> n'est, à l'évidence, pas une représentation de cet objet très utile. On va arranger cela en éditant le modèle des sondages (dans le fichier polls/models.py) et en ajoutant une méthode __unicode__() à Poll et à Choice :

class Poll(models.Model):
    # ...
    def __unicode__(self):
        return self.question

class Choice(models.Model):
    # ...
    def __unicode__(self):
        return self.choice

Il est important d'ajouter des méthodes __unicode__() à vos modèles, non seulement parce que c'est plus pratique lorsque vous utilisez le shell interactif, mais aussi parce que la représentation des objets est très utilisée dans l'interface d'administration automatique de Django.

Notez que ce sont des méthodes Python classiques. Ajoutons une méthode personnalisée, juste pour la démonstration :

import datetime
# ...
class Poll(models.Model):
    # ...
    def was_published_today(self):
        return self.pub_date.date() == datetime.date.today()

Notez l'ajout de import datetime pour référencer le module datetime standard de Python.

Retournons au shell interactif de Python en exécutant à nouveau python manage.py shell :

>>> from mysite.polls.models import Poll, Choice

# Assurons-nous que notre ajout __unicode__() fonctionne.
>>> Poll.objects.all()
[<Poll: Quoi de neuf ?>]

# Django fournit une API de recherche dans la base de donnée très complète
# et entièrement pilotée par les mots-clés fournis en argument.
>>> Poll.objects.filter(id=1)
[<Poll: Quoi de neuf ?>]
>>> Poll.objects.filter(question__startswith='Quoi')
[<Poll: Quoi de neuf ?>]

# Récupérer le sondage dont l'année est 2007. Évidemment, si vous suivez ce
# tutoriel une année différente, adaptez-vous...
>>> Poll.objects.get(pub_date__year=2007)
<Poll: Quoi de neuf ?>

>>> Poll.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Poll matching query does not exist.

# La recherche sur la clé primaire est le cas le plus fréquent. Django
# fournit donc un raccourci pour les recherches exactes sur celle-ci.
# Ce qui suit est identique à Poll.objects.get(id=1)
>>> Poll.objects.get(pk=1)
<Poll: Quoi de neuf ?>

# Voyons si notre méthode personnalisée fonctionne.
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False

# On ajoute au sondage des possibilités de choix. L'appel à create construit
# un nouvel objet choix, lance l'instruction INSERT, ajoute le choix à
# l'ensemble des choix possibles et renvoie le nouvel objet.
>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.create(choice='Rien', votes=0)
<Choice: Rien>
>>> p.choice_set.create(choice='Le ciel', votes=0)
<Choice: Le ciel>
>>> c = p.choice_set.create(choice='Encore en train de coder', votes=0)

# Les objets choix ont une API pour accèder à l'objet sondage auquel ils
# sont reliés
>>> c.poll
<Poll: Quoi de neuf ?>

# Et réciproquement : les objets sondages ont accès aux objets choix.
>>> p.choice_set.all()
[<Choice: Rien>, <Choice: Le ciel>, <Choice: Encore en train de coder>]
>>> p.choice_set.count()
3

# L'API suit les relations automatiquement, aussi loin que nécessaire.
# Utilisez les doubles tirets de soulignement pour séparer les relations.
# Cela fonctionne avec la profondeur que vous souhaitez, il n'y a pas de
# limite.
# Trouver tous les choix pour tout sondage dont la pub_date est 2007.
>>> Choice.objects.filter(poll__pub_date__year=2007)
[<Choice: Rien>, <Choice: Le ciel>, <Choice: Encore en train de coder>]

# Supprimons un des choix. Utilisez delete() pour ça.
>>> c = p.choice_set.filter(choice__startswith='Encore en')
>>> c.delete()

Pour tous les détails sur l'API de base de données, voyez la référence de l'API de base de données (en).

Lorsque vous êtes familiarisés avec l'API, lisez la partie 2 de ce tutoriel pour faire fonctionner l'interface d'administration automatique de Django.