1 ===========================

     2 Outputting PDFs with Django

     3 ===========================

     4 

     5 This document explains how to output PDF files dynamically using Django views.

     6 This is made possible by the excellent, open-source ReportLab_ Python PDF

     7 library.

     8 

     9 The advantage of generating PDF files dynamically is that you can create

    10 customized PDFs for different purposes -- say, for different users or different

    11 pieces of content.

    12 

    13 For example, Django was used at kusports.com_ to generate customized,

    14 printer-friendly NCAA tournament brackets, as PDF files, for people

    15 participating in a March Madness contest.

    16 

    17 .. _ReportLab: http://www.reportlab.org/oss/rl-toolkit/

    18 .. _kusports.com: http://www.kusports.com/

    19 

    20 Install ReportLab

    21 =================

    22 

    23 Download and install the ReportLab library from http://www.reportlab.org/oss/rl-toolkit/download/.

    24 The `user guide`_ (not coincidentally, a PDF file) explains how to install it.

    25 

    26 Test your installation by importing it in the Python interactive interpreter::

    27 

    28     >>> import reportlab

    29 

    30 If that command doesn't raise any errors, the installation worked.

    31 

    32 .. _user guide: http://www.reportlab.com/docs/reportlab-userguide.pdf

    33 

    34 Write your view

    35 ===============

    36 

    37 The key to generating PDFs dynamically with Django is that the ReportLab API

    38 acts on file-like objects, and Django's :class:`~django.http.HttpResponse`

    39 objects are file-like objects.

    40 

    41 Here's a "Hello World" example::

    42 

    43     from reportlab.pdfgen import canvas

    44     from django.http import HttpResponse

    45 

    46     def some_view(request):

    47         # Create the HttpResponse object with the appropriate PDF headers.

    48         response = HttpResponse(mimetype='application/pdf')

    49         response['Content-Disposition'] = 'attachment; filename=somefilename.pdf'

    50 

    51         # Create the PDF object, using the response object as its "file."

    52         p = canvas.Canvas(response)

    53 

    54         # Draw things on the PDF. Here's where the PDF generation happens.

    55         # See the ReportLab documentation for the full list of functionality.

    56         p.drawString(100, 100, "Hello world.")

    57 

    58         # Close the PDF object cleanly, and we're done.

    59         p.showPage()

    60         p.save()

    61         return response

    62 

    63 The code and comments should be self-explanatory, but a few things deserve a

    64 mention:

    65 

    66     * The response gets a special MIME type, ``application/pdf``. This tells

    67       browsers that the document is a PDF file, rather than an HTML file. If

    68       you leave this off, browsers will probably interpret the output as HTML,

    69       which would result in ugly, scary gobbledygook in the browser window.

    70 

    71     * The response gets an additional ``Content-Disposition`` header, which

    72       contains the name of the PDF file. This filename is arbitrary: Call it

    73       whatever you want. It'll be used by browsers in the "Save as..."

    74       dialogue, etc.

    75 

    76     * The ``Content-Disposition`` header starts with ``'attachment; '`` in this

    77       example. This forces Web browsers to pop-up a dialog box

    78       prompting/confirming how to handle the document even if a default is set

    79       on the machine. If you leave off ``'attachment;'``, browsers will handle

    80       the PDF using whatever program/plugin they've been configured to use for

    81       PDFs. Here's what that code would look like::

    82 

    83           response['Content-Disposition'] = 'filename=somefilename.pdf'

    84 

    85     * Hooking into the ReportLab API is easy: Just pass ``response`` as the

    86       first argument to ``canvas.Canvas``. The ``Canvas`` class expects a

    87       file-like object, and :class:`~django.http.HttpResponse` objects fit the

    88       bill.

    89 

    90     * Note that all subsequent PDF-generation methods are called on the PDF

    91       object (in this case, ``p``) -- not on ``response``.

    92 

    93     * Finally, it's important to call ``showPage()`` and ``save()`` on the PDF

    94       file.

    95 

    96 Complex PDFs

    97 ============

    98 

    99 If you're creating a complex PDF document with ReportLab, consider using the

   100 cStringIO_ library as a temporary holding place for your PDF file. The cStringIO

   101 library provides a file-like object interface that is particularly efficient.

   102 Here's the above "Hello World" example rewritten to use ``cStringIO``::

   103 

   104     # Fall back to StringIO in environments where cStringIO is not available

   105     try:

   106         from cStringIO import StringIO

   107     except ImportError:

   108         from StringIO import StringIO

   109     from reportlab.pdfgen import canvas

   110     from django.http import HttpResponse

   111 

   112     def some_view(request):

   113         # Create the HttpResponse object with the appropriate PDF headers.

   114         response = HttpResponse(mimetype='application/pdf')

   115         response['Content-Disposition'] = 'attachment; filename=somefilename.pdf'

   116 

   117         buffer = StringIO()

   118 

   119         # Create the PDF object, using the StringIO object as its "file."

   120         p = canvas.Canvas(buffer)

   121 

   122         # Draw things on the PDF. Here's where the PDF generation happens.

   123         # See the ReportLab documentation for the full list of functionality.

   124         p.drawString(100, 100, "Hello world.")

   125 

   126         # Close the PDF object cleanly.

   127         p.showPage()

   128         p.save()

   129 

   130         # Get the value of the StringIO buffer and write it to the response.

   131         pdf = buffer.getvalue()

   132         buffer.close()

   133         response.write(pdf)

   134         return response

   135 

   136 .. _cStringIO: http://docs.python.org/library/stringio.html#module-cStringIO

   137 

   138 Further resources

   139 =================

   140 

   141     * PDFlib_ is another PDF-generation library that has Python bindings. To

   142       use it with Django, just use the same concepts explained in this article.

   143     * `Pisa XHTML2PDF`_ is yet another PDF-generation library. Pisa ships with

   144       an example of how to integrate Pisa with Django.

   145     * HTMLdoc_ is a command-line script that can convert HTML to PDF. It

   146       doesn't have a Python interface, but you can escape out to the shell

   147       using ``system`` or ``popen`` and retrieve the output in Python.

   148 

   149 .. _PDFlib: http://www.pdflib.org/

   150 .. _`Pisa XHTML2PDF`: http://www.xhtml2pdf.com/

   151 .. _HTMLdoc: http://www.htmldoc.org/

   152 

   153 Other formats

   154 =============

   155 

   156 Notice that there isn't a lot in these examples that's PDF-specific -- just the

   157 bits using ``reportlab``. You can use a similar technique to generate any

   158 arbitrary format that you can find a Python library for. Also see

   159 :doc:`/howto/outputting-csv` for another example and some techniques you can use

   160 when generated text-based formats.