| =========================== |
| Outputting PDFs with Django |
| =========================== |
| |
| This document explains how to output PDF files dynamically using Django views. |
| This is made possible by the excellent, open-source ReportLab_ Python PDF |
| library. |
| |
| The advantage of generating PDF files dynamically is that you can create |
| customized PDFs for different purposes -- say, for different users or different |
| pieces of content. |
| |
| For example, Django was used at kusports.com_ to generate customized, |
| printer-friendly NCAA tournament brackets, as PDF files, for people |
| participating in a March Madness contest. |
| |
| .. _ReportLab: http://www.reportlab.org/rl_toolkit.html |
| .. _kusports.com: http://www.kusports.com/ |
| |
| Install ReportLab |
| ================= |
| |
| Download and install the ReportLab library from http://www.reportlab.org/downloads.html. |
| The `user guide`_ (not coincidentally, a PDF file) explains how to install it. |
| |
| Test your installation by importing it in the Python interactive interpreter:: |
| |
| >>> import reportlab |
| |
| If that command doesn't raise any errors, the installation worked. |
| |
| .. _user guide: http://www.reportlab.com/docs/userguide.pdf |
| |
| Write your view |
| =============== |
| |
| The key to generating PDFs dynamically with Django is that the ReportLab API |
| acts on file-like objects, and Django's ``HttpResponse`` objects are file-like |
| objects. |
| |
| .. admonition:: Note |
| |
| For more information on ``HttpResponse`` objects, see |
| `Request and response objects`_. |
| |
| .. _Request and response objects: ../request_response/ |
| |
| Here's a "Hello World" example:: |
| |
| from reportlab.pdfgen import canvas |
| from django.http import HttpResponse |
| |
| def some_view(request): |
| # Create the HttpResponse object with the appropriate PDF headers. |
| response = HttpResponse(mimetype='application/pdf') |
| response['Content-Disposition'] = 'attachment; filename=somefilename.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 |
| |
| The code and comments should be self-explanatory, but a few things deserve a |
| mention: |
| |
| * The response gets a special mimetype, ``application/pdf``. This tells |
| browsers that the document is a PDF file, rather than an HTML file. If |
| you leave this off, browsers will probably interpret the output as HTML, |
| which would result in ugly, scary gobbledygook in the browser window. |
| |
| * The response gets an additional ``Content-Disposition`` header, which |
| contains the name of the PDF file. This filename is arbitrary: Call it |
| whatever you want. It'll be used by browsers in the "Save as..." |
| dialogue, etc. |
| |
| * The ``Content-Disposition`` header starts with ``'attachment; '`` in this |
| example. This forces Web browsers to pop-up a dialog box |
| prompting/confirming how to handle the document even if a default is set |
| on the machine. If you leave off ``'attachment;'``, browsers will handle |
| the PDF using whatever program/plugin they've been configured to use for |
| PDFs. Here's what that code would look like:: |
| |
| response['Content-Disposition'] = 'filename=somefilename.pdf' |
| |
| * Hooking into the ReportLab API is easy: Just pass ``response`` as the |
| first argument to ``canvas.Canvas``. The ``Canvas`` class expects a |
| file-like object, and ``HttpResponse`` objects fit the bill. |
| |
| * Note that all subsequent PDF-generation methods are called on the PDF |
| object (in this case, ``p``) -- not on ``response``. |
| |
| * Finally, it's important to call ``showPage()`` and ``save()`` on the PDF |
| file. |
| |
| Complex PDFs |
| ============ |
| |
| If you're creating a complex PDF document with ReportLab, consider using the |
| cStringIO_ library as a temporary holding place for your PDF file. The |
| cStringIO library provides a file-like object interface that is particularly |
| efficient. Here's the above "Hello World" example rewritten to use |
| ``cStringIO``:: |
| |
| from cStringIO import StringIO |
| from reportlab.pdfgen import canvas |
| from django.http import HttpResponse |
| |
| def some_view(request): |
| # Create the HttpResponse object with the appropriate PDF headers. |
| response = HttpResponse(mimetype='application/pdf') |
| response['Content-Disposition'] = 'attachment; filename=somefilename.pdf' |
| |
| buffer = StringIO() |
| |
| # Create the PDF object, using the StringIO object as its "file." |
| p = canvas.Canvas(buffer) |
| |
| # 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. |
| pdf = buffer.getvalue() |
| buffer.close() |
| response.write(pdf) |
| return response |
| |
| .. _cStringIO: http://www.python.org/doc/current/lib/module-cStringIO.html |
| |
| Further resources |
| ================= |
| |
| * PDFlib_ is another PDF-generation library that has Python bindings. To |
| use it with Django, just use the same concepts explained in this article. |
| * HTMLdoc_ is a command-line script that can convert HTML to PDF. It |
| doesn't have a Python interface, but you can escape out to the shell |
| using ``system`` or ``popen`` and retrieve the output in Python. |
| * `forge_fdf in Python`_ is a library that fills in PDF forms. |
| |
| .. _PDFlib: http://www.pdflib.org/ |
| .. _HTMLdoc: http://www.htmldoc.org/ |
| .. _forge_fdf in Python: http://www.accesspdf.com/article.php/20050421092951834 |