=======================

How to create PDF files

=======================

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: https://www.reportlab.com/opensource/

.. _kusports.com: http://www2.kusports.com/

Install ReportLab

=================

The ReportLab library is `available on PyPI`_. A `user guide`_ (not

coincidentally, a PDF file) is also available for download.

You can install ReportLab with ``pip``:

.. console::

    $ python -m pip install reportlab

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

    >>> import reportlab

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

.. _available on PyPI: https://pypi.org/project/reportlab/

.. _user guide: https://www.reportlab.com/docs/reportlab-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 :class:`~django.http.FileResponse`

objects accept file-like objects.

Here's a "Hello World" example::

    import io

    from django.http import FileResponse

    from reportlab.pdfgen import canvas

    def some_view(request):

        # Create a file-like buffer to receive PDF data.

        buffer = io.BytesIO()

        # Create the PDF object, using the buffer 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, and we're done.

        p.showPage()

        p.save()

        # FileResponse sets the Content-Disposition header so that browsers

        # present the option to save the file.

        buffer.seek(0)

        return FileResponse(buffer, as_attachment=True, filename='hello.pdf')

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

mention:

* The response will automatically set the MIME type :mimetype:`application/pdf`

  based on the filename extension. This tells browsers that the document is a

  PDF file, rather than an HTML file or a generic

  :mimetype:`application/octet-stream` binary content.

* When ``as_attachment=True`` is passed to ``FileResponse``, it sets the

  appropriate ``Content-Disposition`` header and that tells 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 the ``as_attachment`` parameter is omitted,

  browsers will handle the PDF using whatever program/plugin they've been

  configured to use for PDFs.

* You can provide an arbitrary ``filename`` parameter. It'll be used by browsers

  in the "Save as..." dialog.

* You can hook into the ReportLab API: The same buffer passed as the first

  argument to ``canvas.Canvas`` can be fed to the

  :class:`~django.http.FileResponse` class.

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

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

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

  file.

.. note::

    ReportLab is not thread-safe. Some of our users have reported odd issues

    with building PDF-generating Django views that are accessed by many people

    at the same time.

Other formats

=============

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

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

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

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

when generated text-based formats.

.. seealso::

    Django Packages provides a `comparison of packages

    <https://djangopackages.org/grids/g/pdf/>`_ that help generate PDF files

    from Django.