Gilles Fabio

RVM for Pythonistas, virtualenv for Rubyists

2011-03-01T00:00:00.000Z

You are or have been a Pythonista? You are or were in love with virtualenv, virtualenwrapper or Buildout? Now you do some Ruby you are looking for the same wonderful tools? You should take a look at RVM or Ruby Version Manager.

Oh, well. You are or have been a Rubyist? You are or were in love with RVM? Now you do some Python you are looking for the same wonderful tool? You should take a look at virtualenv (with virtualenvwrapper).

Installation

I am a Pythonista

First, make sure pip is installed on your system.

Then, in your terminal:

sudo pip install virtualenvwrapper

Create the directory which will contain your virtual environments. For example, $HOME/.virtualenvs:

mkdir ~/.virtualenvs

Edit your $HOME/bash_profile file and add these lines:

export WORKON_HOME=$HOME/.virtualenvs
export PIP_VIRTUALENV_BASE=$WORKON_HOME
export PIP_RESPECT_VIRTUALENV=true

Source it:

source ~/.bash_profile

Troubleshooting? Check the documentation.

I am a Rubyist

First, make sure Git is installed on your system.

Then, in your terminal:

bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )

Edit your $HOME/.bash_profile file and add this line at the very end:

[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm"

Source it:

source ~/.rvm/scripts/rvm

Troubleshooting? Check the documentation.

Managing multiple interpreters

I am a Pythonista

You have to install the different Python versions on your system (via your package manager). When you will create a virtual environment with virtualenv, you will pass the interpreter path of the desired Python version as -p argument of mkvirtualenv command.

Example:

mkvirtualenv -p /opt/local/bin/python3 myproject

I am a Rubyist

RVM compiles and installs the desired Ruby interpreter and Ruby version in the current user directory. It supports MRI/YARV, Rubinius, JRuby, Ruby Enterprise Edition, MagLev, IronRuby, MacRuby and GoRuby. This can be achieved in a single one command.

To list the available interpreters and versions to which it may install:

rvm list known

Let’s install the original implementation in version 1.8.7 and 1.9.2 (make sure Subversion is installed):

rvm install 1.8.7
rvm install 1.9.2

This takes some compilation time and you’ve done.

To list the installed Ruby versions:

rvm list rubies

To switch between interpreters:

rvm use RUBY_VERSION

For example, switching to 1.8.2:

rvm use 1.8.2

Or switching to 1.9.2:

rvm use 1.9.2

To set up the default interpreter:

rvm --default use RUBY_VERSION

For example, if you want to use Ruby 1.9.2 as default interpreter:

rvm --default use 1.9.2

To switch back to your default system interpreter:

rvm use system

This is very powerful. Check the documentation to know more about available commands and options.

Managing multiple environments

I am a Pythonista

Generally, with virtualenv, you create one environment per project and/or project stage (development, testing, staging, production, etc). This can be accomplished with the mkvirtualenv command:

mkvirtualenv --no-site-packages PROJECT_NAME

For example, if my project name is “superdjango”:

mkvirtualenv --no-site-packages superdjango

The --no-site-packages option removes the standard site-packages directory from the environment sys.path. I recommend to use this option if you want more isolation. It avoids dealing with system packages conflicts.

As seen above, you can specify the Python version with the -p option:

mkvirtualenv --no-site-packages -p /opt/local/bin/python3 PROJECT_NAME

If you added export PIP_RESPECT_VIRTUALENV=true in your $HOME/.bash_profile file, when your environment is active, pip auto-installs packages in this environment. You do not have to prefix it with any sudo command or have to pass it any option. Just this:

pip install PACKAGE

Example:

pip install Django

Otherwise, you need to use the -E option:

pip install -E ENVIRONMENT_NAME PACKAGE

Example:

pip install -E superdjango Django

To list all available environments, use the workon command:

workon

To activate an environment:

workon ENVIRONMENT_NAME

Example:

workon superdjango

The first time you create a virtual environment with the mkvirtualenv command, you will auto-switch to this environment instantly (the environment name prefixes your session prompt).

To deactivate the current environment, use the deactivate command:

deactivate

To delete a virtual environment:

rmvirtualenv ENVIRONMENT_NAME

Example:

rmvirtualenv superdjango

I am a Rubyist

Where virtualenv has “environments”, RVM has “gemsets”. Interpreters and packages are all separated and self-contained from system and from each other. Creating a virtual environment with virtualenv is creating a gemset with RVM. Generally, you create one gemset per project and/or project stage (development, testing, staging, production, etc). This can be done with this command:

rvm use RUBY_VERSION@GEMSET_NAME --create

Example:

rvm use 1.9.2@myproject --create

This is equivalent to:

rvm use 1.9.2
rvm gemset create myproject
rvm gemset use myproject

When your gemset is active, using gem install command will install packages directly in your gemset. So you can use:

gem install PACKAGE

This will install the given package in your current active gemset directory.

To know the path of this directory, you can use the gemdir RVM command:

rvm gemdir

Deleting a gemset is simple as:

rvm gemset delete GEMSET_NAME

Example:

rvm gemset delete myproject

To empty a gemset (removing all installed gems):

rvm gemset empty GEMSET_NAME

Example:

rvm gemset empty myproject

Managing project dependencies

I am a Pythonista

Managing project dependencies with Pip and virtualenv is crazy simple. You just have to create a text file containing package names (and optionally package versions) and give this file to Pip via the -r option. Everything is clearly well explained in the documentation.

To give you an example, for my “superdjango” project, I create a requirements.txt file to start my project with Django 1.2.x and South support. This requirements.txt file looks like this:

Django >= 1.2
South == 0.7.2

If I don’t already created my environment, I create it right now:

mkvirtualenv --no-site-packages superdjango

And I install project dependencies:

pip install -r /path/to/my/requirements.txt

This will install the latest Django 1.2 version and South 0.7.2 into my virtual environment.

I am a Rubyist

Managing project dependencies with RVM, RubyGem and Bundler is crazy simple too.

Where Pip has “requirements” files, Bundler has “Gemfile” files.

First, you need to create a dedicated gemset for the project:

rvm use RUBY_VERSION@GEMSET_NAME --create

Example:

rvm use 1.9.2@myproject --create

This is the same of these commands:

rvm use 1.9.2
rvm gemset create myproject
rvm gemset use myproject

I install Bundler into my gemset:

gem install bundler

I create a directory for my project:

cd /path/to/my/workspace
mkdir myproject

I go in the directory and create an empty Gemfile file:

cd myproject
bundle init

Then I edit the Gemfile file and add my dependencies:

source "http://rubygems.org"

gem "sinatra", "~> 0.9.0"
gem "rack-cache"
gem "rack-bug"

Now, I install dependencies in the current gemset:

bundle install

That’s all. Everything is clearly well explained in the documentation.

Conclusion

RVM and virtualenv (coupled with virtualenvwrapper) are both powerful tools which considerably improve your productivity and reduce headache fighting with dependencies. Today, I can’t even imagine living without. I didn’t cover Buildout, the Python alternative to virtualenv, because it works a different way but it’s a wonderful tool you should give it a try. These articles, written by Jacob Kaplan-Moss, are must-read:

Installing Symfony2 on Mac OS X

2010-12-17T00:00:00.000Z

Prerequisites

Symfony2 requires at least PHP 5.3.2. If your Mac is not ready, you can follow these instructions.

And make sure Git is installed on your system.

Sandbox and generators

There are three ways to get the initial structure of a new Symfony2 project:

Currently, the recommended way is the Sandbox (Symfony Bootstrapper is still in development, undocumented and can be buggy).

Symfony2Project is an alternative created by Bertrand Zuchuat. You should give it a try.

Creating a new project with the Sandbox

To get the Sandbox, go in your development workspace and grab the source:

cd /path/to/your/workspace
git clone https://github.com/symfony/symfony-sandbox.git

For example, my development workspace is $HOME/Code/PHP:

cd $HOME/Code/PHP
git clone https://github.com/symfony/symfony-sandbox.git

Create a copy of the symfony-sandbox folder with the name of your project:

cp -r symfony-sandbox project

For example, I name my project sf2project:

cp -r symfony-sandbox sf2project

Fix some permissions for the cache and logs folders:

cd project
chmod -R 777 app/cache
chmod -R 777 app/logs

With my sf2project:

cd sf2project
chmod -R 777 app/cache
chmod -R 777 app/logs

Create a VirtualHost (instructions) with a similar configuration:

NameVirtualHost *:80


    DocumentRoot "/absolute/path/to/your/project/web"
    ServerName project.localhost
    
        Options Indexes FollowSymlinks
        AllowOverride All
        Order allow,deny
        Allow from all
    
    ErrorLog "logs/project-error_log"
    CustomLog "logs/project-access_log" common

Example of my sf2project:

NameVirtualHost *:80


    DocumentRoot "/Users/gilles/Code/PHP/sf2project/web"
    ServerName sf2project.localhost
    
        Options Indexes FollowSymlinks
        AllowOverride All
        Order allow,deny
        Allow from all
    
    ErrorLog "logs/sf2project-error_log"
    CustomLog "logs/sf2project-access_log" common

Restart the server.

Open your browser and go to the URL: http://project.localhost. You should see the “Congratulations” page.

To check if everything is correctly installed and configured, go the URL: http://project.localhost/check.php. If you see green everywhere, you won. Otherwise, fix any problem that it finds.

Getting PHP 5.3 on Mac OS X

2010-12-17T00:00:00.000Z

The default Mac OS X stack

If you are running Mac OS X Snow Leopard, you should already have PHP 5.3.3 installed on your system.

To be sure, open Applications » Utilities » Terminal and check it yourself:

/usr/bin/php -v

You just have to turn on the Apple’s Personal Web Sharing in the System Preferences and place your projects in $HOME/Sites folder.

But you will need to install MySQL or any SGBDR/NoSQL Manager by hand (getting the tarballs and fighting with dependencies, configuration and compilation stuff). Installing Apache/PHP modules and libraries can also be a pain. Personally, I rather prefer the MAMP solution or using package managers such as MacPorts or Homebrew. To my point of view, the default Mac OS X stack is only suitable for simple needs.

MAMP: Drag, drop, done.

This is the quick way to get a ready-to-go PHP 5.3 environment on a Mac.

Download MAMP, drag and drop the MAMP folder into the Applications folder and that’s all.

You can easily switch between two major PHP versions (PHP 5.2 or PHP 5.3) in a single click thanks to the Applications » MAMP » MAMP application. As the default MAMP PHP version is 5.2, launch the MAMP application, go in the preferences pane and change the current PHP version.

You now have to override your system PATH.

Edit your $HOME/.profile or $HOME/.bash_profile file, then add these lines at the end:

export PATH=/Applications/MAMP/bin/php5.3/bin:$PATH

Source it:

source $HOME/.profile

Check your PHP version:

php -v

This command should return PHP 5.3.2 (cli) (or above).

Cook your own stack with MacPorts

MacPorts is the most popular package manager for Mac OS X. Homebrew is also very powerful. With MacPorts, you can install your own stack with a high level of configuration and optimization. Everything is compiled from source and MacPorts manages itself all dependencies. Obviously, this takes time but it’s worth it. Let’s go?

Turn off Apple’s Personal Web Sharing in the System Preferences.

Install MacPorts.

Open a terminal (Applications » Utilities » Terminal).

Update the ports tree:

sudo port -d selfupdate

Install Apache2:

sudo port install apache2

Activate Apache2 to start it automatically at the boot:

sudo port load apache2

Go in your browser and enter the URL: http://localhost. You should see “It works!”.

Install MySQL:

sudo port install mysql5-server

Set up the “mysql” database:

sudo -u _mysql mysql_install_db5
sudo chown -R mysql:mysql /opt/local/var/db/mysql5/
sudo chown -R mysql:mysql /opt/local/var/run/mysql5/
sudo chown -R mysql:mysql /opt/local/var/log/mysql5/

Activate MySQL to start it automatically at the boot:

sudo port load mysql5-server

Set the MySQL’s root password (the current one is empty):

mysqladmin5 -u root -p password

Try to log you as root:

mysql5 -u root -p

Then exit the session:

mysql> exit;

Secure the configuration:

/opt/local/bin/mysql_secure_installation5

Install PHP:

sudo port install php5 +apache2 +pear
sudo port install php5-mysql php5-sqlite php5-xdebug php5-mbstring php5-iconv \
php5-posix php5-apc

cd /opt/local/apache2/modules
sudo /opt/local/apache2/bin/apxs -a -e -n "php5" libphp5.so

Set up the PHP configuration file:

cd /opt/local/etc/php5
sudo cp php.ini-development php.ini

Set up the timezone in /opt/local/etc/php5/php.ini:

[Date]
; Defines the default timezone used by the date functions
; http://php.net/date.timezone
date.timezone = "Europe/Paris"

Set up the MySQL default socket:

sudo -i
cd /opt/local/etc/php5
cp php.ini php.ini.bak
defSock=`/opt/local/bin/mysql_config5 --socket`
cat php.ini | sed \
  -e "s#pdo_mysql\.default_socket.*#pdo_mysql\.default_socket=${defSock}#" \
  -e "s#mysql\.default_socket.*#mysql\.default_socket=${defSock}#" \
  -e "s#mysqli\.default_socket.*#mysqli\.default_socket=${defSock}#" > tmp.ini
grep default_socket tmp.ini
mv tmp.ini php.ini
rm php.ini.bak
exit

Edit /opt/local/apache2/conf/httpd.conf file.

Find these lines:


    DirectoryIndex index.html

Then, add index.php:


    DirectoryIndex index.php index.html

At the end of the file, add this line:

Include conf/extra/mod_php.conf

Restart Apache2:

sudo /opt/local/apache2/bin/apachectl -k restart

Done.

Adding a VirtualHost

For a MacPorts configuration, edit /opt/local/apache2/conf/httpd.conf and uncomment this line:

Include conf/extra/httpd-vhosts.conf

Then edit /opt/local/apache2/conf/extra/httpd-vhosts.conf.

Remove dummy examples and replace them with your own configuration:

NameVirtualHost *:80


    DocumentRoot "/absolute/path/to/your/project"
    ServerName project.localhost
    
        Options Indexes FollowSymlinks
        AllowOverride All
        Order allow,deny
        Allow from all
    
    ErrorLog "logs/project-error_log"
    CustomLog "logs/project-access_log" common

Restart Apache2:

sudo /opt/local/apache2/bin/apachectl -k restart

For a MAMP configuration, add your VirtualHost at the end of Applications/MAMP/conf/httpd.conf file, then restart the server.

Don’t forget to add your host in /private/etc/hosts:

127.0.0.1    localhost project.localhost

In the folder of your project, create a phpinfo.php file:

Now, open your browser and go to http://project.localhost/phpinfo.php.

You should see the PHP Info page.

Python et les décorateurs

2010-12-16T00:00:00.000Z

Introduction

Vous débutez en programmation Python ? Python vous intéresse ? Vous avez certainement déjà entendu parler des “décorateurs”. C’est une fonctionnalité très utilisée dans le monde Python. Ils permettent d’écrire du code concis, lisible et non-répétitif.

Concrètement, un décorateur est un callable qui prend pour argument un callable et qui retourne une copie de ce même callable en le “décorant”, c’est-à-dire en effectuant un pré-traitement et/ou un post-traitement sur celui-ci. Dans le jargon, on parle souvent de wrapping (on enveloppe, on saupoudre, on apporte un “plus”, on décore).

Si vous connaissez un peu le framework web Django, vous avez peut-être déjà manipulé des décorateurs, notamment pour la gestion de l’authentification. Pour protéger les vues, il suffit de les décorer avec les décorateurs @login_required ou @permission_required.

Un exemple :

@login_required
def protected_view(request):
    ...

Dans cet exemple, la vue protected_view est automatiquement protégée. Si vous n’êtes pas un utilisateur enregistré et connecté, vous serez redirigé vers le formulaire d’authentification, puisque le décorateur @login_required a ajouté son grain de sel pour que nous écrivions le moins de code possible.

Le micro-framework web Bottle utilise essentiellement cette fonctionnalité du langage.

Un exemple :

@route('/hello/:names')
@view('hello')
def hello(names):
   names = names.split(',')
   return dict(title='Hello World', names=names)

Ici, le décorateur @route se charge de définir une route pour cette vue et le décorateur @view se charge de charger le template hello.tpl et d’y injecter les variables retournées dans son contexte. Comme vous pouvez le constater, nous pouvons exécuter plusieurs décorateurs sur une même fonction car nous pouvons les “chaîner”.

Il existe deux types de syntaxes.

La syntaxe arobase @ :

@dec2
@dec1
def func(arg1, arg2):
    pass

Et la syntaxe classique :

def func(arg1, arg2):
    pass

func = dec2(dec1(func))

Les deux exemples de code ci-dessus sont équivalents. On utilise, généralement, la syntaxe @ lorsque nous souhaitons “figer” le comportement de la fonction (lors de son appel, ses décorateurs seront alors systématiquement exécutés) et la syntaxe classique si nous n’avons pas accés à sa définition ou lorsqu’on souhaite modifier son comportement à un endroit précis dans le code.

Les décorateurs peuvent prendre des arguments requis ou optionnels, en plus de la fonction à décorer. On peut alors modifier dynamiquement leur comportement. C’est le cas dans l’exemple du framework web Bottle avec les décorateurs @route et @view. C’est aussi le cas pour les décorateurs @login_required ou @permission_required de Django.

Un exemple avec @permission_required:

@permission_required('polls.can_vote', login_url='/loginpage/')
def my_view(request):
    ...

Non seulement de prendre pour argument la fonction à décorer, ce décorateur prend aussi un argument requis (la permission) et un argument optionnel (l’URL du formulaire d’authentification en cas d’échec).

Maintenant que nous connaissons un peu mieux les décorateurs, passons à la pratique. Nous allons, tout d’abord, implémenter un décorateur “simple” ne prenant pas d’argument. Nous aborderons ensuite l’implémentation de décorateurs plus élaborés, capables d’accepter des arguments (requis et/ou optionnels). Nous ferons ensuite connaissance avec functools.wraps (inclus dans Python). Et nous terminerons avec un exemple concret.

Décorateur simple

Commençons par un premier exemple :

# -*- coding: utf-8 -*-

# Notre décorateur
def decorate(func):
    print u"Je suis dans la fonction 'decorate' et je décore '%s'." % func.__name__
    print u"Exécution de la fonction '%s'." % func.__name__
    return func

# Notre fonction décorée
@decorate
def foobar(*args):
    print ", ".join(args)

# Appel de la fonction
foobar("A", "B", "C", "D")

Exécutons le code :

Je suis dans la fonction 'decorate' et je décore 'foobar'.
Exécution de la fonction 'foobar'.
A, B, C, D

Notre fonction a bien été décorée. Mais dans cet exemple, nous avons pas accès aux arguments de la fonction décorée. On affiche simplement une chaîne de caractères pour s’informer de l’éxecution du décorateur.

Modifions notre code pour pouvoir accéder aux arguments de la fonction décorée :

# -*- coding: utf-8 -*-

# Notre décorateur
def decorate(func):
    print u"Je suis dans la fonction 'decorate' et je décore '%s.'" % func.__name__
    def wrapper(*args, **kwargs):
        print u"Je suis dans la fonction 'wrapper' qui accède aux arguments de '%s'." % func.__name__
        a = list(args)
        a.reverse()
        print u"Je t'en donne la preuve, je peux les inverser : %s." % ', '.join(a)
        print u"Exécution de la fonction '%s'." % func.__name__
        return func(*args, **kwargs)
    return wrapper

# Notre fonction décorée
@decorate
def foobar(*args):
    print ", ".join(args)

# Appel de la fonction
foobar("A", "B", "C", "D")

Exécutons-le :

Je suis dans la fonction 'decorate' et je décore 'foobar.'
Je suis dans la fonction 'wrapper' qui accède aux arguments de 'foobar'.
Je t'en donne la preuve, je peux les inverser : D, C, B, A.
Exécution de la fonction 'foobar'.
A, B, C, D

Nous avons créé un wrapper, qui n’est autre qu’une fonction possédant la même signature (les mêmes arguments) que la fonction à décorer et qui retourne la fonction décorée, avec ses arguments. Le wrapper est lui-même retourné par le décorateur. C’est un système à la poupées Russes.

Dans cet exemple, nous avons seulement effectué un pré-traitement. Mais il est tout à fait possible, très simplement, d’effectuer un post-traitement sur la fonction à décorer :

# -*- coding: utf-8 -*-

# Notre décorateur
def decorate(func):
    print u"Je suis dans la fonction 'decorate' et je décore '%s.'" % func.__name__
    def wrapper(*args, **kwargs):
        print u"Je suis dans la fonction 'wrapper' qui accède aux arguments de '%s'." % func.__name__
        a = list(args)
        a.reverse()
        print u"J'en donne la preuve, je peux les inverser : %s." % ', '.join(a)
        print u"Exécution de la fonction '%s'." % func.__name__
        response = func(*args)
        print u"Je peux effectuer, ici, un post-traitement."
        return response
    return wrapper

# Notre fonction décorée
@decorate
def foobar(*args):
    print ", ".join(args)

# Appel de la fonction
foobar("A", "B", "C", "D")

Exécutons le code :

Je suis dans la fonction 'decorate' et je décore 'foobar.'
Je suis dans la fonction 'wrapper' qui accède aux arguments de 'foobar'.
Je t'en donne la preuve, je peux les inverser : D, C, B, A.
Exécution de la fonction 'foobar'.
A, B, C, D
Je peux effectuer, ici, un post-traitement.

Pour simplifier au maximum :

def decorate(func):
    def wrapper(*args, **kwargs):
        # Pré-traitement
        response = func(*args, **kwargs)
        # Post-traitement
        return response
    return wrapper

Ici, je récupère le retour de la fonction dans response et je retourne ensuite la valeur après le post-traitement. Mais si vous n’avez pas besoin d’accéder aux données retournées par la fonction à décorer, ce qui était un peu notre cas, il suffit juste d’appeller la fonction :

def decorate(func):
    def wrapper(*args, **kwargs):
        # Pré-traitement
        func(*args, **kwargs)
        # Post-traitement
    return wrapper

Cela dépend vraiment de votre implémentation.

C’est un peu plus clair ? Si vous avez compris les exemples ci-dessus et ce bout de code, vous avez tout compris.

J’entends certains penser fortement… Si un décorateur prend pour argument un callable, on doit pouvoir lui passer d’autres arguments, non ? Si, par exemple, on souhaite modifier son comportement dynamiquement ? Comme pour le décorateur @permission_required de Django, qui prend pour arguments une permission donnée et, éventuellement, l’URL de la page de connexion pour rediriger automatiquement l’utilisateur en cas d’échec :

@permission_required('polls.can_vote', login_url='/loginpage/')
def my_view(request):
    ...

Ou bien, comme avec les vues de Bottle et leurs décorateurs @route et @view:

@route('/hello/:names')
@view('hello')
def hello(names):
   names = names.split(',')
   return dict(title='Hello World', names=names)

Bien vu. Nous avons abordé l’implémentation d’un décorateur simple qui ne prend pas d’argument, excepté le callable à décorer. On ne peut donc pas modifier dynamiquement son comportement en précisant diverses options. Voyons comment implémenter un décorateur capable d’accepter des arguments.

Décorateur avec arguments

Pour implémenter un décorateur dynamique capable d’accépter des arguments (ou “options”), nous devons ajouter un niveau supplémentaire : un décorateur qui prend pour arguments les arguments du décorateur de la fonction à décorer. Vous suivez toujours ? Pour un décorateur simple, nous avons deux niveaux de fonctions (le décorateur et le wrapper). Pour un décorateur avec arguments, nous en avons trois (le décorateur du décorateur, le décorateur et le wrapper).

Si on simplifie au maxium :

def decorate(arg1, arg2, arg3):
    def decorated(func):
        def wrapper(*args, **kwargs):
            # Pré-traitement
            response = func(*args, **kwargs)
            # Post-traitement
            return response
        return wrapper
    return decorated

Prenons un exemple :

# -*- coding: utf-8 -*-

def decorate(arg1, arg2, arg3):
    print u'Je suis dans la fonction "decorate".'
    def decorated(func):
        print u'Je suis dans la fonction "decorated".'
        def wrapper(*args, **kwargs):
            print u'Je suis dans la fonction "wrapper".'
            print u"Les arguments du décorateurs sont : %s, %s, %s." % (arg1, arg2, arg3)
            print u"Pré-traitement."
            print u"Exécution de la fonction %s." % func.__name__
            response = func(*args, **kwargs)
            print u"Post-traitement."
            return response
        return wrapper
    return decorated

@decorate("Arg 1", "Arg 2", "Arg 3")
def foobar():
    print u"Je suis foobar, je vous reçois 5 sur 5."

foobar()

Si on exécute le code :

Je suis dans la fonction "decorate".
Je suis dans la fonction "decorated".
Je suis dans la fonction "wrapper".
Les arguments du décorateurs sont : Arg 1, Arg 2, Arg 3.
Pré-traitement.
Exécution de la fonction foobar.
Je suis foobar, je vous reçois 5 sur 5.
Post-traitement.

Les arguments passés au décorateur ont bien été pris en compte.

Nous avons implémenté un décorateur avec arguments obligatoires (ou requis). Pour passer des arguments optionnels :

def decorate(arg1='default', arg2=None, arg3=None):
    def decorated(func):
        def wrapper(*args, **kwargs):
            # Pré-traitement
            response = func(*args, **kwargs)
            # Post-traitement
            return response
        return wrapper
    return decorated

@decorate(arg1='my value')
def foobar():
    pass

Attention. Comme tous les arguments de ce décorateur sont optionnels, si on ne souhaite pas les modifier, on serait tenté d’appeller le décorateur comme un décorateur “simple” :

@decorate
def foobar():
    pass

Si on exécute ce code :

Traceback (most recent call last):
  File "exemple.py", line 22, in 
    foobar()
TypeError: decorated() takes exactly 1 argument (0 given)

Catastrophe ! Python vous demandera quand même de founir un argument, qu’il considère comme “requis” (même si tous les arguments sont optionnels). Dans ce cas, la bonne syntaxe est d’utiliser les parenthèses d’appel de fonction :

@decorate()
def foobar():
    pass

Ce n’est pas très sexy, source d’erreur, mais ça fonctionne. Nous aborderons plus loin comment contourner ce “problème”.

Un autre exemple, avec un argument obligatoire et des arguments optionnels :

def decorate(arg1, arg2='default value', arg3=None):
    def decorated(func):
        def wrapper(*args, **kwargs):
            # Pré-traitement
            response = func(*args, **kwargs)
            # Post-traitement
            return response
        return wrapper
    return decorated

@decorate('required value')
def foo():
    pass

@decorate('required value', arg3='my value')
def bar():
    pass

Retenez surtout les trois niveaux de fonctions (la fonction qui prend pour arguments les arguments du décorateur, le décorateur et le wrapper) et les parenthèses d’appel de fonction pour un décorateur avec arguments optionnels appelé sans argument.

Préservation de la fonction décorée

Jusque là, on s’est intéressé au décorateur, pas vraiment à la fonction décorée.

Penchons-nous de plus près sur la fonction décorée :

# -*- coding: utf-8 -*-

def logged(func):
    def wrapper(*args, **kwargs):
        """Je suis la documentation de logged."""
        print u"Exécution de %s." % func.__name__
        return func(*args, **kwargs)
    return wrapper

@logged
def foobar(arg):
    """Je suis la documentation de foobar."""
    print arg

foobar("Yeah!")

print foobar.__name__
print foobar.__doc__

Si on exécute ce bout de code :

Exécution de foobar.
Yeah!
_logged
Je suis la documentation de logged.

Mince ! On appelle la fonction foobar et c’est pourtant le nom et la documentation du décorateur logged que nous renvoie foobar.__name__ et foobar.__doc__. Ça, c’est bien le genre de truc à donner des migraines. Si on y réfléchie bien, c’est un comportement logique puisque la fonction retournée par le décorateur est une fonction de substitution, pas notre vraie foobar.

Heureusement, si vous utilisez Python 2.5 ou supérieure, functools.wraps vient à notre rescousse. Ce décorateur va préserver notre fonction décorée avec élégance et délicatesse. Pour ce faire, nous devons juste décorer le wrapper avec ce décorateur, en lui passant comme argument la fonction à décorer. Ensuite, il se charge du reste.

Un exemple :

# -*- coding: utf-8 -*-
import functools

def logged(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        """Je suis la documentation de logged."""
        print u"Exécution de %s." % func.__name__
        return func(*args, **kwargs)
    return wrapper

def foobar(arg):
    """Je suis la documentation de foobar."""
    print arg

foobar = logged(foobar)
foobar("Yeah!")

print foobar.__name__
print foobar.__doc__

Si on exécute ce code :

Exécution de foobar.
Yeah!
foobar
Je suis la documentation de foobar.

Hallelujah ! Ça marche.

Si vous n’utilisez pas Python 2.5 ou supérieur mais si vous utilisez Django et Python 2.4, vous pouvez quand même bénéficier de cette fonctionnalité via django.utils.functional.wraps.

Décorateurs avec ou sans arguments

Nous avons vu, plus haut, comment implémenter un décorateur avec arguments obligatoires ou optionnels. Nous nous sommes aperçu que si nous appellons un décorateur ne prenant que des arguments optionnels sans argument, comme un décorateur “simple”, Python renvoie une erreur. En ajoutant les parenthèses d’appel de fonction, on contourne le problème.

Exemple :

# -*- coding: utf-8 -*-

def decorate(arg1='default', arg2=None, arg3=None):
    def decorated(func):
        def wrapper(*args, **kwargs):
            # Pré-traitement
            response = func(*args, **kwargs)
            # Post-traitement
            return response
        return wrapper
    return decorated

# MAUVAIS
@decorate
def foobar():
    pass

# BON
@decorate()
def foobar():
    pass

Malheureusement, il n’existe pas de solution générique. Pas de solution idéale qui nous permettrait d’implémenter des décorateurs capables d’être appelés avec ou sans arguments, sans parenthèses d’appel de fonction. Un décorateur ne prend pas d’argument ? Pas de paranthèses. Un décorateur prend des arguments optionnels, même avec des valeurs par défaut ? Lorsqu’il est appelé seul, les parenthèses s’imposent. Pour un décorateur avec des arguments obligatoires, on ne se pose même pas la question puisque nous sommes “obligé” de lui donner des arguments.

Cependant, si il n’existe pas de solution “générique”, nous pouvons quand même modifier notre implémentation pour éviter l’emploi des parenthèses. Nous devons alors donner notre fonction à décorer comme premier argument au décorateur de notre décorateur. On l’initialisera à None. Si nous fournissons des arguments optionnels, la valeur de notre fonction sera None, on retournera alors une fonction prenant pour argument notre fonction à décorer et qui retournera notre décorateur. Si la valeur de notre fonction n’est pas None, cela sous-entend que nous appelons notre décorateur sans argument, ni parenthèses.

Pour mieux comprendre, modifions notre exemple :

# -*- coding: utf-8 -*-

def decorate(func=None, arg1=None, arg2=None, arg3=None):
    print u'Je suis dans la fonction "decorate".'
    def decorated(func):
        print u'Je suis dans la fonction "decorated".'
        def wrapper(*args, **kwargs):
            print u'Je suis dans la fonction "wrapper".'
            print u"Les arguments du décorateurs sont : %s, %s, %s." % (arg1, arg2, arg3)
            print u"Pré-traitement."
            print u"Exécution de la fonction %s." % func.__name__
            response = func(*args, **kwargs)
            print u"Post-traitement."
            return response
        return wrapper
    if func is None:
        # Le décorateur est appellé avec des arguments
        def decorator(func):
            return decorated(func)
        return decorator
    # Le décorateur est appellé sans arguments
    return decorated(func)

@decorate
def foobar():
    print u"Je suis foobar, je vous reçois 5 sur 5."

foobar()

Si on exécute ce code :

Je suis dans la fonction "decorate".
Je suis dans la fonction "decorated".
Je suis dans la fonction "wrapper".
Les arguments du décorateurs sont : None, None, None.
Pré-traitement.
Exécution de la fonction foobar.
Je suis foobar, je vous reçois 5 sur 5.
Post-traitement.

Ça marche ! Nous n’avons plus besoin d’ajouter les parenthèses à notre décorateur quand il est appelé sans argument. Mais, en contre-partie, cela nous contraint à lui donner uniquement des arguments nommés :

# BON
@decorate(arg1="Python", arg2="Haskell")
def foobar():
    print u"Je suis foobar, je vous reçois 5 sur 5."

# MAUVAIS
@decorate("Python", "Haskell")
def foobar():
    print u"Je suis foobar, je vous reçois 5 sur 5."

Si on exécute le second exemple :

Je suis dans la fonction "decorate".
Je suis dans la fonction "decorated".
Je suis dans la fonction "wrapper".
Les arguments du décorateurs sont : Haskell, None, None.
Pré-traitement.
Traceback (most recent call last):
  File "exemple.py", line 24, in 
    @decorate("Python", "Haskell")
  File "exemple.py", line 11, in wrapper
    print u"Exécution de la fonction %s." % func.__name__
AttributeError: 'str' object has no attribute '__name__'

Ça coince. Notre chaîne de caractères “Python” a été interprétée comme la fonction à décorer, puisqu’elle a été passée comme premier argument, donc logiquement considérée comme func.

Vous vous souvenez du chapitre précédent ? Notre code ne préserve pas la fonction décorée. Rajoutons un peu de documentation et appelons foobar.__name__ et foobar.__doc__ pour s’en convaincre :

# -*- coding: utf-8 -*-

def decorate(func=None, arg1=None, arg2=None, arg3=None):
    print u'Je suis dans la fonction "decorate".'
    def decorated(func):
        print u'Je suis dans la fonction "decorated".'
        def wrapper(*args, **kwargs):
            """Je suis la documentation de decorate."""
            print u'Je suis dans la fonction "wrapper".'
            print u"Les arguments du décorateurs sont : %s, %s, %s." % (arg1, arg2, arg3)
            print u"Pré-traitement."
            print u"Exécution de la fonction %s." % func.__name__
            response = func(*args, **kwargs)
            print u"Post-traitement."
            return response
        return wrapper
    if func is None:
        # Le décorateur est appellé avec des arguments
        def decorator(func):
            return decorated(func)
        return decorator
    # Le décorateur est appellé sans arguments
    return decorated(func)

@decorate(arg1="Python", arg2="Haskell")
def foobar():
    """Je suis la documentation de foobar."""
    print u"Je suis foobar, je vous reçois 5 sur 5."

print foobar.__name__
print foobar.__doc__

Exécutons :

Je suis dans la fonction "decorate".
Je suis dans la fonction "decorated".
wrapper
Je suis la documentation de decorate.

Mauvais. Faisons appel à functools.wraps :

# -*- coding: utf-8 -*-
import functools

def decorate(func=None, arg1=None, arg2=None, arg3=None):
    print u'Je suis dans la fonction "decorate".'
    def decorated(func):
        print u'Je suis dans la fonction "decorated".'
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            """Je suis la documentation de decorate."""
            print u'Je suis dans la fonction "wrapper".'
            print u"Les arguments du décorateurs sont : %s, %s, %s." % (arg1, arg2, arg3)
            print u"Pré-traitement."
            print u"Exécution de la fonction %s." % func.__name__
            response = func(*args, **kwargs)
            print u"Post-traitement."
            return response
        return wrapper
    if func is None:
        # Le décorateur est appellé avec des arguments
        def decorator(func):
            return decorated(func)
        return decorator
    # Le décorateur est appellé sans arguments
    return decorated(func)

@decorate(arg1="Python", arg2="Haskell")
def foobar():
    """Je suis la documentation de foobar."""
    print u"Je suis foobar, je vous reçois 5 sur 5."

print foobar.__name__
print foobar.__doc__

Exécutons :

Je suis dans la fonction "decorate".
Je suis dans la fonction "decorated".
foobar
Je suis la documentation de foobar.

C’est beaucoup mieux.

Exemple concret avec Django

Vous connaissez la fonction render_to_response de Django ? C’est un raccourci pour rendre du contenu dans un template. Cette fonction prend pour arguments : le nom du template (requis), un dictionnaire contenant les variables/valeurs à ajouter dans le contexte du template (optionnel), une instance de Context ou RequestContext (si on souhaite bénéficier des context processors) dans laquelle sera injecté le dictionnaire (par défaut, une instance de Context) et le type MIME de la réponse (par défaut, celui défini par settings.DEFAULT_CONTENT_TYPE).

Exemple :

# -*- coding: utf-8 -*-
from django.shortcuts import render_to_response

def home(request):
    """
    Page d'accueil.
    """
    return render_to_response('home.html', {'foo': 'bar'})

Dans cet exemple, nous n’accédons pas aux context processors de Django. Pour pour avoir accéder à ces fameux context processors, nous devons plutôt utiliser une instance RequestContext :

# -*- coding: utf-8 -*-
from django.shortcuts import render_to_response
from django.template import RequestContext

def home(request):
    """
    Page d'accueil.
    """
    return render_to_response(
        'home.html',
        {"foo": "bar"},
        context_instance=RequestContext(request))

On est bien d’accord, c’est un peu verbeux. Si vous êtes un développeur Django rusé, vous utilisez certainement les vues génériques (nous allons y venir). Comme nous ne sommes pas censé savoir qu’il existe déjà une solution prête-à-l’emploi, implémentons un décorateur pour rendre ce code un peu plus concis. Nous allons le nommer render.

Implémentation :

# -*- coding: utf-8 -*-
import functools

from django.shortcuts import render_to_response
from django.template import RequestContext

def render(template):
    def decorated(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            """
            Raccourci du raccourci ``django.shortcuts.render_to_response``.
            """
            context = func(*args, **kwargs)
            return render_to_response(
                template,
                context,
                context_instance=RequestContext(args[0]))
        return wrapper
    return decorated

@render('home.html')
def home(request):
    """
    Page d'accueil.
    """
    return {
        'title': u"Home",
        'description': u"This is the homepage.",
        'view_name': home.__name__,
        'view_doc': home.__doc__,
        }

Nos vues n’ont plus qu’à retourner un dictionnaire des variables/valeurs à injecter dans le context du template, que nous donnons comme argument au décorateur. Notre décorateur render se charge du reste. Les variables view_name et view_doc doivent respectivement retourner le nom et la documentation de la vue, et non celles du décorateur. Merci functools.wrap.

Oui mais… On a réinventé la roue. Django propose déjà des vues génériques, dont notamment direct_to_template. Nous n’avons, d’ailleurs, même plus besoin d’écrire la moindre vue. On spécifie tout ça dans notre module urls.py.

Notre code se limite à :

urlpatterns = patterns('',
    url(r'^foobar/$', 'django.views.generic.simple.direct_to_template', {
        'template': 'foobarapp/index.html',
        'extra_context': {
            "foo": "bar",
        }},
        name="foobar",
    ),
)

Merci les vues génériques. Il est vivement recommandé d’en abuser.

Un peu de lecture

Pour en savoir plus, n’hésitez pas à consulter ces liens :

Conclusion

Les décorateurs sont une fonctionnalité très puissante et très utilisée du langage Python. Python, lui-même, en propose de nombreux. Nous n’avons qu’abordé functools.wraps, mais il en existe beaucoup d’autres que vous rencontrerez certainement un jour dans vos projets. Cet article n’est qu’une simple introduction tant les possibilités offertes sont larges. Ils sont un point fort du langage, avec sa syntaxe et son écosystème. Ne vous en privez pas. À vos décorateurs !

Python et les "callables"

2010-07-31T00:00:00.000Z

Tout développeur Python s’est certainement en jour posé cette question : qu’est-ce qu’un callable au sens Python ? Tout objet “exécutable” ou “appelable” ? Flou. Vague. En Python, les fonctions et les méthodes sont “naturellement” des callables puisqu’elles sont définies pour être appelées. On dit d’ailleurs qu’un objet callable est un objet qui peut être appelé comme une fonction (avec des parenthèses et prenant, éventuellement, des arguments).

Si l’on se réfère à la documentation officielle, sont callables :

Les fonctions et méthodes que nous définissons (user-defined)
Les fonctions et méthodes natives (built-in)
Les fonctions generator
Les classes new-style ou old-style (nommées aussi classic)
Les instances de classe possédant une méthode __call__

En effet, Python ne limite pas qu’aux fonctions, classes et méthodes. Un callable est aussi tout objet qui possède une méthode spécifique nommée __call__. Pour être plus précis : un objet dont le type possède une méthode spécifique nommée __call__. Si l’objet est appelée comme une fonction, il retournera la valeur retournée par cette méthode.

Les deux exemples ci-dessous sont similaires :

# 1er exemple : une fonction
# -------------------------------------------------------------------------
def foo():
    """
    Callable affichant la chaîne de caractères "Hello".
    """
    print u"Hello"

# Ici, on appelle directement la fonction
foo()

# 2ème exemple : une classe avec méthode "__call__"
# -------------------------------------------------------------------------
class Foo(object):
    """
    Callable affichant la chaîne de caractères "Hello".
    """

    def __call__(self):
        print u"Hello"

# Ici, on instancie la classe et on appelle l'objet comme une fonction
foo = Foo()
foo()

Grâce à cette fonctionnalité, il est alors tout à fait possible d’utiliser les instances d’une classe comme des fonctions. À la seule différence qu’une instance de classe préserve l’état de ses variables (ce qui permet de modifier ses données à tout moment) et permet d’effectuer d’autres opérations (via différentes méthodes), pas seulement un appel à __call__.

Exemple :

# -*- coding: utf-8 -*-
class Add(object):
    """
    Callable stockant un compteur que nous pouvons incrémenter à chaque
    appel en lui donnant comme argument un entier.
    """

    def __init__(self):
        """
        Initialisation du compteur.
        """
        self.count = 0

    def __call__(self, value=None):
        """
        Méthode exécutée si l'objet est appelé comme une fonction.
        """
        if value is not None:
            self.count += int(value)
        return self.count

    def reset(self):
        """
        Remet à zéro le compteur.
        """
        self.count = 0

add = Add()

print add()
print add(10)
print add()
print add(15)
add.reset()
print add()
print add(2)

Si on exécute ce code :

Dans cet exemple, on crée une instance dont le compteur est initialisé à zéro. Si on appelle cette instance comme une fonction, et si on ne lui donne pas d’argument, elle renvoie l’état actuel du compteur. Si on lui donne un entier, elle incrémente son état. L’état est préservé. On peut également effectuer d’autres opérations sur l’objet, dont notamment la remise à zéro du compteur.

L’utilisation de __call__ est, notamment, très intéressante avec le framework web Django. Son système d’URL accepte n’importe quel callable, pas seulement des fonctions. Il est alors possible d’implémenter des vues reposant sur des classes. On appelle ce type de vue : class-based. Les applications admin et syndication utilisent cette technique. D’autres exemples ?

Le projet django-class-based-views de Ben Fishman
Le projet django-clsview de Zachary Voase
La branche class-based-generic-views de Jacob Kaplan-Moss
Les slides de la conférence de Simon Willison sur le sujet

Pour savoir si un objet est callable ou pas, il est tentant d’utiliser la fonction native callable, incluse dans Python 2.x. Elle prend pour argument l’objet à tester. Si elle renvoie True, l’objet est bien callable.

Exemple avec une fonction et un entier :

>>> def foo():
...     pass
...
>>> callable(foo)
True
>>> i = 3
>>> callable(i)
False

Mais cette fonction a été supprimée dans la version 3 du langage. On peut, cependant, aisément la remplacer par une fonction lambda qui vérifie si l’objet passé en argument possède ou non un attribue nommé __call__ :

>>> callable = lambda o: hasattr(o, '__call__')
>>> callable(foo)
True
>>> callable(i)
False

En revanche, si les classes new-style héritant d’object disposent par défaut d’une méthode __call__, les classes old-style (ou classic) n’héritant pas d’object n’ont pas de méthode __call__ mais sont considérées comme callable (puisqu’elles retournent une instance). C’est un point important puisque notre fonction lambda appliquée sur une classe old-style renverra systématiquement False.

Exemple :

>>> is_callable = lambda o: hasattr(o, '__call__')
>>> class Foo:
...     pass
...
...
>>> callable(Foo)
True
>>> is_callable(Foo)
False

On remarque bien dans cet exemple que notre fonction lambda considère notre classe old-style comme non-callable, alors que la fonction native callable la considère comme callable. Méfiance. Cela peut être source de bogue. Le plus sage serait de bannir définitivement les classes old-style puisqu’elles ont disparu dans la version 3 du langage. Ou de continuer à utiliser la fonction callable (ou votre propre implémentation), si vous utilisez des classes old-style avec une version 2.x.

Précision. Si une classe new-style est callable par défaut, on parle bien de la “classe” et non de ses éventuelles instances. Si on instancie un objet à partir de cette classe, il ne possédera pas de méthode __call__, sauf si nous la définissons explicitement.

Preuve à l’appui :

>>> class Bar(object):
...     pass
...
>>> hasattr(Bar, '__call__')
True
>>> bar = Bar()
>>> hasattr(bar, '__call__')
False
>>> class Bar(object):
...     def __call__(self):
...         pass
...
>>> bar = Bar()
>>> hasattr(bar, '__call__')
True

Maintenant qu’on s’est familiarisé avec les callables, faisons quelques tests.

# -*- coding: utf-8 -*-

class OldStyle:
    foo = "attribut foo"

    def bar(self):
        pass

class OldStyleCall:
    foo = "attribut foo"
    def __call__(self):
        pass

    def bar(self):
        pass

class NewStyle(object):
    foo = "attribut foo"

    def bar(self):
        pass

class NewStyleCall(object):
    foo = "attribut foo"

    def __call__(self):
        pass

    def bar(self):
        pass

old_style = OldStyle()
old_style_call = OldStyleCall()
new_style = NewStyle()
new_style_call = NewStyleCall()

generator_expr = (2*x for x in (1, 2, 3))

def generator_func(n):
    while n > 0:
        yield n
        n -= 1

def function():
    pass

lambda_func = lambda x: x

TEST_OBJECTS = (
    ('sep', u'Types natifs'),
    (u"Entier",  10),
    (u"Flottant", 10.9),
    (u"Chaîne de caractères", u"Hello"),
    (u"Booléen", True),
    (u"Liste", [1, 2, 3]),
    (u"Tuple", (1, 2, 3)),
    (u"Dictionnaire", {u"1": 1, u"2": 2, u"3": 3}),

    ('sep', u'Generators'),
    (u"Expression", generator_expr),
    (u"Fonction", generator_func),

    ('sep', u'Fonctions'),
    (u"Fonction", function),
    (u"Fonction lambda", lambda_func),

    ('sep', u'Classes "Old-Style"'),
    (u"Classe", OldStyle),
    (u"Méthode de classe", OldStyle.bar),
    (u"Attribut de classe", OldStyle.foo),

    ('sep', u'Classes "Old-Style" avec méthode "__call__"'),
    (u"Classe", OldStyleCall),
    (u"Méthode de classe", OldStyleCall.bar),
    (u"Attribut de classe", OldStyleCall.foo),

    ('sep', u'Classes "New-Style"'),
    (u"Classe", NewStyle),
    (u"Méthode de classe", NewStyle.bar),
    (u"Attribut de classe", NewStyle.foo),

    ('sep', u'Classes "New-Style" avec méthode "__call__"'),
    (u"Classe", NewStyleCall),
    (u"Méthode de classe", NewStyleCall.bar),
    (u"Attribut de classe", NewStyleCall.foo),

    ('sep', u'Instance de classe "Old-Style"'),
    (u"Instance", old_style),
    (u"Méthode d'instance", old_style.bar),
    (u"Attribut d'instance", old_style.foo),

    ('sep', u'Instance de classe "Old-Style" avec méthode "__call__"'),
    (u"Instance", old_style_call),
    (u"Méthode d'instance", old_style_call.bar),
    (u"Attribut d'instance", old_style_call.foo),

    ('sep', u'Instance de classe "New-Style"'),
    (u"Instance", new_style),
    (u"Méthode d'instance", new_style.bar),
    (u"Attribut d'instance", new_style.foo),

    ('sep', u'Instance de classe "New-Style" avec méthode "__call__"'),
    (u"Instance", new_style_call),
    (u"Méthode d'instance", new_style_call.bar),
    (u"Attribut d'instance", new_style_call.foo),
    )

is_callable = lambda o: u"OUI" if callable(o) else u"NON"

for k, v in TEST_OBJECTS:
    if k == 'sep':
        print ""
        print v
        print "-" * 54
    else:
        print u"%s : %s" % (k, is_callable(v))

Vérifions :

Types natifs
------------------------------------------------------
Entier : NON
Flottant : NON
Chaîne de caractères : NON
Booléen : NON
Liste : NON
Tuple : NON
Dictionnaire : NON

Generators
------------------------------------------------------
Expression : NON
Fonction : OUI

Fonctions
------------------------------------------------------
Fonction : OUI
Fonction lambda : OUI

Classes "Old-Style"
------------------------------------------------------
Classe : OUI
Méthode de classe : OUI
Attribut de classe : NON

Classes "Old-Style" avec méthode "__call__"
------------------------------------------------------
Classe : OUI
Méthode de classe : OUI
Attribut de classe : NON

Classes "New-Style"
------------------------------------------------------
Classe : OUI
Méthode de classe : OUI
Attribut de classe : NON

Classes "New-Style" avec méthode "__call__"
------------------------------------------------------
Classe : OUI
Méthode de classe : OUI
Attribut de classe : NON

Instance de classe "Old-Style"
------------------------------------------------------
Instance : NON
Méthode d'instance : OUI
Attribut d'instance : NON

Instance de classe "Old-Style" avec méthode "__call__"
------------------------------------------------------
Instance : OUI
Méthode d'instance : OUI
Attribut d'instance : NON

Instance de classe "New-Style"
------------------------------------------------------
Instance : NON
Méthode d'instance : OUI
Attribut d'instance : NON

Instance de classe "New-Style" avec méthode "__call__"
------------------------------------------------------
Instance : OUI
Méthode d'instance : OUI
Attribut d'instance : NON

Finalement, rien de bien compliqué.

Créer un blog avec Django 1.2

2010-07-22T00:00:00.000Z

Cet article est une mise à jour d’une précédente publication : créer un blog avec Django, basée sur la version 1.1 du framework. La version 1.2 requière de légères modifications.

Introduction

Créer un blog avec Django, c’est simple. Oui, vraiment. Ce tutorial s’adresse aux personnes connaissant déjà un peu le langage de programmation Python et disposant d’un environnement de développement Django opérationnel.

Brièvement, cela se résume à :

Python (interpréteur, libraires… )
Un gestionnaire de bases de données et son binding
Un terminal (ou “console”)
Un navigateur web
Un éditeur de texte

Si vous désirez installer Django sur votre machine, n’hésitez pas à consulter la section Quick install guide de la documentation.

Mise en place du projet

Dans ce tutoriel, nous allons utiliser MySQL comme gestionnaire de bases de données mais vous pouvez utiliser n’importe quel autre gestionnaire de bases de données supporté par Django.

Il faut donc, tout d’abord, créer une base de données :

$ mysql -u user -p
mysql> CREATE DATABASE blog;

Remplacez user par l’utilisateur qui va bien (root ou un utilisateur ayant les droits de création de base). Comme il vaut mieux éviter d’utiliser l’utilisateur root, même en local, nous allons créer un utilisateur spécifique pour la base et lui donner les permissions nécessaires. Nous allons nommer cet utilisateur blog, du même nom que la base :

mysql> GRANT ALL ON blog.* TO blog@localhost IDENTIFIED BY 'password';
mysql> FLUSH PRIVILEGES;
mysql> \q

Bien sûr, remplacez password par un vrai mot de passe.

Notre base est créée.

Dans un dossier de votre répertoire personnel (si possible, dans un dossier dédié à vos projets de programmation), nous allons créer le projet Django website et l’application blog :

$ django-admin startproject website
$ cd website
$ django-admin startapp blog

Dans le répertoire du projet website, nous allons créer un dossier templates (qui contiendra nos templates) et un dossier media qui contiendra les fichiers statiques :

$ mkdir templates
$ mkdir media

Pour bien séparer nos applications, nous allons les placer dans un répertoire apps à la racine du projet :

$ mkdir apps
$ touch apps/__init__.py
$ mv blog apps/

La commande tree devrait retourner cette arborescence :

.
|-- __init__.py
|-- apps
|   |-- __init__.py
|   `-- blog
|       |-- __init__.py
|       |-- models.py
|       `-- views.py
|-- manage.py
|-- media
|-- settings.py
|-- templates
`-- urls.py

Le projet est en place. Exécutez la commande suivante :

$ python manage.py runserver

Dans votre navigateur, pointez l’adresse : http://127.0.0.1:8000.

Bienvenue sous Django ! Control + C pour stopper le serveur.

Paramètres et URLs

Éditez le fichier settings.py à l’aide de votre éditeur favori.

Tout d’abord, on crée la constante PROJECT_PATH (en haut du fichier) afin de stocker le chemin absolu vers notre projet :

import os.path
PROJECT_PATH = os.path.dirname(os.path.abspath(__file__))

C’est pratique si vous utilisez différents systèmes d’exploitation ou différentes machines. Le chemin est automatiquement détecté.

Ensuite, on passe à la base de données :

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'blog',
        'USER': 'blog',
        'PASSWORD': 'mot-de-passe',
        'HOST': '',
        'PORT': '',
    }
}

On ajuste la timezone :

TIME_ZONE = 'Europe/Paris'

On ajuste la langue par défaut :

LANGUAGE_CODE = 'fr-fr'

On ajoute notre répertoire media :

MEDIA_ROOT = os.path.join(PROJECT_PATH, 'media/')

On ajoute l’URL vers les médias :

MEDIA_URL = '/media/'

On ajuste l’URL vers les médias de l’interface d’administration :

ADMIN_MEDIA_PREFIX = '/media/admin/'

On ajoute notre répertoire templates :

TEMPLATE_DIRS = (
    os.path.join(PROJECT_PATH, 'templates'),
)

On ajoute notre application blog à la liste INSTALLED_APPS :

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.admin',
    'website.apps.blog',
)

On enregistre les modifications et on passe aux URLs.

Éditez le fichier urls.py. Nous allons ajouter le support des médias. Django va donc prendre en charge les fichiers statiques (pratique quand on développe en local mais à proscrire en production). Pour ce faire, on importe le module settings pour récupérer MEDIA_ROOT (le chemin absolu vers le répertoire media) et on ajoute un urlpatterns pour django.views.static.serve :

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
# from django.contrib import admin
# admin.autodiscover()


urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    # (r'^admin/(.*)', include(admin.site.root)),
)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

On enregistre les modifications et on passe à l’installation de l’interface d’administration.

Installation de l’interface d’administration

Django embarque une interface d’administration sympathique et pratique. L’installation se fait en trois étapes : ajout de l’application dans le fichier settings.py, ajout des URLs et synchronisation de la base de données.

Éditez le fichier settings.py et ajoutez django.contrib.admin dans la liste INSTALLED_APPS :

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',
    'website.apps.blog',
)

Enregistrez les modifications.

Éditez le fichier urls.py et ajoutez le support de l’admin en décommentant les lignes indiquées dans les commentaires, soit trois lignes au total :

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()


urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    (r'^admin/(.*)', include(admin.site.root)),
)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

Enregistrez les modifications.

Il ne reste plus qu’à synchroniser avec la base de données (à exécuter à la racine du projet) :

$ python manage.py syncdb

Django vous guidera dans la création d’un compte super-utilisateur.

Lancez le serveur :

$ python manage.py runserver

Dans votre navigateur, pointer l’adresse : http://127.0.0.1:8000/admin/. Entrez votre identifiant et votre mot de passe super-utilisateur. Bienvenue dans l’interface d’administration de Django !

Écriture des tests

Oui, écrire les tests avant le code, c’est mieux. Ça permet d’éviter des bogues et des prises de tête. Le but est le suivant : faire en sorte que tous les tests passent. Prêt ? Alors créez un fichier tests.py à la racine de l’application blog. On commence par importer la classe TestCase du module django.test et on crée une classe BlogTest qui contiendra nos tests :

# -*- coding: utf-8 -*-
from django.test import TestCase


class BlogTest(TestCase):
    pass

On lance les tests (à exécuter à la racine du projet) :

$ python manage.py test
Creating test database...
Creating table auth_permission
Creating table auth_group
Creating table auth_user
Creating table auth_message
Creating table django_content_type
Creating table django_session
Creating table django_site
Creating table django_admin_log
Installing index for auth.Permission model
Installing index for auth.Message model
Installing index for admin.LogEntry model
................
----------------------------------------------------------------------
Ran 16 tests in 2.134s

OK
Destroying test database...

Tous les tests passent ! Normal, nous n’en avons écrit aucun. Au boulot !

Notre classe de test :

# -*- coding: utf-8 -*-
from django.test import TestCase
from django.core.urlresolvers import reverse


class BlogTest(TestCase):
    """
    Tests of ``blog`` application.
    """
    fixtures = ['test_data']

    def test_entry_archive_index(self):
        """
        Tests ``entry_archive`` view.

        """
        response = self.client.get(reverse('blog'))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive.html')

    def test_entry_archive_year(self):
        """
        Tests ``entry_archive_year`` view.
        """
        response = self.client.get(reverse('blog_year', args=['2010']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_year.html')

    def test_entry_archive_month(self):
        """
        Tests ``entry_archive_month``view.
        """
        response = self.client.get(reverse('blog_month', args=['2010', '07']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_month.html')

    def test_entry_archive_day(self):
        """
        Tests ``entry_archive_day`` view.
        """
        response = self.client.get(reverse('blog_day', args=['2010', '07', '21']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_day.html')

    def test_entry_detail(self):
        """
        Tests ``entry_detail`` view.
        """
        response = self.client.get(reverse('blog_entry', args=['2010', '07', '21', 'test-entry']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_detail.html')

    def test_entry_detail_not_found(self):
        """
        Test ``entry_detail`` view with an offline entry.
        """
        response = self.client.get(reverse('blog_entry', args=['2010', '07', '21', 'offline-entry']))
        self.failUnlessEqual(response.status_code, 404)

    def test_category_detail(self):
        """
        Tests ``category_detail`` view.
        """
        response = self.client.get(reverse('blog_category', args=['test']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/category_detail.html')

    def test_category_detail_not_found(self):
        """
        Tests ``category_detail`` view with an offline category.
        """
        response = self.client.get(reverse('blog_category', args=['offline']))
        self.failUnlessEqual(response.status_code, 404)

La fonction reverse est utilisée pour récupérer l’URL en fonction de son nom (URLs nommées). Pour en savoir plus, n’hésitez pas à consulter la section URL dispatcher de la documentation. Nous testons ici la réponse et le template (pour vérifier que la future vue renverra bien le bon template). Si vous relancez les tests, vous devriez vous faire insulter. C’est normal. Nous n’avons encore rien implémenté. Donc, passons à l’implémentation.

Création des modèles

Nous allons réaliser un blog “basique” composé de deux modèles : Entry et Category. Le premier modèle représente un billet de blog et le deuxième une catégorie pour classer les billets par thème.

Un billet est composé des champs suivants :

Un titre
Un slug (aussi appelé “permalien”)
Un auteur
Une catégorie
Une date de création
Une date de modification
Une date de publication
Un statut (en ligne / hors ligne)
Un corps au format HTML

Une categorie est composée des champs suivants :

Un nom
Un slug (aussi appelé “permalien”)
Une date de création
Une date de modification

Éditez le fichier models.py du répertoire blog. Ce fichier contiendra les modèles de notre application. Pour en savoir plus, n’hésitez pas à consulter la section Writing models de la documentation.

Nos modèles :

# -*- coding: utf-8 -*-
"""
Models of ``blog`` application.
"""
from datetime import datetime

from django.db import models
from django.utils.translation import ugettext_lazy as _


class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })


class Entry(models.Model):
    """
    A blog entry.
    """
    STATUS_OFFLINE = 0
    STATUS_ONLINE = 1
    STATUS_DEFAULT = STATUS_OFFLINE
    STATUS_CHOICES = (
        (STATUS_OFFLINE, _('Offline')),
        (STATUS_ONLINE, _('Online')),
    )

    title = models.CharField(_('title'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique_for_date='publication_date')
    author = models.ForeignKey('auth.User', verbose_name=_('author'))
    category = models.ForeignKey(Category, verbose_name=_('category'))
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)
    publication_date = models.DateTimeField(_('publication date'), default=datetime.now(), db_index=True)
    status = models.IntegerField(_('status'), choices=STATUS_CHOICES, default=STATUS_DEFAULT, db_index=True)
    body = models.TextField(_('body'))

    class Meta:
        verbose_name = _('entry')
        verbose_name_plural = _('entries')

    def __unicode__(self):
        return u'%s' % self.title

    @models.permalink
    def get_absolute_url(self):
        return ('blog_entry', (), {
            'year': self.publication_date.strftime('%Y'),
            'month': self.publication_date.strftime('%m'),
            'day': self.publication_date.strftime('%d'),
            'slug': self.slug,
        })

La syntaxe du langage Python est tellement clean que le code parle de lui-même.

Nos modèles sont i18n-ready (via la fonction magique _()).

Avant de créer nos tables, il est recommandé de vérifier si les modèles ne comportent aucune erreur. Pour ce faire, à la racine du projet, on exécute la commande suivante :

$ python manage.py validate
0 errors found

Si cette commande renvoie des erreurs, il suffira de les corriger.

Tout est OK. On synchronise avec la base de données:

$ python manage.py syncdb
Creating table blog_category
Creating table blog_entry
Installing index for blog.Entry model

Par la suite, dans nos templates, nous afficheront uniquement les billets ayant pour statut “en ligne”. Lors de la récupération de nos objets, on peut très bien filtrer sur ce champ. Mais parce qu’on est feignant, on va créer des managers pour s’épargner du code.

Les méthodes d’un manager s’appliquent à une table, tandis que les méthodes d’un modèle s’appliquent à un objet. Donc, si nous voulons récupérer tous les billets ayant pour statut “en ligne”, nous avons besoin d’un manager. Si nous voulons récupérer le nom complet de l’auteur du billet, nous devons définir une méthode spécifique dans le modèle.

Nous avons besoin de deux managers : un pour manipuler uniquement les billets “en ligne” et un autre pour manipuler uniquement les catégories ayant des billets “en ligne” (c’est-à-dire que si nous rédigeons un seul billet dans une catégorie et que ce billet est “hors ligne”, la catégorie ne doit pas exister publiquement).

Dans le répertoire de notre application, on crée un fichier (ou plutôt, un module) nommé managers.py. N’hésitez pas à consulter la section Managers de la documentation pour en savoir plus.

Nos managers :

# -*- coding: utf-8 -*-
"""
Managers of ``blog`` application.
"""
from django.db import models


class CategoryOnlineManager(models.Manager):
    """
    Manager that manages online ``Category`` objects.
    """

    def get_query_set(self):
        from website.apps.blog.models import Entry
        entry_status = Entry.STATUS_ONLINE
        return super(CategoryOnlineManager, self).get_query_set().filter(
            entry__status=entry_status).distinct()


class EntryOnlineManager(models.Manager):
    """
    Manager that manages online ``Entry`` objects.
    """

    def get_query_set(self):
        return super(EntryOnlineManager, self).get_query_set().filter(
            status=self.model.STATUS_ONLINE)

Il faut maintenant ajouter ces managers dans nos modèles :

# -*- coding: utf-8 -*-
"""
Models of ``blog`` application.
"""
from datetime import datetime

from django.db import models
from django.utils.translation import ugettext_lazy as _

from website.apps.blog.managers import CategoryOnlineManager
from website.apps.blog.managers import EntryOnlineManager


class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    objects = models.Manager()
    online_objects = CategoryOnlineManager()

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })


class Entry(models.Model):
    """
    A blog entry.
    """
    STATUS_OFFLINE = 0
    STATUS_ONLINE = 1
    STATUS_DEFAULT = STATUS_OFFLINE
    STATUS_CHOICES = (
        (STATUS_OFFLINE, _('Offline')),
        (STATUS_ONLINE, _('Online')),
    )

    title = models.CharField(_('title'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique_for_date='publication_date')
    author = models.ForeignKey('auth.User', verbose_name=_('author'))
    category = models.ForeignKey(Category, verbose_name=_('category'))
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)
    publication_date = models.DateTimeField(_('publication date'), default=datetime.now(), db_index=True)
    status = models.IntegerField(_('status'), choices=STATUS_CHOICES, default=STATUS_DEFAULT, db_index=True)
    body = models.TextField(_('body'))

    objects = models.Manager()
    online_objects = EntryOnlineManager()

    class Meta:
        verbose_name = _('entry')
        verbose_name_plural = _('entries')

    def __unicode__(self):
        return u'%s' % self.title

    @models.permalink
    def get_absolute_url(self):
        return ('blog_entry', (), {
            'year': self.publication_date.strftime('%Y'),
            'month': self.publication_date.strftime('%m'),
            'day': self.publication_date.strftime('%d'),
            'slug': self.slug,
        })

Nous avons des modèles, des managers, une interface d’administration… Ah tiens, et si on ajoutait nos modèles dans l’admin ? Il serait peut-être temps de rédiger quelques billets et de créer quelques catégories pour nos tests.

Ajout des modèles dans l’interface d’administration

Pour ajouter nos modèles dans l’interface d’administration, nous devons créer une classe de type ModelAdmin par modèle. Chaque classe embarquera des options et des méthodes propres à l’admin. Par convention, on placera ces classes dans un module admin.py dans le répertoire de l’application. N’hésitez pas à consulter la section The Django admin site de la documentation pour en savoir plus.

Créez le fichier admin.py dans le répertoire blog.

Nos classes admin :

# -*- coding: utf-8 -*-
"""
Administration interface options of ``blog`` application.
"""
from django.contrib import admin

from website.apps.blog.models import Category
from website.apps.blog.models import Entry


class CategoryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Category`` model.
    """
    pass


class EntryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Entry`` model.
    """
    pass


admin.site.register(Category, CategoryAdmin)
admin.site.register(Entry, EntryAdmin)

Pour l’instant, on se contente du minimum. Il est possible de presque tout personnaliser. Nous allons quand même améliorer un peu. Voici une version un peu plus peaufinée :

# -*- coding: utf-8 -*-
"""
Administration interface options of ``blog`` application.
"""
from django.contrib import admin
from django.utils.translation import ugettext_lazy as _

from website.apps.blog.models import Category
from website.apps.blog.models import Entry


class CategoryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Category`` model.
    """
    list_display = ('name', 'slug', 'creation_date', 'modification_date')
    search_fields = ('name',)
    date_hierarchy = 'creation_date'
    save_on_top = True
    prepopulated_fields = {'slug': ('name',)}


class EntryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Entry`` model.
    """
    list_display = ('title', 'category', 'status', 'author')
    search_fields = ('title', 'body')
    date_hierarchy = 'publication_date'
    fieldsets = (
        (_('Headline'), {'fields': ('author', 'title', 'slug', 'category')}),
        (_('Publication'), {'fields': ('publication_date', 'status')}),
        (_('Body'), {'fields': ('body',)}),
    )
    save_on_top = True
    radio_fields = {'status': admin.VERTICAL}
    prepopulated_fields = {'slug': ('title',)}

admin.site.register(Category, CategoryAdmin)
admin.site.register(Entry, EntryAdmin)

Maintenant qu’on peut créer des billets et des catégories, nous allons en profiter pour créer des fixtures pour nos tests. Les fixtures sont des données de test.

Création des fixtures

On crée deux catégories. La première :

Titre : Test
Slug : test

La seconde :

Titre : Offline
Slug : offline

Et deux billets. Le premier :

Titre : Test Entry
Slug : test-entry
Catégorie : Test
Date de publication : 2010-07-21 00:00:00
Statut : en ligne
Corps : peu importe, ce que vous voulez

Le second :

Titre : Offline
Slug : offline-entry
Catégorie : Offline
Date de publication : 2010-07-21 00:00:00
Statut : hors ligne
Corps : peu importe, ce que vous voulez

Une fois ces données sauvegardées, on va les exporter au format JSON pour pouvoir les réutiliser automatiquement dans nos tests.

Créons tout d’abord un répertoire fixtures dans le répertoire de l’application.

Puis, exécutez cette commande à la racine du projet :

$ python manage.py dumpdata blog --indent=4 > apps/blog/fixtures/test_data.json

Nos fixtures sont prêtes. Passons aux URLs.

Création des URLs

Nous n’avons même pas besoin de créer de vue pour notre application puisque nous allons utiliser les vues génériques de Django. N’hésitez pas à consulter les sections Generic Views et URL dispatcher de la documentation pour en savoir plus.

Par convention, les URLs seront contenues dans le module urls.py dans le répertoire de l’application (ce fichier n’existe pas, donc pensez à le créer).

Nos URLs :

# -*- coding: utf-8 -*-
"""
URLs of ``blog`` application.
"""
from django.conf.urls.defaults import *

from website.apps.blog.models import Entry
from website.apps.blog.models import Category


urlpatterns = patterns('',
    url(r'^(?P\d{4})/(?P\d{2})/(?P\d{2})/(?P[\w-]+)/$',
        'django.views.generic.date_based.object_detail',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
            slug_field='slug',
        ),
        name='blog_entry',
    ),
    url(r'^(?P\d{4})/(?P\d{2})/(?P\d{2})/$',
        'django.views.generic.date_based.archive_day',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
        ),
        name='blog_day',
    ),
    url(r'^(?P\d{4})/(?P\d{2})/$',
        'django.views.generic.date_based.archive_month',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
        ),
        name='blog_month',
    ),
    url(r'^(?P\d{4})/$',
        'django.views.generic.date_based.archive_year',
        dict(
            queryset=Entry.online_objects.all(),
            make_object_list=True,
            date_field='publication_date',
        ),
        name='blog_year',
    ),
    url(r'^category/(?P[\w-]+)/$',
        'django.views.generic.list_detail.object_detail',
        dict(
            queryset=Category.online_objects.all(),
            slug_field='slug'
        ),
        name='blog_category',
    ),
    url(r'^$',
        'django.views.generic.date_based.archive_index',
        dict(
            queryset=Entry.online_objects.all(),
            date_field='publication_date',
        ),
        name='blog',
    ),
)

Notre projet n’est pas encore au courant de ces URLs. Éditez le fichier urls.py à la racine du projet et ajoutez le module via la fonction include :

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()


urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),
    (r'', include('website.apps.blog.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    (r'^admin/', include(admin.site.urls)),

)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

Relançons nos tests :

$ python manage.py test

Ça ne passe toujours pas mais vous avez certainement remarqué que les erreurs sont différentes. Vous ne devriez voir que des erreurs de templates. Il y a donc une progression !

Passons à la création des templates.

Création des templates

Nous allons, dans un premier temps, créer uniquement des templates vides. Puis, nous relancerons nos tests pour vérifier si ils passent bien à présent. Il restera alors juste à remplir les templates pour afficher les données.

On se place à la racine du projet et on crée les fichiers :

$ mkdir templates/layout
$ mkdir templates/blog
$ touch templates/layout/base.html
$ touch templates/blog/entry_detail.html
$ touch templates/blog/category_detail.html
$ touch templates/blog/entry_archive.html
$ touch templates/blog/entry_archive_year.html
$ touch templates/blog/entry_archive_month.html
$ touch templates/blog/entry_archive_day.html
$ touch templates/404.html
$ touch templates/500.html

Relançons les tests :

$ python manage.py test

Nos tests passent ! Nous devons maintenant remplir ces templates.

Fichier templates/layout/base.html :



    
        {% block title %}{% endblock title %} - Django Blog
        
        
    
    
        
            Django Blog
        
        
            {% block content %}{% endblock content %}

Fichier templates/404.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "404 Not Found" %}{% endblock title %}
{% block content %}
    {% trans "404 Not Found" %}
{% endblock content %}

Fichier templates/500.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "error 500" %}{% endblock title %}
{% block content %}
    {% trans "Error 500" %}
{% endblock content %}

Fichier templates/blog/entry_archive.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "Latest entries" %}{% endblock title %}
{% block content %}
{% trans "Latest entries" %}
{% if latest %}
    {% for entry in latest %}
    
        {{ entry.title }}
        
            {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
            {{ entry.category.name }}
        
        
            {{ entry.body|safe }}
        
    
    {% endfor %}
{% else %}
    {% trans "No entry yet" %}.
{% endif %}
{% endblock content %}

Fichier templates/blog/entry_archive_year.html :

{% extends "layout/base.html" %}
{% block title %}{{ year }}{% endblock title %}
{% block content %}
{{ year }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_archive_month.html :

{% extends "layout/base.html" %}
{% block title %}{{ month|date:"Y/m" }}{% endblock title %}
{% block content %}
{{ month|date:"Y/m" }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_archive_day.html :

{% extends "layout/base.html" %}
{% block title %}{{ day|date:"Y/m/d" }}{% endblock title %}
{% block content %}
{{ day|date:"Y/m/d" }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_detail.html :

{% extends "layout/base.html" %}
{% block title %}{{ object.title }}{% endblock title %}
{% block content %}

    {{ object.title }}
    
        {{ object.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ object.category.name }}
    
    
        {{ object.body|safe }}
    

{% endblock content %}

Fichier templates/blog/category_detail.html :

{% extends "layout/base.html" %}
{% block title %}{{ object.name }}{% endblock title %}
{% block content %}
{{ object.name }}

    {% for entry in object.entry_set.all %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Dans ce dernier template, object.entry_set.all récupére tous les billets liés à cette catégorie. Et oui, tous. Y compris les billets hors ligne. Le plus simple est donc de créer une propriété dans le modèle Category pour ne récupérer que les billets en ligne :

class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    objects = models.Manager()
    online_objects = CategoryOnlineManager()

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })

    def _get_online_entries(self):
        """
        Returns entries in this category with status of "online".
        Access this through the property ``online_entry_set``.
        """
        from website.apps.blog.models import Entry
        return self.entry_set.filter(status=Entry.STATUS_ONLINE)

    online_entry_set = property(_get_online_entries)

Voici la nouvelle version du template :

{% extends "layout/base.html" %}
{% block title %}{{ object.name }}{% endblock title %}
{% block content %}
{{ object.name }}

    {% for entry in object.online_entry_set.all %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Nos templates sont en place. C’est très rustre mais c’est un exemple d’application.

Qu’avons-nous oublié ? Mais oui, bien sûr, les fils RSS ! Un blog sans fils RSS n’est pas un blog. C’est indispensable. Heureusement, Django nous permet d’ajouter cette fonctionnalité en moins de deux minutes. Voyons comment procéder.

Ajout des fils RSS

Django embarque une application pour la génération de fils RSS. N’hésitez pas à consulter la section The syndication feed framework de la documentation pour en savoir plus. Difficile de faire plus simple et efficace.

Commençons par écrire nos tests. Ajoutons les méthodes test_rss_entries et test_rss_category à notre module test.py, placé dans le répertoire de l’application :

def test_rss_entries(self):
    """
    Tests entries RSS feed.
    """
    blog_url = reverse('blog')
    url = u'%sfeed/rss/entries/' % blog_url
    response = self.client.get(url)
    self.failUnlessEqual(response.status_code, 200)

def test_rss_category(self):
    """
    Tests categories RSS feed.
    """
    from website.apps.blog.models import Category
    categories = Category.online_objects.all()
    blog_url = reverse('blog')
    for category in categories:
        url = u'%sfeed/rss/category/%s/' % (blog_url, category.slug)
        response = self.client.get(url)
        self.failUnlessEqual(response.status_code, 200)

Dans notre application blog, créons un module feeds.py. Dans ce module, plaçons nos classes de syndication :

# -*- coding: utf-8
"""
Feeds of ``blog`` application.
"""
from django.utils.feedgenerator import Rss201rev2Feed
from django.utils.translation import ugettext_lazy as _
from django.core.exceptions import ObjectDoesNotExist
from django.core.urlresolvers import reverse

from django.contrib.syndication import feeds
from django.contrib.sites.models import Site

from website.apps.blog.models import Entry
from website.apps.blog.models import Category


class RssEntries(feeds.Feed):
    """
    RSS entries.
    """
    feed_type = Rss201rev2Feed
    title_template = "blog/feeds/entry_title.html"
    description_template = "blog/feeds/entry_description.html"

    def title(self):
        """
        Channel title.
        """
        site = Site.objects.get_current()
        return _('%(site_name)s: RSS entries') % {
            'site_name': site.name,
        }

    def description(self):
        """
        Channel description.
        """
        site = Site.objects.get_current()
        return _('RSS feed of recent entries posted on %(site_name)s.') % {
            'site_name': site.name,
        }

    def link(self):
        """
        Channel link.
        """
        return reverse('blog')

    def items(self):
        """
        Channel items.
        """
        return Entry.online_objects.order_by('-publication_date')[:10]

    def item_pubdate(self, item):
        """
        Channel item publication date.
        """
        return item.publication_date


class RssCategory(RssEntries):
    """
    RSS category.
    """
    def title(self, obj):
        """
        Channel title.
        """
        site = Site.objects.get_current()
        return _('%(site_name)s: RSS %(category)s category') % {
            'site_name': site.name,
            'category': obj.name,
        }

    def description(self, obj):
        """
        Channel description.
        """
        site = Site.objects.get_current()
        return _('RSS feed of recent entries posted in the category %(category)s on %(site_name)s.') % {
            'category': obj.name,
            'site_name': site.name,
        }

    def link(self, obj):
        """
        Channel link.
        """
        return reverse('blog_category', args=[obj.slug])

    def get_object(self, bits):
        """
        Object: the Category.
        """
        if len(bits) != 1:
            raise ObjectDoesNotExist
        return Category.online_objects.get(slug=bits[0])

    def items(self, obj):
        """
        Channel items.
        """
        return obj.online_entry_set

    def item_pubdate(self, item):
        """
        Channel item publication date.
        """
        return item.publication_date

Dans le module urls.py de l’application blog, ajoutons le support des fils RSS :

"""
URLs of blog application.
"""
from django.conf.urls.defaults import *

from website.apps.blog.models import Entry
from website.apps.blog.models import Category

from website.apps.blog.feeds import RssEntries
from website.apps.blog.feeds import RssCategory


rss_feeds = {
    'entries': RssEntries,
    'category': RssCategory,
}

urlpatterns = patterns('',
    url(r'^feed/rss/(?P.*)/$',
        'django.contrib.syndication.views.feed', {
            'feed_dict': rss_feeds,
        },
        name='blog_rss_feed',
    ),
    ...
)

Il ne reste plus qu’à créer les templates :

$ mkdir templates/blog/feeds
$ touch templates/blog/feeds/entry_title.html
$ touch templates/blog/feeds/entry_description.html

Le template templates/blog/feeds/entry_title.html :

{{ obj.title }}

Le template templates/blog/feeds/entry_description.html :

{{ obj.body|safe }}

Lançons les tests pour vérifier si tout est OK:

python manage.py test

Vous ne devriez pas rencontrer d’erreur.

Lancez le serveur:

python manage.py runserver

Dans votre navigateur, allez à ces adresses:

Vous devriez voir les fils. Merci Django !

Conclusion

Cet exemple d’application Django est un blog simpliste, basique, lambda. Moult fonctionnalités ont été volontairement omises (formatage du contenu des billets avec une syntaxe wiki, gestion multi-catégories, support des tags, support du format Atom pour les fils de syndication, amélioration de l’interface d’administration, amélioration des templates à l’aide d’includes, support des commentaires, ajout d’une barre de navigation… ) pour ne pas transformer ce tutoriel en ouvrage technique. La documentation de Django est complète et claire. N’hésitez pas à la consulter au moindre problème.

Télécharger le source de l’application.

Créer un blog avec Django

2009-01-29T00:00:00.000Z

Brièvement, cela se résume à :

Python (interpréteur, libraires… )
Un gestionnaire de bases de données et son binding
Un terminal (ou “console”)
Un navigateur web
Un éditeur de texte

Si vous désirez installer Django sur votre machine, n’hésitez pas à consulter la section Quick install guide de la documentation.

Mise en place du projet

Dans ce tutorial, nous allons utiliser MySQL comme gestionnaire de bases de données mais vous pouvez utiliser n’importe quel autre gestionnaire de bases de données supporté par Django.

Il faut donc, tout d’abord, créer une base de données :

$ mysql -u user -p
mysql> CREATE DATABASE blog;

mysql> GRANT ALL ON blog.* TO blog@localhost IDENTIFIED BY 'password';
mysql> FLUSH PRIVILEGES;
mysql> \q

Bien sûr, remplacez password par un vrai mot de passe.

Notre base est créée.

Dans un dossier de votre répertoire personnel (si possible, dans un dossier dédié à vos projets de programmation), nous allons créer le projet Django website et l’application blog :

$ django-admin startproject website
$ cd website
$ django-admin startapp blog

Dans le répertoire du projet website, nous allons créer un dossier templates (qui contiendra nos templates) et un dossier media qui contiendra les fichiers statiques :

$ mkdir templates
$ mkdir media

Pour bien séparer nos applications, nous allons les placer dans un répertoire apps à la racine du projet :

$ mkdir apps
$ touch apps/__init__.py
$ mv blog apps/

La commande tree devrait retourner cette arborescence :

.
|-- __init__.py
|-- apps
|   |-- __init__.py
|   `-- blog
|       |-- __init__.py
|       |-- models.py
|       `-- views.py
|-- manage.py
|-- media
|-- settings.py
|-- templates
`-- urls.py

Le projet est en place. Exécutez la commande suivante :

$ python manage.py runserver

Dans votre navigateur, pointez l’adresse : http://127.0.0.1:8000.

Bienvenue sous Django ! Control + C pour stopper le serveur.

Paramètres et URLs

Éditez le fichier settings.py à l’aide de votre éditeur favori.

Tout d’abord, on crée la constante PROJECT_PATH (en haut du fichier) afin de stocker le chemin absolu vers notre projet :

import os.path
PROJECT_PATH = os.path.dirname(os.path.abspath(__file__))

C’est pratique si vous utilisez différents systèmes d’exploitation ou différentes machines. Le chemin est automatiquement détecté.

Ensuite, on passe à la base de données :

DATABASE_ENGINE = 'mysql'
DATABASE_NAME = 'blog'
DATABASE_USER = 'blog'
DATABASE_PASSWORD = 'password'

On ajuste la timezone :

TIME_ZONE = 'Europe/Paris'

On ajuste la langue par défaut :

LANGUAGE_CODE = 'fr-fr'

On ajoute notre répertoire media :

MEDIA_ROOT = os.path.join(PROJECT_PATH, 'media/')

On ajoute l’URL vers les médias :

MEDIA_URL = '/media/'

On ajuste l’URL vers les médias de l’interface d’administration :

ADMIN_MEDIA_PREFIX = '/media/admin/'

On ajoute notre répertoire templates :

TEMPLATE_DIRS = (
    os.path.join(PROJECT_PATH, 'templates'),
)

On ajoute notre application blog à la liste INSTALLED_APPS :

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'website.apps.blog',
)

On enregistre les modifications et on passe aux URLs.

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
# from django.contrib import admin
# admin.autodiscover()

urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    # (r'^admin/(.*)', admin.site.root),
)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

On enregistre les modifications et on passe à l’installation de l’interface d’administration.

Installation de l’interface d’administration

Éditez le fichier settings.py et ajoutez django.contrib.admin dans la liste INSTALLED_APPS :

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',
    'website.apps.blog',
)

Enregistrez les modifications.

Éditez le fichier urls.py et ajoutez le support de l’admin en décommentant les lignes indiquées dans les commentaires, soit trois lignes au total :

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()

urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    (r'^admin/(.*)', admin.site.root),
)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve', {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

Enregistrez les modifications.

Il ne reste plus qu’à synchroniser avec la base de données (à exécuter à la racine du projet) :

$ python manage.py syncdb

Django vous guidera dans la création d’un compte super-utilisateur.

Lancez le serveur :

$ python manage.py runserver

Écriture des tests

# -*- coding: utf-8 -*-
from django.test import TestCase

class BlogTest(TestCase):
    pass

On lance les tests (à exécuter à la racine du projet) :

$ python manage.py test
Creating test database...
Creating table auth_permission
Creating table auth_group
Creating table auth_user
Creating table auth_message
Creating table django_content_type
Creating table django_session
Creating table django_site
Creating table django_admin_log
Installing index for auth.Permission model
Installing index for auth.Message model
Installing index for admin.LogEntry model
................
----------------------------------------------------------------------
Ran 16 tests in 2.134s

OK
Destroying test database...

Tous les tests passent ! Normal, nous n’en avons écrit aucun. Au boulot !

Notre classe de test :

# -*- coding: utf-8 -*-
from django.test import TestCase
from django.core.urlresolvers import reverse

class BlogTest(TestCase):
    """
    Tests of ``blog`` application.
    """
    fixtures = ['test_data']

    def test_entry_archive_index(self):
        """
        Tests ``entry_archive`` view.
        """
        response = self.client.get(reverse('blog'))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive.html')

    def test_entry_archive_year(self):
        """
        Tests ``entry_archive_year`` view.
        """
        response = self.client.get(reverse('blog_year', args=['2009']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_year.html')

    def test_entry_archive_month(self):
        """
        Tests ``entry_archive_month``view.
        """
        response = self.client.get(reverse('blog_month', args=['2009', '01']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_month.html')

    def test_entry_archive_day(self):
        """
        Tests ``entry_archive_day`` view.
        """
        response = self.client.get(reverse('blog_day', args=['2009', '01', '28']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_archive_day.html')

    def test_entry_detail(self):
        """
        Tests ``entry_detail`` view.
        """
        response = self.client.get(reverse('blog_entry', args=['2009', '01', '28', 'test-entry']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/entry_detail.html')

    def test_entry_detail_not_found(self):
        """
        Test ``entry_detail`` view with an offline entry.
        """
        response = self.client.get(reverse('blog_entry', args=['2009', '01', '28', 'offline-entry']))
        self.failUnlessEqual(response.status_code, 404)

    def test_category_detail(self):
        """
        Tests ``category_detail`` view.
        """
        response = self.client.get(reverse('blog_category', args=['test']))
        self.failUnlessEqual(response.status_code, 200)
        self.assertTemplateUsed(response, 'blog/category_detail.html')

    def test_category_detail_not_found(self):
        """
        Tests ``category_detail`` view with an offline category.
        """
        response = self.client.get(reverse('blog_category', args=['offline']))
        self.failUnlessEqual(response.status_code, 404)

Création des modèles

Un billet est composé des champs suivants :

Un titre
Un slug (aussi appelé “permalien”)
Un auteur
Une catégorie
Une date de création
Une date de modification
Une date de publication
Un statut (en ligne / hors ligne)
Un corps au format HTML

Une categorie est composée des champs suivants :

Un nom
Un slug (aussi appelé “permalien”)
Une date de création
Une date de modification

Nos modèles :

# -*- coding: utf-8 -*-
"""
Models of ``blog`` application.
"""
from datetime import datetime

from django.db import models
from django.utils.translation import ugettext_lazy as _

class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })

class Entry(models.Model):
    """
    A blog entry.
    """
    STATUS_OFFLINE = 0
    STATUS_ONLINE = 1
    STATUS_DEFAULT = STATUS_OFFLINE
    STATUS_CHOICES = (
        (STATUS_OFFLINE, _('Offline')),
        (STATUS_ONLINE, _('Online')),
    )

    title = models.CharField(_('title'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique_for_date='publication_date')
    author = models.ForeignKey('auth.User', verbose_name=_('author'))
    category = models.ForeignKey(Category, verbose_name=_('category'))
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)
    publication_date = models.DateTimeField(_('publication date'), default=datetime.now(), db_index=True)
    status = models.IntegerField(_('status'), choices=STATUS_CHOICES, default=STATUS_DEFAULT, db_index=True)
    body = models.TextField(_('body'))

    class Meta:
        verbose_name = _('entry')
        verbose_name_plural = _('entries')

    def __unicode__(self):
        return u'%s' % self.title

    @models.permalink
    def get_absolute_url(self):
        return ('blog_entry', (), {
            'year': self.publication_date.strftime('%Y'),
            'month': self.publication_date.strftime('%m'),
            'day': self.publication_date.strftime('%d'),
            'slug': self.slug,
        })

La syntaxe du langage Python est tellement clean que le code parle de lui-même.

Nos modèles sont i18n-ready (via la fonction magique _()).

Avant de créer nos tables, il est recommandé de vérifier si les modèles ne comportent aucune erreur. Pour ce faire, à la racine du projet, on exécute la commande suivante :

$ python manage.py validate
0 errors found

Si cette commande renvoie des erreurs, il suffira de les corriger.

Tout est OK. On synchronise avec la base de données:

$ python manage.py syncdb
Creating table blog_category
Creating table blog_entry
Installing index for blog.Entry model

Nos managers :

# -*- coding: utf-8 -*-
"""
Managers of ``blog`` application.
"""
from django.db import models

class CategoryOnlineManager(models.Manager):
    """
    Manager that manages online ``Category`` objects.
    """

    def get_query_set(self):
        from website.apps.blog.models import Entry
        entry_status = Entry.STATUS_ONLINE
        return super(CategoryOnlineManager, self).get_query_set().filter(
            entry__status=entry_status).distinct()

class EntryOnlineManager(models.Manager):
    """
    Manager that manages online ``Entry`` objects.
    """

    def get_query_set(self):
        return super(EntryOnlineManager, self).get_query_set().filter(
            status=self.model.STATUS_ONLINE)

Il faut maintenant ajouter ces managers dans nos modèles :

# -*- coding: utf-8 -*-
"""
Models of ``blog`` application.
"""
from datetime import datetime

from django.db import models
from django.utils.translation import ugettext_lazy as _

from website.apps.blog.managers import CategoryOnlineManager
from website.apps.blog.managers import EntryOnlineManager

class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    objects = models.Manager()
    online_objects = CategoryOnlineManager()

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })

class Entry(models.Model):
    """
    A blog entry.
    """
    STATUS_OFFLINE = 0
    STATUS_ONLINE = 1
    STATUS_DEFAULT = STATUS_OFFLINE
    STATUS_CHOICES = (
        (STATUS_OFFLINE, _('Offline')),
        (STATUS_ONLINE, _('Online')),
    )

    title = models.CharField(_('title'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique_for_date='publication_date')
    author = models.ForeignKey('auth.User', verbose_name=_('author'))
    category = models.ForeignKey(Category, verbose_name=_('category'))
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)
    publication_date = models.DateTimeField(_('publication date'), default=datetime.now(), db_index=True)
    status = models.IntegerField(_('status'), choices=STATUS_CHOICES, default=STATUS_DEFAULT, db_index=True)
    body = models.TextField(_('body'))

    objects = models.Manager()
    online_objects = EntryOnlineManager()

    class Meta:
        verbose_name = _('entry')
        verbose_name_plural = _('entries')

    def __unicode__(self):
        return u'%s' % self.title

    @models.permalink
    def get_absolute_url(self):
        return ('blog_entry', (), {
            'year': self.publication_date.strftime('%Y'),
            'month': self.publication_date.strftime('%m'),
            'day': self.publication_date.strftime('%d'),
            'slug': self.slug,
        })

Ajout des modèles dans l’interface d’administration

Créez le fichier admin.py dans le répertoire blog.

Nos classes admin :

# -*- coding: utf-8 -*-
"""
Administration interface options of ``blog`` application.
"""
from django.contrib import admin

from website.apps.blog.models import Category
from website.apps.blog.models import Entry

class CategoryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Category`` model.
    """
    pass

class EntryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Entry`` model.
    """
    pass

admin.site.register(Category, CategoryAdmin)
admin.site.register(Entry, EntryAdmin)

Pour l’instant, on se contente du minimum. Il est possible de presque tout personnaliser. Nous allons quand même améliorer un peu. Voici une version un peu plus peaufinée :

# -*- coding: utf-8 -*-
"""
Administration interface options of ``blog`` application.
"""
from django.contrib import admin
from django.utils.translation import ugettext_lazy as _

from website.apps.blog.models import Category
from website.apps.blog.models import Entry

class CategoryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Category`` model.
    """
    list_display = ('name', 'slug', 'creation_date', 'modification_date')
    search_fields = ('name',)
    date_hierarchy = 'creation_date'
    save_on_top = True
    prepopulated_fields = {'slug': ('name',)}

class EntryAdmin(admin.ModelAdmin):
    """
    Administration interface options of ``Entry`` model.
    """
    list_display = ('title', 'category', 'status', 'author')
    search_fields = ('title', 'body')
    date_hierarchy = 'publication_date'
    fieldsets = (
        (_('Headline'), {'fields': ('author', 'title', 'slug', 'category')}),
        (_('Publication'), {'fields': ('publication_date', 'status')}),
        (_('Body'), {'fields': ('body',)}),
    )
    save_on_top = True
    radio_fields = {'status': admin.VERTICAL}
    prepopulated_fields = {'slug': ('title',)}

admin.site.register(Category, CategoryAdmin)
admin.site.register(Entry, EntryAdmin)

Maintenant qu’on peut créer des billets et des catégories, nous allons en profiter pour créer des fixtures pour nos tests. Les fixtures sont des données de test.

Création des fixtures

On crée deux catégories. La première :

Titre : Test
Slug : test

La seconde :

Titre : Offline
Slug : offline

Et deux billets. Le premier :

Titre : Test Entry
Slug : test-entry
Catégorie : Test
Date de publication : 2009-01-28 00:00:00
Statut : en ligne
Corps : peu importe, ce que vous voulez

Le second :

Titre : Offline
Slug : offline-entry
Catégorie : Offline
Date de publication : 2009-01-28 00:00:00
Statut : hors ligne
Corps : peu importe, ce que vous voulez

Une fois ces données sauvegardées, on va les exporter au format JSON pour pouvoir les réutiliser automatiquement dans nos tests.

Créons tout d’abord un répertoire fixtures dans le répertoire de l’application.

Puis, exécutez cette commande à la racine du projet :

$ python manage.py dumpdata blog --indent=4 > apps/blog/fixtures/test_data.json

Nos fixtures sont prêtes. Passons aux URLs.

Création des URLs

Par convention, les URLs seront contenues dans le module urls.py dans le répertoire de l’application (ce fichier n’existe pas, donc pensez à le créer).

Nos URLs :

# -*- coding: utf-8 -*-
"""
URLs of ``blog`` application.
"""
from django.conf.urls.defaults import *

from website.apps.blog.models import Entry
from website.apps.blog.models import Category

urlpatterns = patterns('',
    url(r'^(?P\d{4})/(?P\d{2})/(?P\d{2})/(?P[\w-]+)/$',
        'django.views.generic.date_based.object_detail',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
            slug_field='slug',
        ),
        name='blog_entry',
    ),
    url(r'^(?P\d{4})/(?P\d{2})/(?P\d{2})/$',
        'django.views.generic.date_based.archive_day',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
        ),
        name='blog_day',
    ),
    url(r'^(?P\d{4})/(?P\d{2})/$',
        'django.views.generic.date_based.archive_month',
        dict(
            queryset=Entry.online_objects.all(),
            month_format='%m',
            date_field='publication_date',
        ),
        name='blog_month',
    ),
    url(r'^(?P\d{4})/$',
        'django.views.generic.date_based.archive_year',
        dict(
            queryset=Entry.online_objects.all(),
            make_object_list=True,
            date_field='publication_date',
        ),
        name='blog_year',
    ),
    url(r'^category/(?P[\w-]+)/$',
        'django.views.generic.list_detail.object_detail',
        dict(
            queryset=Category.online_objects.all(),
            slug_field='slug'
        ),
        name='blog_category',
    ),
    url(r'^$',
        'django.views.generic.date_based.archive_index',
        dict(
            queryset=Entry.online_objects.all(),
            date_field='publication_date',
        ),
        name='blog',
    ),
)

Notre projet n’est pas encore au courant de ces URLs. Éditez le fichier urls.py à la racine du projet et ajoutez le module via la fonction include :

from django.conf.urls.defaults import *
from django.conf import settings

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()

urlpatterns = patterns('',
    # Example:
    # (r'^website/', include('website.foo.urls')),
    (r'', include('website.apps.blog.urls')),

    # Uncomment the admin/doc line below and add 'django.contrib.admindocs'
    # to INSTALLED_APPS to enable admin documentation:
    # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    (r'^admin/(.*)', admin.site.root),
)

urlpatterns += patterns('',
    (r'^media/(?P.*)$',
        'django.views.static.serve',
        {
            'document_root': settings.MEDIA_ROOT,
            'show_indexes': True,
        },
    ),
)

Relançons nos tests :

$ python manage.py test

Ça ne passe toujours pas mais vous avez certainement remarqué que les erreurs sont différentes. Vous ne devriez voir que des erreurs de templates. Il y a donc une progression !

Passons à la création des templates.

Création des templates

On se place à la racine du projet et on crée les fichiers :

$ mkdir templates/layout
$ mkdir templates/blog
$ touch templates/layout/base.html
$ touch templates/blog/entry_detail.html
$ touch templates/blog/category_detail.html
$ touch templates/blog/entry_archive.html
$ touch templates/blog/entry_archive_year.html
$ touch templates/blog/entry_archive_month.html
$ touch templates/blog/entry_archive_day.html
$ touch templates/404.html
$ touch templates/500.html

Relançons les tests :

$ python manage.py test

Nos tests passent ! Nous devons maintenant remplir ces templates.

Fichier templates/layout/base.html :



    
        {% block title %}{% endblock title %} - Django Blog
        
        
    
    
        
            Django Blog
        
        
            {% block content %}{% endblock content %}

Fichier templates/404.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "404 Not Found" %}{% endblock title %}
{% block content %}
    {% trans "404 Not Found" %}
{% endblock content %}

Fichier templates/500.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "error 500" %}{% endblock title %}
{% block content %}
    {% trans "Error 500" %}
{% endblock content %}

Fichier templates/blog/entry_archive.html :

{% extends "layout/base.html" %}
{% load i18n %}
{% block title %}{% trans "Latest entries" %}{% endblock title %}
{% block content %}
{% trans "Latest entries" %}
{% if latest %}
    {% for entry in latest %}
    
        {{ entry.title }}
        
            {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
            {{ entry.category.name }}
        
        
            {{ entry.body|safe }}
        
    
    {% endfor %}
{% else %}
    {% trans "No entry yet" %}.
{% endif %}
{% endblock content %}

Fichier templates/blog/entry_archive_year.html :

{% extends "layout/base.html" %}
{% block title %}{{ year }}{% endblock title %}
{% block content %}
{{ year }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_archive_month.html :

{% extends "layout/base.html" %}
{% block title %}{{ month|date:"Y/m" }}{% endblock title %}
{% block content %}
{{ month|date:"Y/m" }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_archive_day.html :

{% extends "layout/base.html" %}
{% block title %}{{ day|date:"Y/m/d" }}{% endblock title %}
{% block content %}
{{ day|date:"Y/m/d" }}

    {% for entry in object_list %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Fichier templates/blog/entry_detail.html :

{% extends "layout/base.html" %}
{% block title %}{{ object.title }}{% endblock title %}
{% block content %}

    {{ object.title }}
    
        {{ object.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ object.category.name }}
    
    
        {{ object.body|safe }}
    

{% endblock content %}

Fichier templates/blog/category_detail.html :

{% extends "layout/base.html" %}
{% block title %}{{ object.name }}{% endblock title %}
{% block content %}
{{ object.name }}

    {% for entry in object.entry_set.all %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

class Category(models.Model):
    """
    A blog category.
    """
    name = models.CharField(_('name'), max_length=255)
    slug = models.SlugField(_('slug'), max_length=255, unique=True)
    creation_date = models.DateTimeField(_('creation date'), auto_now_add=True)
    modification_date = models.DateTimeField(_('modification date'), auto_now=True)

    objects = models.Manager()
    online_objects = CategoryOnlineManager()

    class Meta:
        verbose_name = _('category')
        verbose_name_plural = _('categories')

    def __unicode__(self):
        return u'%s' % self.name

    @models.permalink
    def get_absolute_url(self):
        return ('blog_category', (), {
            'slug': self.slug,
        })

    def _get_online_entries(self):
        """
        Returns entries in this category with status of "online".
        Access this through the property ``online_entry_set``.
        """
        from website.apps.blog.models import Entry
        return self.entry_set.filter(status=Entry.STATUS_ONLINE)

    online_entry_set = property(_get_online_entries)

Voici la nouvelle version du template :

{% extends "layout/base.html" %}
{% block title %}{{ object.name }}{% endblock title %}
{% block content %}
{{ object.name }}

    {% for entry in object.online_entry_set.all %}
    
        {{ entry.title }} |
        
        {{ entry.publication_date|date:"Y/m/d @ H:i:s" }} -
        {{ entry.category.name }}
        
    
    {% endfor %}

{% endblock content %}

Nos templates sont en place. C’est très rustre mais c’est un exemple d’application.

Ajout des fils RSS

Commençons par écrire nos tests. Ajoutons les méthodes test_rss_entries et test_rss_category à notre module test.py, placé dans le répertoire de l’application :

def test_rss_entries(self):
    """
    Tests entries RSS feed.
    """
    blog_url = reverse('blog')
    url = u'%sfeed/rss/entries/' % blog_url
    response = self.client.get(url)
    self.failUnlessEqual(response.status_code, 200)

def test_rss_category(self):
    """
    Tests categories RSS feed.
    """
    from website.apps.blog.models import Category
    categories = Category.online_objects.all()
    blog_url = reverse('blog')
    for category in categories:
        url = u'%sfeed/rss/category/%s/' % (blog_url, category.slug)
        response = self.client.get(url)
        self.failUnlessEqual(response.status_code, 200)

Dans notre application blog, créons un module feeds.py. Dans ce module, plaçons nos classes de syndication :

# -*- coding: utf-8
"""
Feeds of ``blog`` application.
"""
from django.utils.feedgenerator import Rss201rev2Feed
from django.utils.translation import ugettext_lazy as _
from django.core.exceptions import ObjectDoesNotExist
from django.core.urlresolvers import reverse
from django.contrib.syndication import feeds
from django.contrib.sites.models import Site

from website.apps.blog.models import Entry
from website.apps.blog.models import Category

class RssEntries(feeds.Feed):
    """
    RSS entries.
    """
    feed_type = Rss201rev2Feed
    title_template = "blog/feeds/entry_title.html"
    description_template = "blog/feeds/entry_description.html"

    def title(self):
        """
        Channel title.
        """
        site = Site.objects.get_current()
        return _('%(site_name)s: RSS entries') % {
            'site_name': site.name,
        }

    def description(self):
        """
        Channel description.
        """
        site = Site.objects.get_current()
        return _('RSS feed of recent entries posted on %(site_name)s.') % {
            'site_name': site.name,
        }

    def link(self):
        """
        Channel link.
        """
        return reverse('blog')

    def items(self):
        """
        Channel items.
        """
        return Entry.online_objects.order_by('-publication_date')[:10]

    def item_pubdate(self, item):
        """
        Channel item publication date.
        """
        return item.publication_date

class RssCategory(RssEntries):
    """
    RSS category.
    """
    def title(self, obj):
        """
        Channel title.
        """
        site = Site.objects.get_current()
        return _('%(site_name)s: RSS %(category)s category') % {
            'site_name': site.name,
            'category': obj.name,
        }

    def description(self, obj):
        """
        Channel description.
        """
        site = Site.objects.get_current()
        return _('RSS feed of recent entries posted in the category %(category)s on %(site_name)s.') % {
            'category': obj.name,
            'site_name': site.name,
        }

    def link(self, obj):
        """
        Channel link.
        """
        return reverse('blog_category', args=[obj.slug])

    def get_object(self, bits):
        """
        Object: the Category.
        """
        if len(bits) != 1:
            raise ObjectDoesNotExist
        return Category.online_objects.get(slug=bits[0])

    def items(self, obj):
        """
        Channel items.
        """
        return obj.online_entry_set

    def item_pubdate(self, item):
        """
        Channel item publication date.
        """
        return item.publication_date

Dans le module urls.py de l’application blog, ajoutons le support des fils RSS :

"""
URLs of blog application.
"""
from django.conf.urls.defaults import *

from website.apps.blog.models import Entry
from website.apps.blog.models import Category

from website.apps.blog.feeds import RssEntries
from website.apps.blog.feeds import RssCategory

rss_feeds = {
    'entries': RssEntries,
    'category': RssCategory,
}

urlpatterns = patterns('',
    url(r'^feed/rss/(?P.*)/$',
        'django.contrib.syndication.views.feed', {
            'feed_dict': rss_feeds,
        },
        name='blog_rss_feed',
    ),
    ...
)

Il ne reste plus qu’à créer les templates :

$ mkdir templates/blog/feeds
$ touch templates/blog/feeds/entry_title.html
$ touch templates/blog/feeds/entry_description.html

Le template templates/blog/feeds/entry_title.html :

{{ obj.title }}

Le template templates/blog/feeds/entry_description.html :

{{ obj.body|safe }}

Lançons les tests pour vérifier si tout est OK:

python manage.py test

Vous ne devriez pas rencontrer d’erreur.

Lancez le serveur:

python manage.py runserver

Dans votre navigateur, allez à ces adresses:

Vous devriez voir les fils. Merci Django !

Conclusion

Cet exemple d’application Django est un blog simpliste, basique, lambda. Moult fonctionnalités ont été volontairement omises (formatage du contenu des billets avec une syntaxe wiki, gestion multi-catégories, support des tags, support du format Atom pour les fils de syndication, amélioration de l’interface d’administration, amélioration des templates à l’aide d’includes, support des commentaires, ajout d’une sidebar… ) pour ne pas transformer ce tutorial en ouvrage technique. La documentation de Django est complète et claire. N’hésitez pas à la consulter au moindre problème.

Télécharger le source de l’application.