larlet-fr-david/david/biologeek/archives/20080211-astuces-et-bonnes-pratiques-django/article.md

title:      ★ Astuces et bonnes pratiques Django
slug:       astuces-et-bonnes-pratiques-django
date:       2008-02-11 02:14:05
type:       post
vignette:   images/logos/django.png
contextual_title1:  ★ Django-ROA, pour une architecture orientée ressources
contextual_url1:    20090526-django-roa-pour-une-architecture-orientee-ressources
contextual_title2:  Sortie de Django 1.0, une année de nouveautés
contextual_url2:    20080902-sortie-de-django-10-une-annee-de-nouveautes
contextual_title3:  ★ Découvrons OAuth avec mixin (et django-oauth)
contextual_url3:    20080713-decouvrons-oauth-avec-mixin-et-django-oauth

<p>Développant avec <a href="http://www.django-fr.org/">Django</a> depuis maintenant près de deux ans (ça rajeunit pas tout ça...), je suis encore surpris de découvrir de nouvelles possibilités de temps en temps. Dans mon combat pour les <a href="https://larlet.fr/david/biologeek/archives/20060121-bonnes-pratiques-de-la-programmation-en-python/">bonnes pratiques</a>, je pense qu'il y a quelques bases à avoir pour se lancer dans un projet d'envergure avec Django. Je vais essayer de lister les miennes, n'hésitez pas à ajouter les vôtres pour que ça devienne une ressource collaborative.</p>

<h2>Une arborescence de fichiers qui tient la route</h2>


<p>Je pense qu'il y a deux stratégies lorsqu'on démarre un projet&nbsp;:</p>

<ul>
<li>une seule énorme application (au sens Django du terme)&nbsp;;</li>
<li>plusieurs applications si possibles découplées.</li>
</ul>

<p>Les deux approches sont intéressantes et nécessitent de toute façon d'avoir un découpage des fichiers habituels (models, views, etc) en modules python pour s'y retrouver et un dossier de bibliothèques tierces car la réutilisation a quand même du bon. Bon ça aussi c'est discutable, certains préférant les fichiers de 3000 lignes, encore une fois ce ne sont que des conseils...</p>


<p>Au final, la structure que j'adopte maintenant est la suivante (je ne donne pas le détail des applications car il varie beaucoup en fonction du degré de <a href="https://larlet.fr/david/biologeek/archives/20070629-architecture-orientee-ressource-pour-faire-des-services-web-restful/">RESTification</a> de votre projet)&nbsp;:</p>


<pre>monsuperprojet/
  projetdjango/
    __init__.py
    manage.py
  applidjango1/
  applidjango2/
  applidjango3/
  applitierce1/
  applitierce2/</pre>


<p>De cette manière, vous n'avez qu'un seul dossier à mettre dans votre <strong>$PYTHONPATH</strong>&nbsp;: monsuperprojet et vos applications sont totalement découplées (vous n'avez jamais besoin de connaître projetdjango). Remarquez qu'il est possible de spécifier le chemin directement dans votre <strong>manage.py</strong> si vous souhaitez ne pas surcharger votre <strong>$PYTHONPATH</strong> (par exemple si vous bossez sur plusieurs projets qui ont les mêmes noms d'applis...)&nbsp;:</p>


<pre>
<code>import sys
sys.path = ['/chemin/vers/monsuperprojet'] + sys.path</code>
</pre>


<p>À ajouter bien sûr avant d'importer les settings.</p>


<p>Pour revenir à l'arborescence, je n'ai pas vraiment de bonnes pratiques pour la place des templates. Certains les séparent complètement, d'autres les mettent dans les applications. À vous de voir en fonction de vos besoins.</p>


<h2>Des fichiers statiques séparés</h2>


<p>La doc de Django recommande de gérer ses fichiers statiques à part pour gagner en performances (téléchargements en parallèle sur un autre sous-domaine, etc). Bon bien sûr c'est un peu overkill pour un blog et encore plus lorsque vous développez. Il existe une solution assez simple pour s'en sortir avec le serveur de développement&nbsp;:</p>


<pre><code>if settings.DEBUG:
    from django.views.static import serve
    urlpatterns += patterns('',
        (r'^media/(?P&lt;path&gt;.*)$',
            serve,
            dict(
                document_root = os.path.join(settings.PROJECT_PATH, 'media'),
                show_indexes = True
            )
        ),
    )</code>
</pre>


<p>avec <em>settings.PROJECT_PATH</em> défini ainsi&nbsp;:</p>


<pre><code>PROJECT_PATH = os.path.dirname(os.path.abspath(__file__))</code></pre>


<p>Puisqu'on parle des settings, n'oubliez pas qu'il faut toujours les importer avec&nbsp;:</p>


<pre><code>from django.conf import settings</code></pre>


<p>Et <strong>jamais</strong> directement de votre projet.</p>


<p>Si vous avez besoin de versionner vos fichiers (ici aussi pour les performances car il vaut mieux avoir un cache très long et un nom de fichier qui change lorsque vous mettez à jour l'application), inutile de vous casser la tête avec des <em>style.20080214.css</em> ou autres noms de fichiers barbares, le paramètre <strong>MEDIA_URL</strong> est l'unique modification à effectuer, vous pouvez par exemple le suffixer avec le numéro de révision de votre dépôt (je vous laisse jouer avec <em>django.utils.version.get_svn_revision</em>) ou la date, on obtient&nbsp;:</p>


<pre>http://media.biologeek.com/20080210/css/biologeek.css
&lt;------------ MEDIA_URL ----------&gt; &lt;--- static ----&gt;</pre>


<p><strong>[edit du 26 mars]</strong>&nbsp;: voir aussi <a href="http://www.djangosnippets.org/snippets/666/">ce snippet</a> à ce sujet.</p>


<h2>Des raccourcis biens pratiques</h2>


<p>Le système d'expressions régulières des URL de Django est très puissant. Mais il faut avouer qu'il est un peu rebutant au premier abord et qu'on a vite fait d'oublier un - ou un \+. J'ai trouvé une solution assez élégante à ça en constituant un <strong>dictionnaire d'expression régulières communément utilisées</strong> réutilisable au besoin, ça donne&nbsp;:</p>


<pre><code>import lasuperfonction

re_urls = {
    'username': '(?P&lt;username&gt;\w+)/',
    'pk_value': '(?P&lt;pk_value&gt;\d+)/',
    'foo_args': '(?P&lt;foo_args&gt;\d+)?/?',
    etc
}

urlpatterns = pattern('',
    url(r'%(username)s%(pk_value)s%(foo_args)s' % locals(), lasuperfonction)
)</code>
</pre>

<p>ce qui permet d'avoir des URL un peu plus lisibles. Au passage, deux détails&nbsp;:</p>
<ul>
<li>l'utilisation de <strong>locals()</strong> n'est pas trop coûteuse ici car les fichiers d'urls ne contiennent en théorie que des urls&nbsp;;</li>
<li>il est vraiment très puissant d'utiliser les fonctions et non leurs 'noms' car ça permet d'appliquer directement les décorateurs à ce niveau, par exemple <em>login_required(lasuperfonction)</em>.</li>
</ul>

<p>Concernant les raccourcis, il est bien pratique d'avoir ses propres fonctions de base comme <em>send_mail</em> si vous souhaitez ensuite faire de l'envoi en asynchrone ou <em>direct_to_template</em> si vous souhaitez un jour <a href="http://www.b-list.org/weblog/2007/nov/27/performance/#c36262">précompiler vos templates</a> sans avoir à modifier tous vos fichiers (<strong>[edit]</strong>&nbsp;: une <a href="http://www.djangosnippets.org/snippets/596/">solution élégante</a>) ou par exemple si vous souhaitez modifier le chemin par défaut vers lequel redirige le décorateur <em>permission_required</em>&nbsp;:</p>


<pre>from django.contrib.auth.decorators import permission_required as django_permission_required</pre>


<pre><code>def permission_required(perm):
    return django_permission_required(perm, login_url='/')</code></pre>


<p>L'avantage de Django c'est d'être totalement en Python, ce qui permet de modifier facilement les différents points bloquants au besoin :-).</p>


<h2>Des GenericForeignKey encore plus puissantes</h2>


<p>J'ai passé pas mal de temps à essayer d'utiliser deux <a href="http://www.djangoproject.com/documentation/models/generic_relations/">GenericForeignKey</a> dans un même modèle donc on peut considérer ça comme une astuce (même si ça ne doit pas concerner grand monde). Lorsqu'on en arrive à un tel modèle c'est généralement qu'il y a une grande inconnue dans le contenu qui va être stocké. C'est typiquement le cas d'un log qui doit à la fois prendre en compte un item et une position par exemple&nbsp;:</p>


<pre><code>class Log(models.Model):
    item = generic.GenericForeignKey(ct_field="item_content_type", fk_field="item_object_id")
    item_content_type = models.ForeignKey(ContentType, related_name="log_item")
    item_object_id = models.IntegerField()

    position = generic.GenericForeignKey(ct_field="position_content_type", fk_field="position_object_id")
    position_content_type = models.ForeignKey(ContentType, related_name="log_position")
    position_object_id = models.IntegerField()</code>
</pre>

<p>De cette manière, vous pouvez procéder aux requêtes habituelles&nbsp;:</p>


<pre><code>queryset = Log.objects.filter(item_content_type = user_ct, item_object_id = user_id)</code></pre>


<p>Mais aussi utiliser directement les objets pour la création&nbsp;:</p>


<pre><code>log = Log(item = user, position = last_step)</code></pre>


<p>Si vous utilisez l'interface d'administration de Django auto-générée, il peut être intéressant de créer les liens vers ces objets génériques liés. Malheureusement, on ne peut pas spécifier directement une GenericForeignKey dans <em>list_display</em>&nbsp;:</p>


<pre><code>     class Admin:
        list_display = ('item',)</code>
</pre>


<p>Il va donc falloir passer par une petite astuce, on commence par spécifier un nom de fonction&nbsp;:</p>


<pre><code>    class Admin:
        list_display = ('get_item_for_admin',)</code></pre>


<p>Puis on crée le lien vers l'objet en question&nbsp;:</p>


<pre><code>    def get_item_for_admin(self):
        url = '../../%s/%s/%s/' % ( self.item.__class__._meta.app_label,
                                    self.item.__class__._meta.module_name,
                                    self.item.id)
        return '&lt;a href="%s" title=""&gt;%s&lt;/a&gt;' % (url, self.item)
    get_item_for_admin.short_description = _('Item')
    get_item_for_admin.allow_tags = True</code>
</pre>

<p>Hop, les liens vont être disponibles pour vos GenericForeignKey.</p>


<h2>Le meilleur pour la fin</h2>


<h3>Une application non testée est une application morte-née</h3>


<p>Vraiment. <strong>La qualité d'une application devrait se mesurer au nombre de tests</strong>, sinon c'est ce que j'appelle du code poubelle. Prenez cette bonne habitude dès le début car c'est difficile d'expliquer à vos boss qu'il va falloir passer le mois prochain à ajouter des tests.</p>


<p>Heureusement, Django offre un framework vraiment intéressant pour tester vos applications alors il serait dommage de s'en passer&nbsp;! Au bout d'un moment, les tests vont devenir énormes (du moins je vous le souhaite) et prendre pas mal du temps à se lancer, ce qui va avoir pour conséquence <del>de vous faire coder directement comme un Dieu</del> de transformer la séance d'écriture des tests en corvée. N'hésitez pas à ce moment là à ne lancer qu'une partie de vos tests (s'ils sont suffisamment découplés... mais c'est le cas bien évidemment), soit en spécifiant la classe du test unitaire&nbsp;:</p>


<pre>python manage.py test users.TestAccounts</pre>


<p>soit en spécifiant le fichier de doctests sous réserve d'<a href="http://code.djangoproject.com/ticket/6364">appliquer ce patch</a>&nbsp;:</p>


<pre>python manage.py test users.emails</pre>


<h3>Parlez vous unicode&nbsp;?</h3>


<p>Il est très important aussi de penser à l'internationalisation de votre application dès le début car il est vraiment pénible de devoir repasser ensuite sur l'ensemble des chaînes pouvant être traduites (et n'oubliez pas de nommer vos fichiers de templates en <strong>.html</strong> sous peine de devoir toucher à <strong>make-message.py</strong>).</p>


<h3>Des IntegerFields pour les choix</h3>


<p>Je ne vais pas trop me fatiguer sur ce point car c'est <a href="http://www.b-list.org/weblog/2007/nov/02/handle-choices-right-way/">très bien expliqué par James Bennett</a>. C'est très important au niveau des performances et c'est très pénible à reprendre si vous n'avez pas pris la peine d'utiliser cette méthode dès le début. On ne l'oublie qu'une seule fois généralement.</p>


<h3>Des managers pour les requêtes récurrentes</h3>


<p>Ici aussi, c'est déjà traité par Jared Kuolt à <a href="http://superjared.com/entry/django-quick-tip-1-managers/">deux</a> <a href="http://superjared.com/entry/django-quick-tips-15-manager-methods/">reprises</a>. Vous avez même une solution pour <a href="http://www.djangosnippets.org/snippets/562/">enchaîner</a> ces nouvelles fonctions au besoin.</p>



<p>Une autre dernière astuce si vous avez à utiliser vos modèles Django dans un script indépendant de Django&nbsp;:</p>


<pre><code>import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'projetdjango.settings'
from django.conf import settings</code>
</pre>


<p>Vous pouvez ensuite importer vos modèles sans problème normalement.</p>


<p>Enfin, <strong>usez et abusez des ressources fournies par Django</strong> (<em>middlewares</em>, <em>context_processors</em>, <em>managers</em>, etc) et Python (<em>property</em>, <em>list-comprehension</em>, <em>decorator</em>, etc). Ce sont vos meilleurs amis... avec le cache :-).</p>


<p><strong>[edit du 20 mars]</strong>&nbsp;: après une relecture de <a href="http://python.net/~goodger/projects/pycon/2007/idiomatic/">Code Like a Pythonista</a>, j'ai découvert qu'il existait une solution plus simple que <abbr title="Decorate Sort Undecorate">DSU</abbr> pour trier plusieurs modèles Django selon un champ, par exemple la date de billets et de brèves de blog&nbsp;:</p>


<pre><code>self.items = list(Post.published.all()[:10]) + list(Thought.published.all()[:20])</code>
</pre>


<p>Voici la version originale compatible python2.3&nbsp;:</p>


<pre><code>to_sort = [(item.publication_date, item) for item in self.items]
to_sort.sort()
self.items = [item[1] for item in reversed(to_sort)]</code>
</pre>


<p>Et voici celle qui utilise l'argument <strong>key</strong> apparu à la version 2.4&nbsp;:</p>


<pre><code>self.items.sort(key=lambda item: item.publication_date, reverse=True)</code></pre>


<p>Élégant non&nbsp;?</p>


<p><strong>[edit du 26 mars]</strong>&nbsp;: Pour répondre au commentaire de Philippe&nbsp;:</p>


<blockquote><p>Une petite note sur des choses à pas faire comme dans la doc serait peut-être bienvenu&nbsp;? Comme par exemple l'histoire du auto_now_add&nbsp;?</p></blockquote>


<p>Je n'ai plus tout en tête mais effectivement rappeler que <a href="http://www.b-list.org/weblog/2006/nov/02/django-tips-auto-populated-fields/#c2637">auto_now_add est deprecated</a> ne fait pas de mal.</p>


<blockquote><p>Un petit retour d'expérience sur les migrations de schema éventuellement&nbsp;?</p></blockquote>


<p>Il n'y a pas vraiment de solution pour l'instant, ormis les grosses mises à jour du modèle c'est assez simple à faire à la main. Dès qu'on touche aux données c'est toujours assez critique donc ne pas oublier de tester sur une iso-prod avant :-).</p>


<blockquote><p>Un petit retour d'expérience sur l'utilisation du trunk pour tous tes projets (notamment la maintenance que ça engendre)&nbsp;?</p></blockquote>


<p>Le problème du trunk arrive lorsqu'on laisse un projet en sommeil quelques mois/années et qu'il faut alors tout mettre à jour d'un coup. Tant que ça reste du quotidien, les modifications sont généralement minimes donc c'est rapidement fait. Ma stratégie dans le cas d'une reprise c'est de reprendre point par point ceux listés sur la page des <a href="http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges">changements de Django</a> ce qui se fait sans douleur pour l'instant, à part pour le passage en unicode bien sûr...</p>


<p>Il ne faut pas se voiler la vérité, le web évolue toujours plus rapidement et un projet s'entretient sous peine de devenir irrécupérable. C'est presque un avantage d'être sur une version qui avance au quotidien et qui permet de conserver cette agilité. Je n'ai jamais ressenti ça comme une contrainte personnellement, je suis davantage gêné par mon propre code qui reflète ma progression&nbsp;: «&nbsp;comment j'ai fait pour coder ça comme ça il y a 6 mois ?! » ;-).</p>