Le livre de

Installer ReportLab

Avant toute génératio de PDF, cependant, vous devrez installer ReportLab. C’est généralement assez simple: il suffit de télécharger et d’installer la bibliothèque depuis http://www.reportlab.org/downloads.html.

Le guide de l’utilisateur (naturellement disponible uniquement sous forme de fichier PDF) à l’adresse http://www.reportlab.org/rsrc/userguide.pdf propose des instructions d’installation complémentaire.

>>> import reportlab

Écrire vos propres vues

Tout comme CSV, la génération dynamique de PDFs avec Django est aisée puisque l’API ReportLab se comporte comme un objet fichier.

Voici un exemple de type «Bonjour Monde»:

from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF
    headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment;
    filename=hello.pdf'

    # Create the PDF object, using the response object as its
    "file."
    p = canvas.Canvas(response)

    # Draw things on the PDF. Here's where the PDF generation
    happens.
    # See the ReportLab documentation for the full list of
    functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly, and we're done.
    p.showPage()
    p.save()
    return response

Quelques notes cependant:

• Nous utilisons ici le type MIME application/pdf. Ceci indique aux navigateurs que le document est un fichier PDF, plutôt qu’un fichier HTML. Si vous négligez cette information, les navigateur tenterons probablement d’interpréter la réponse comme du HTML, ce qui aboutira en un charabia effrayant dans la fenêtre du navigateur.
• Intéragir avec l’API de ReportLab API est facile: transmettez lui simplement la response en premier argument de canvas.Canvas. La classe Canvas attends des objets de type fichiers, et les objets HttpResponse correspondent parfaitement.
• Toutes les méthodes de génération de PDF suivantes sont appelées sur l’objet PDF (dans notre cas, p), pas sur response.
• Finallement, il est important d’appeler showPage() et save() sur le fichier PDF (ou vous obtiendrez un fichier PDF corrompu).

PDFs complexes

Si vous créez un document PDF complexe (ou tout gros blob de donnée), envisagez l’utilisation de la bibliothèque cStringIO comme endroit de stockage temporaire de votre fichier PDF. La bibliothèque cStringIO fourni une interface écrite en C pour un maximum d’efficacité.

Revoici l’exemple précédent, «Bonjour Monde», réécrit de façon à utiliser cStringIO:

from cStringIO import StringIO
from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF
    headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment;
    filename=hello.pdf'

    temp = StringIO()

    # Create the PDF object, using the StringIO object as its
    "file."
    p = canvas.Canvas(temp)

    # Draw things on the PDF. Here's where the PDF generation
    happens.
    # See the ReportLab documentation for the full list of
    functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly.
    p.showPage()
    p.save()

    # Get the value of the StringIO buffer and write it to the
    response.
    response.write(temp.getvalue())
    return response

Initialisation

Pour activer les flux de syndication sur votre site Django, ajoutez cet URLConf:

(r'^feeds/(?P<url>.*)/$',
 'django.contrib.syndication.views.feed',
 {'feed_dict': feeds}
),

Cette ligne indique à Django qu’il faut utiliser le framework RSS pour gérer toutes les URLs commencant "feeds/". (Vous pouvez changer ce prefixe "feeds/" pour répondre à vos propres besoins).

Cette ligne de l’URLConf présente un argument supplémentaire: {'feed_dict': feeds}. Utilisez cet argument pour transmettre au framework de syndication les flux qui doivent être publiés sous cet URL.

Plus spécialement, feed_dict doit être un dictionnaire qui met en correspondance le slug du flux (une courte étiquette représentant l’URL) avec sa classe Feed. Vous pouvez définir le feed_dict dans l’URLConf lui même. Voici un exemple complet d’URLconf:

from django.conf.urls.defaults import *
from myproject.feeds import LatestEntries, LatestEntriesByCategory

feeds = {
    'latest': LatestEntries,
    'categories': LatestEntriesByCategory,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$',
    'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

L’exemple précédent enregistre deux flux:

• Le flux représenté par LatestEntries sera disponible sous feeds/latest/.
• le flux représenté par LatestEntriesByCategory sera disponible sous feeds/categories/.

Une fois paramétré, vous devrez définir les classes Feed elles mêmes.

Une classe Feed est une simple classe Pytohn qui représente un flux de syndication. Un flux peut être simple (par exemple, un flux «nouveautés du site», ou un flux basique affichant les dernières entrées d’un blog) ou plus complexe (par exemple, un flux affichant toutes les entrées de blog d’une catégorie particulière, ou la catégorie est variable).

Les classes Feed doivent être des sous classes django.contrib.syndication.feeds.Feed. Elle peuvent se trouver n’importe où dans votre arborescence de code.

Un simple flux

Cet exemple simple, extrait de chicagocrime.org, décrit un flux des cinq dernièrs éléments d’actualités:

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem

class LatestEntries(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to
    chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

Les choses importantes qu’il faut noter ici sont les suivantes:

• La classe sous-classe django.contrib.syndication.feeds.Feed.

• title, link, et description correspondent aux éléments standards RSS <title>, <link>, et <description>, respectivement.

• items() est simplement une méthode qui renvoie une liste d’objets qui doivent être inclus dans le flux sous forme d’éléments <item>. Bien que cet exemple renvoie des objets NewsItem en utilisant l’API de base de données de Django, items() n’a pas à renvoyer d’instances de modèle.

  Vous pouvez récupérer quelques fonctionnalités «gratuitement» en utilisant les modèles Django, mais items() peut renvoyer tous les types d’objets que vous désirez.

Il reste juste une étape. Dans un flux RSS, chaque <item>``propose ``<title>, <link>, et <description>. Nous devons indiquer au framework quelles sont les données à placer dans ces éléments.

• Pour spécifier les contenus de <title> et de <description>, créez des gabarits Django (voir le chapitre 4) appelés feeds/latest_title.html et feeds/latest_description.html, ou latest est le slug spécifié dans l’URLconf pour le flux indiqué. Notez que l’extension .html est requise.

  Le système RSS interprète le gabarit pour chaque élément, lui transmettant les deux variables de contexte du gabarit:

  • obj: l’objet courant (un parmis tous les objets que vous avez renvoyé dans items()).

  • site: un objet django.models.core.sites.Site représentant le site courant. C’est utile pour {{ site.domain }} ou {{ site.name }}.

    Si vous ne créez pas de gabarit pour le titre ou pour la description, le framework utilisera le gabarit "{{ obj }}" par défaut - autrement dit, la représentation normale, sous forme de chaîne, de l’objet.

    Vous pouvez aussi changer les noms de ces deux gabarits en précisant title_template et description_template comme attributs de votre classe Feed.

• Pour préciser les contenus de <link>, vos avez deu options.Pour chaque élément de items(), Django commence par essayer d’exécuter une méthode get_absolute_url() sur cet objet. Si cette méthode n’existe pas, il tente d’appeler une méthode item_link()``dans la classe ``Feed, lui passant un unique paramètre, item, qui est l’objet lui même.

  À la fois get_absolute_url() et item_link() doivent retourner l’URL de l’élément comme une chaîne standard Python.

• Pour l’exemple précédent LatestEntries, nous pouvons avoir des gabarits de flux très simples. latest_title.html contient:

  {{ obj.title }}
  

  et latest_description.html contient:

  {{ obj.description }}
  

  C’est presque trop facile !

Un flux plus complexe

Le framework supporte aussi les flux plus complexes, via les paramètres.

Par exemple, chicagocrime.org offre un flux RSS des crimes récents pour chaque ronde de la police de chicago. Il serait insensé de créer une classe séparée pour chaque ronde de police; cela violerait le principe Don’t Repeat Yourself (DRY) et couplerait les données avec la logique de programmation.

Au lieu de cela, le framework de syndication vous autorise à faire des flux génériques qui renvoient les éléments selon l’information contenu dans l’URL du flux.

Sur chicagocrime.org, le flux pour les rondes de police sont accessibles via des URLs semblablent à celles-ci:

• http://www.chicagocrime.org/rss/beats/0613/: reonvoie les crimes récents pour la ronde 0613
• http://www.chicagocrime.org/rss/beats/1424/: renvoie les crimes récents pour la ronde 1424

Le slug est ici "beats". Le framework de syndication voit le bout de l’URL qui suit le slug - 0613 et 1424 - et vous donne un point d’entré pour le renseigner sur la signification de cette partie et sur son influence auprès dès éléments publiés dans le flux.

Un exemple rendra cela plus clair. Voici le code des flux spécifiques aux rondes:

from django.core.exceptions import ObjectDoesNotExist

class BeatFeed(Feed):
    def get_object(self, bits):
        # In case of "/rss/beats/0613/foo/bar/baz/", or other
        such
        # clutter, check that bits has only one member.
        if len(bits) != 1:
            raise ObjectDoesNotExist
        return Beat.objects.get(beat__exact=bits[0])

    def title(self, obj):
        return "Chicagocrime.org: Crimes for beat %s" %
        obj.beat

    def link(self, obj):
        return obj.get_absolute_url()

    def description(self, obj):
        return "Crimes recently reported in police beat %s" %
        obj.beat

    def items(self, obj):
        crimes =
        Crime.objects.filter(beat__id__exact=obj.id)
        return crimes.order_by('-crime_date')[:30]

Voici l’algorithme de base du framework RSS, pour cette classe donnée et pour une requête sur l’URL /rss/beats/0613/:

1. Le framework récupère l’URL /rss/beats/0613/ et note qu’il y a un bout supplémentaire après le slug. Il coupe cette fin de chaîne au niveau du caractère ("/") et appelle la méthode get_object() de la classe Feed, lui transmettant au passage la partie restante.

   Dans ce cas, la partie est ['0613']. Pour une requête vers /rss/beats/0613/foo/bar/, la partie restante serait ['0613', 'foo', 'bar'].

2. get_object() est responsable de récupérer la ronde de police précisée, depuis la partie indiquée.

   Danc ce cas, on utilise l’API de base de données de Django pour récupérer la ronde. Notez que get_object() doit lever django.core.exceptions.ObjectDoesNotExist si des paramètres invalides sont fournis. Il n’y a pas de try/except autour de l’appel à Beat.objects.get(), parce que cela n’est pas nécessaire. Cette fonction lève Beat.DoesNotExist en cas d’erreur, et Beat.DoesNotExist est une sous classe de ObjectDoesNotExist. Lever ObjectDoesNotExist dans get_object() indique à Django qu’il lui faut produire une erreur 404 pour cette requête.

3. Pour générer les <title>, <link>, et <description> du flux, Django utilise les méthodes title(), link(), et description(). Dans l’exemple précédent, il y avait des attributs de classes sous forme de simple chaîne, mais cet exemple illustre le fait qu’il peut sagir soit de chaînes soit des méthodes. Pour chaque title, link, et description, Django suit cet algorithme:

   1. Il tente d’appeler la méthode, lui passant l’argument obj, où obj est l’objet retourné par get_object().
   2. en cas d’échec, il tente d’appeler une méthode sans arguments.
   3. en cas d’échec, il utilise l’attribut de classe.

4. Finallement, notez que la fonction items() de cet exemple prends aussi l’argument obj. L’algorithme pour items est le même que celui décrit dans l’étape précédente - il commence par essayer items(obj), ensuite items(), et finallement un attribut de classe items (qui doit être une liste).

La documentation complète pour toutes les méthodes et attributs des classes Feed est toujours disponible sur le site de la documentation officielle de Django (http://www.djangoproject.com/documentation/0.96/syndication_feeds/).

Spécifier le type de flux

Par défaut, le framework de syndication produit du RSS 2.0. Pour modifier cela, ajoutez un attribut feed_type à votre classe Feed:

from django.utils.feedgenerator import Atom1Feed

class MyFeed(Feed):
    feed_type = Atom1Feed

Notez que vous paramétrez feed_type pour un objet de classe, pas pour une instance. Actuellement les types de flux sont renseignés dans le tableau 11-1.

Tableau 11-1. Types de flux

Pièces associées

Pour préciser des pièces jointes (c’est à dire, des médias ressources associés à un élément flux tel qu’un flux de podcast MP3), utilisez les points d’entrée item_enclosure_url, item_enclosure_length, et item_enclosure_mime_type, par exemple:

from myproject.models import Song

class MyFeedWithEnclosures(Feed):
    title = "Example feed with enclosures"
    link = "/feeds/example-with-enclosures/"

    def items(self):
        return Song.objects.all()[:30]

    def item_enclosure_url(self, item):
        return item.song_url

    def item_enclosure_length(self, item):
        return item.song_length

    item_enclosure_mime_type = "audio/mpeg"

Ceci implique, bien sure, que vous ayez créé un objet Song avec des champs song_url et song_length (c’est à dire, la taille en octets).

Langage

Les flux créés par le framework de syndication incluent automatiquement la balise appropriée <language> (RSS 2.0) ou l’attribut xml:lang (Atom). Ceci provient directement de votre paramètre LANGUAGE_CODE.

URLs

La méthode/l’attribut link peut retourner soit un URL absolut (par exemple, "/blog/") ou un URL avec le domaine pleinement qualifié et le protocol ( par exemple, "http://www.example.com/blog/"). Si link ne retourne pas le domaine, le framework de syndication inserera le domaine du site courant, conformément à votre paramètre SITE_ID.

Le flux Atom requière un <link rel="self"> qui définit l’emplacement actuel du flux. Le framework de syndication ajoute cela automatiquement, en utilisant le domaine du site courant selon le paramètre SITE_ID.

Publier des flux RSS et Atom conjointement

Certain développeurs aiment à rendre disponible à la fois les versions Atom et RSS de leurs flux. Ceci est simple à faire avec Django: créez simplement une sous classe de votre classe feed et fixez le feed_type à une valeur différente. Ensuite mettez à jour votre URLconf pour ajouter les versions supplémentaires. Voici un exemple complet:

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem
from django.utils.feedgenerator import Atom1Feed

class RssSiteNewsFeed(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to
    chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

class AtomSiteNewsFeed(RssSiteNewsFeed):
    feed_type = Atom1Feed

Et voici l’URLconf l’accompagnant:

from django.conf.urls.defaults import *
from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed

feeds = {
    'rss': RssSiteNewsFeed,
    'atom': AtomSiteNewsFeed,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$',
    'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

Installation

Pour installer l’application sitemap, suivez ces étapes:

1. Ajoutez 'django.contrib.sitemaps' à votre paramètre INSTALLED_APPS.
2. Assurez vous que 'django.template.loaders.app_directories.load_template_source' soit dans votre paramètre TEMPLATE_LOADERS. Il s’y trouve par défaut, vous n’aurez donc pas à modifier cela à moins que vous ne l’ayez changer auparavant.
3. Assurez vous d’avoir installer le framework de sites (voir le chapitre 14).

Initialisation

Pour activer la génération d’une sitemap sur votre site Django, ajoutez cette ligne à votre URLconf:

(r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})

Cette ligne indique à Django qu’il faut construire une sitemap lorsqu’un client accède à /sitemap.xml.

Le nom du fichier sitemap n’est pas important, mais son emplacement, si. Les moteurs de recherche indexerons seulement les liens de votre sitemap pour le niveau d’URL courant et suivant. Par conséquent, si sitemap.xml réside dans votre répertoire racine, il peut référencer tout URL dans votre site web. Cependant, si votre sitemap réside dans /content/sitemap.xml, il ne pourra référencer les URLs commencant par /content/.

La vue sitemap prend un argument supplémentaire, requis: {'sitemaps': sitemaps}. sitemaps doit être un dictionnaire qui met en correspondance une courte étiquette de section (par exemple, blog ou news) avec sa classe Sitemap (par exemple, BLogSitemap ou NewsSitemap). Il peut aussi mettre en correspondance avec une instance de classe Sitemap (par exemple, BlogSitemap(some_var)).

Les classes Sitemap

Une classe Sitemap est une simple classe Python qui représente une «rubrique» d’entrées dans votre sitemap. Par exemple, une classe Sitemap peut représenter toutes les entrées de votre blog, alors qu’une autre peut représenter tous les événement de votre calendrier d’événements.

Dans le cas le plus simple, toutes ces rubriques sont mélangées au sein d’un même sitemap.xml, mais il est aussi possible d’utiliser le framework pour générer un index de sitemap qui référence des fichiers sitemaps individuels, un par rubrique (comme on le détaille sous peu).

Les classes Sitemap doivent sous classer django.contrib.sitemaps.Sitemap. Elles peuvent être placé n’importe où dans votre arborescence de code.

Par exemple, considérons que nous ayons un système de blog, avec un modèle Entry, et que vous vouliez que votre sitemap inclu tous les liens vers vos entrées individuelles de blog. Voici à quoi pourrait ressembler votre classe Sitemap:

from django.contrib.sitemaps import Sitemap
from mysite.blog.models import Entry

class BlogSitemap(Sitemap):
    changefreq = "never"
    priority = 0.5

    def items(self):
        return Entry.objects.filter(is_draft=False)

    def lastmod(self, obj):
        return obj.pub_date

Déclarer un Sitemap ressemble étrangement à la déclaration d’un Feed; Ceci est du à la conception.

Tout comme les classes Feed, les membres de Sitemap peuvent être des méthodes ou des attributs. Voyez les étapes dans la section «Un exemple complexe» pour en savoir plus au sujet de son fonctionnement.

Une classe Sitemap peut définir les méthodes et attributs suivants:

• items (requis): fournit une liste d’objets. Le framework ne s’occupe pas de savoir quel est le type des objets; tout ce qui compte est que ces objets soit transmis aux méthodes location(), lastmod(), changefreq(), et priority().

• location (optionel): donne l’URL absolut d’une objet donné. Ici, «URL absolut» signifie que l’URL ne contient pas le protocol ou le domaine. Voici quelques exemples:

  • Bon: '/foo/bar/'
  • Mauvais: 'example.com/foo/bar/'
  • Mauvais: 'http://example.com/foo/bar/'

  Si location n’est pas fourni, le framework appellera la méthode get_absolute_url() sur chaque objets retournés par items().

• lastmod (optionel): la date de «dernière modification» de l’objet, sous forme d’objet Python datetime.

• changefreq (optionel): la fréquence de modification des objets. Les valeurs possible sont les suivantes (comme l’indique la spécification Sitemaps):

  • 'always'
  • 'hourly'
  • 'daily'
  • 'weekly'
  • 'monthly'
  • 'yearly'
  • 'never'

• priority (optionel): une suggestion de priorité d’indexaton entre 0.0 et 1.0. La priorité par défaut d’une page est 0.5; lisez la documentation de http://sitemaps.org pour en savoir plus sur le fonctionnement de priority.

Raccourcis

Le framework de sitemap fournit quelques classiques bien pratiques dans les cas courants. Elles sont décrites dans les sections qui suivent.

from django.conf.urls.defaults import *
from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap
from mysite.blog.models import Entry

info_dict = {
    'queryset': Entry.objects.all(),
    'date_field': 'pub_date',
}

sitemaps = {
    'flatpages': FlatPageSitemap,
    'blog': GenericSitemap(info_dict, priority=0.6),
}

urlpatterns = patterns('',
    # some generic view using info_dict
    # ...

    # the sitemap
    (r'^sitemap.xml$',
     'django.contrib.sitemaps.views.sitemap',
     {'sitemaps': sitemaps})
)

Créer un index de sitemap

Le framework de sitemap possède aussi l’aptitude à créer un index de sitemap qui référence des fichiers sitemap individuels, un pour chaque rubrique définies dans votre dictionnaire sitemaps. Les seules différences d’utilisation sont les suivantes:

• Vous utilisez deux vues dans votre URLconf: django.contrib.sitemaps.views.index et django.contrib.sitemaps.views.sitemap.
• La vue django.contrib.sitemaps.views.sitemap doit prendre un argument mot-clef section.

Voici un exemple de ce à quoi pourrait ressembler ces lignes dans l’URLconf avec notre exemple précédent:

(r'^sitemap.xml$',
 'django.contrib.sitemaps.views.index',
 {'sitemaps': sitemaps}),

(r'^sitemap-(?P<section>.+).xml$',
 'django.contrib.sitemaps.views.sitemap',
 {'sitemaps': sitemaps})

Cela générera automatiquement un fichier sitemap.xml qui référence à la fois sitemap-flatpages.xml et sitemap-blog.xml. Les classes Sitemap et le dictionnaire sitemaps ne change pas du tout.

«Pinger» Google

Vous pourriez vouloir «pinger» Google lorsque votre sitemap change, pour lui signaler de réindexer votre site. Le framework fournit une fonction pour faire cela: django.contrib.sitemaps.ping_google().

ping_google() accepte deux arguments optionnels, sitemap_url, qui doit être l’URL absolut de la sitemap de votre site (par exemple, '/sitemap.xml'). Si cette argument n’est pas fourni, ping_google() tentera de déterminer votre sitemap grâce à une analyse de votre URLconf.

ping_google() lève l’exception django.contrib.sitemaps.SitemapNotFound s’il ne peut déterminer l’URL de votre sitemap.

Un façon utile d’appeler ping_google() est de la faire depuis une méthode save() du modèle:

from django.contrib.sitemaps import ping_google

class Entry(models.Model):
    # ...
    def save(self):
        super(Entry, self).save()
        try:
            ping_google()
        except Exception:
            # Bare 'except' because we could get a
            variety
            # of HTTP-related exceptions.
            pass

Une solution plus efficace, cependant, est d’appeler ping_google() depuis un script cron ou depuis tout autre ordonnanceur de tâche. La fonction fait une requête HTTP vers les serveurs de Goolge, vous n’introduirez pas cette surchage réseau à chaque fois que vous appellez save().