A pyPdf Tour

To get the most out of pyPdf, you need to learn its two major functions: PdfFileReader and PdfFileWriter. They are the ones that I use the most. Let’s take a look at what they can do:

# Merge two PDFs
from pyPdf import PdfFileReader, PdfFileWriter
 
output = PdfFileWriter()
pdfOne = PdfFileReader(file( "some\path\to\a\PDf", "rb"))
pdfTwo = PdfFileReader(file("some\other\path\to\a\PDf", "rb"))
 
output.addPage(pdfOne.getPage(0))
output.addPage(pdfTwo.getPage(0))
 
outputStream = file(r"output.pdf", "wb")
output.write(outputStream)
outputStream.close()

The code above will open two PDFs, take the first page from each and create a third PDF by joining those two pages. Note that the pages are zero-based, so zero is page one, one is page two, etc. I use this sort of script to extract one or more pages from a PDF or to join a series of PDFs together. For example, sometimes my users will receive a bunch of scanned documents where each page of the document ends up in a separate PDF. They need all the single pages joined into one PDF and pyPdf allows me to do this very simply.

There aren’t many applications for the rotating functions that pyPdf gives me in my day-to-day experience, but maybe you have lots of users that scan documents in landscape rather than portrait and you end up needing to do a lot of turning. Fortunately, this is pretty painless:

from pyPdf import PdfFileWriter, PdfFileReader
 
output = PdfFileWriter()
input1 = PdfFileReader(file("document1.pdf", "rb"))
output.addPage(input1.getPage(1).rotateClockwise(90))
# output.addPage(input1.getPage(2).rotateCounterClockwise(90))
 
outputStream = file("output.pdf", "wb")
output.write(outputStream)
outputStream.close()

The code above is just taken from the pyPdf documentation and shortened for this example. As you can see, the method to call is rotateClockwise or rotateCounterClockwise. Make sure you pass the method the number of degrees to turn the page as well.

Now let’s see what information we can pull from the PDF about itself:

>>> from pyPdf import PdfFileReader
>>> p = r'E:\My Documents\My Dropbox\ebooks\helloWorld book.pdf'
>>> pdf = PdfFileReader(file(p, 'rb'))
>>> pdf.documentInfo
{'/CreationDate': u'D:20090323080712Z', '/Author': u'Warren Sande', '/Producer': u'Acrobat Distiller 8.0.0 (Windows)', '/Creator': u'FrameMaker 8.0', '/ModDate': u"D:20090401124817-04'00'", '/Title': u'Hello World!'}
>>> pdf.getNumPages()
432
>>> info = pdf.getDocumentInfo()
>>> info.author
u'Warren Sande'
>>> info.creator
u'FrameMaker 8.0'
>>> info.producer
u'Acrobat Distiller 8.0.0 (Windows)'
>>> info.title
u'Hello World!'

As you can see, we can gather quite a bit of useful data using pyPdf. Now let’s create a simple GUI to make merging two PDFs easier!

Creating a wxPython PDF Merger Application

I came up with this script yesterday. It uses Tim Golden’s winshell module to give me easy access to the user’s desktop on Windows. If you’re on Linux or Mac, then you’ll want to change this part of the code for your platform. I wanted to use wxPython’s StandardPaths module, but it didn’t have a function for getting the desktop that I could see. Anyway, enough talk. Let’s look at some code!

import os
import pyPdf
import winshell
import wx
 
class MyFileDropTarget(wx.FileDropTarget):
    def __init__(self, window):
        wx.FileDropTarget.__init__(self)
        self.window = window
 
    def OnDropFiles(self, x, y, filenames):
        self.window.SetInsertionPointEnd()
 
        for file in filenames:
            self.window.WriteText(file)
 
########################################################################
class JoinerPanel(wx.Panel):
    """"""
 
    #----------------------------------------------------------------------
    def __init__(self, parent):
        """Constructor"""
        wx.Panel.__init__(self, parent=parent)
 
        self.currentPath = winshell.desktop()
 
 
        lblSize = (70,-1)
        pdfLblOne = wx.StaticText(self, label="PDF One:", size=lblSize)
        self.pdfOne = wx.TextCtrl(self)
        dt = MyFileDropTarget(self.pdfOne)
        self.pdfOne.SetDropTarget(dt)
        pdfOneBtn = wx.Button(self, label="Browse", name="pdfOneBtn")
        pdfOneBtn.Bind(wx.EVT_BUTTON, self.onBrowse)
 
        pdfLblTwo = wx.StaticText(self, label="PDF Two:", size=lblSize)
        self.pdfTwo = wx.TextCtrl(self)
        dt = MyFileDropTarget(self.pdfTwo)
        self.pdfTwo.SetDropTarget(dt)
        pdfTwoBtn = wx.Button(self, label="Browse", name="pdfTwoBtn")
        pdfTwoBtn.Bind(wx.EVT_BUTTON, self.onBrowse)
 
        outputLbl = wx.StaticText(self, label="Output name:", size=lblSize)
        self.outputPdf = wx.TextCtrl(self)
        widgets = [(pdfLblOne, self.pdfOne, pdfOneBtn),
                   (pdfLblTwo, self.pdfTwo, pdfTwoBtn),
                   (outputLbl, self.outputPdf)]
 
        joinBtn = wx.Button(self, label="Join PDFs")
        joinBtn.Bind(wx.EVT_BUTTON, self.onJoinPdfs)
 
        self.mainSizer = wx.BoxSizer(wx.VERTICAL)
        for widget in widgets:
            self.buildRows(widget)
        self.mainSizer.Add(joinBtn, 0, wx.ALL|wx.CENTER, 5)
        self.SetSizer(self.mainSizer)
 
    #----------------------------------------------------------------------
    def buildRows(self, widgets):
        """"""
        sizer = wx.BoxSizer(wx.HORIZONTAL)
        for widget in widgets:
            if isinstance(widget, wx.StaticText):
                sizer.Add(widget, 0, wx.ALL|wx.CENTER, 5)
            elif isinstance(widget, wx.TextCtrl):
                sizer.Add(widget, 1, wx.ALL|wx.EXPAND, 5)
            else:
                sizer.Add(widget, 0, wx.ALL, 5)
        self.mainSizer.Add(sizer, 0, wx.EXPAND)
 
    #----------------------------------------------------------------------
    def onBrowse(self, event):
        """
        Browse for PDFs
        """
        widget = event.GetEventObject()
        name = widget.GetName()
 
        wildcard = "PDF (*.pdf)|*.pdf"
        dlg = wx.FileDialog(
            self, message="Choose a file",
            defaultDir=self.currentPath,
            defaultFile="",
            wildcard=wildcard,
            style=wx.OPEN | wx.CHANGE_DIR
            )
        if dlg.ShowModal() == wx.ID_OK:
            path = dlg.GetPath()
            if name == "pdfOneBtn":
                self.pdfOne.SetValue(path)
            else:
                self.pdfTwo.SetValue(path)
            self.currentPath = os.path.dirname(path)
        dlg.Destroy()
 
    #----------------------------------------------------------------------
    def onJoinPdfs(self, event):
        """
        Join the two PDFs together and save the result to the desktop
        """
        pdfOne = self.pdfOne.GetValue()
        pdfTwo = self.pdfTwo.GetValue()
        if not os.path.exists(pdfOne):
            msg = "The PDF at %s does not exist!" % pdfOne
            dlg = wx.MessageDialog(None, msg, 'Error', wx.OK|wx.ICON_EXCLAMATION)
            dlg.ShowModal()
            dlg.Destroy()
            return
        if not os.path.exists(pdfTwo):
            msg = "The PDF at %s does not exist!" % pdfTwo
            dlg = wx.MessageDialog(None, msg, 'Error', wx.OK|wx.ICON_EXCLAMATION)
            dlg.ShowModal()
            dlg.Destroy()
            return
 
        outputPath = os.path.join(winshell.desktop(), self.outputPdf.GetValue()) + ".pdf"
        output = pyPdf.PdfFileWriter()
 
        pdfOne = pyPdf.PdfFileReader(file(pdfOne, "rb"))
        for page in range(pdfOne.getNumPages()):
            output.addPage(pdfOne.getPage(page))
        pdfTwo = pyPdf.PdfFileReader(file(pdfTwo, "rb"))
        for page in range(pdfTwo.getNumPages()):
            output.addPage(pdfTwo.getPage(page))
 
        outputStream = file(outputPath, "wb")
        output.write(outputStream)
        outputStream.close()
 
        msg = "PDF was save to " + outputPath
        dlg = wx.MessageDialog(None, msg, 'PDF Created', wx.OK|wx.ICON_INFORMATION)
        dlg.ShowModal()
        dlg.Destroy()
 
        self.pdfOne.SetValue("")
        self.pdfTwo.SetValue("")
        self.outputPdf.SetValue("")
 
########################################################################
class JoinerFrame(wx.Frame):
 
    #----------------------------------------------------------------------
    def __init__(self):
        wx.Frame.__init__(self, None, wx.ID_ANY,
                          "PDF Joiner", size=(550, 200))
        panel = JoinerPanel(self)
 
#----------------------------------------------------------------------
# Run the program
if __name__ == "__main__":
    app = wx.App(False)
    frame = JoinerFrame()
    frame.Show()
    app.MainLoop()

You’ll notice that the frame and panel have dopey names. Feel free to change them. This is Python after all! The MyFileDropTarget class is used to enable drag-and-drop functionality on the first two text controls. If the user wants, they may drag a PDF onto one of those text controls and the path will magically get inserted. Otherwise, they can use the Browse button(s) to find the PDF(s) of their choice. Once they have their PDFs chosen, they need to enter the name of the output PDF, which goes in the third text control. You don’t even need to append the “.pdf” extension since this application will do it for you.

The last step is to press the “Join PDFs” button. This will add the second PDF to the end of the first, then display a dialog if it was created successfully. For this to function correctly, we need to loop over all the pages of each PDF and add them to the output in order.

It would be fun to enhance this application with some kind of drag-and-drop interface where the user could see the PDF pages and rearrange them by dragging them around. Or just being able to specify a few pages from each PDF to add rather than joining them in their entirety. I’ll leave those as exercises for the reader though.

I hope you found this article interesting and that it will spark your creative juices. If you write something cool with these ideas, be sure to post a comment so I can see it!

Installation

Reportlab supports most of the normal Python installation methods. You have the option of downloading the source and running “python setup.py install” or running a binary installer (on Windows). There was a recent thread on their mailing list that seemed to indicate that they may also support pip soon. The threads I’ve read about Reportlab’s support of easy_install are confusing, so I’m not sure if they already support that method or not.

Creating a Simple PDF

Reportlab has decent documentation. What I mean by that is that the documentation gives you just enough to get started, but when you find something slightly complex to do, you get to figure it out on your own. Just recently, they added a Code Snippets section to their website that will hopefully become a recipe book of cool tips and tricks and also help ameliorate this issue. But enough about that. Let’s see how to actually create something!

In Reportlab, the lowest-level component that’s used regularly is the canvas object from the pdfgen package. The functions in this package allow you to “paint” a document with your text, images, lines or whatever. I’ve heard some people describe this as writing in PostScript. I doubt it’s really that bad. In my experience, it’s actually a lot like using a GUI toolkit to layout widgets in specific locations. Let’s see how the canvas object works:

from reportlab.pdfgen import canvas
 
c = canvas.Canvas("hello.pdf")
c.drawString(100,750,"Welcome to Reportlab!")
c.save()

You should end up with a PDF that looks something like this:

The first thing to notice about this code is that if we want to save the PDF, we need to supply a file name to the Canvas object. This can be an absolute path or a relative path. In this example, it should create the PDF in the same location that you run the script from. The next piece of the puzzle is the drawString method. This will draw text wherever you tell it to. When using the canvas object, it starts at the bottom left of the page, so for this example, we told it to draw the string 100 points from the left margin and 750 points from the bottom of the page (1 point = 1/72 inch). You can change this default in the Canvas constructor by passing a zero to the bottomup keyword argument. However, I’m not exactly sure what will happen if you do that as the Reportlab user guide isn’t clear on this topic. I think it will change the start point to the top left though. The final piece in the code above is to save your PDF.

That was easy! You’ve just created a really simple PDF! Note that the default Canvas size is A4, so if you happen to be American, you’ll probably want to change that to letter size. This is easy to do in Reportlab. All you need to do is the following:

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas
 
canvas = canvas.Canvas('myfile.pdf', pagesize=letter)
width, height = letter

The main reason to grab the width and height is that you can use them for calculations to decide when to add a page break or help define margins. Let’s take a quick look at the constructor for the Canvas object to see what other options we have:

def __init__(self,filename,
    pagesize=letter,
    bottomup = 1,
    pageCompression=0,
    encoding=rl_config.defaultEncoding,
    verbosity=0
    encrypt=None):

The above was pulled directly from the Reportlab User Guide, page 11. You can read about the other options in their guide if you want the full details.

Now let’s do something a little more complicated and useful.

A Little Form, Little Function

In this example, we’ll create a partial printable form. As far as I can tell, Reportlab doesn’t support the fillable forms that were added to Adobe products a few years ago. Anyway, let’s take a look at some code!

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas
 
canvas = canvas.Canvas("form.pdf", pagesize=letter)
canvas.setLineWidth(.3)
canvas.setFont('Helvetica', 12)
 
canvas.drawString(30,750,'OFFICIAL COMMUNIQUE')
canvas.drawString(30,735,'OF ACME INDUSTRIES')
canvas.drawString(500,750,"12/12/2010")
canvas.line(480,747,580,747)
 
canvas.drawString(275,725,'AMOUNT OWED:')
canvas.drawString(500,725,"$1,000.00")
canvas.line(378,723,580,723)
 
canvas.drawString(30,703,'RECEIVED BY:')
canvas.line(120,700,580,700)
canvas.drawString(120,703,"JOHN DOE")
 
canvas.save()

This is based on an actual receipt I created at work. The main difference between this one and the previous example is the canvas.line code. You can use it to draw lines on your documents by passing two X/Y pairs. I’ve used this functionality to create grids, although it’s pretty tedious. Other points of interest in this code include the setLineWidth(.3) command, which tells Reportlab how thick or thin the line should be; and the setFont(‘Helvetica’, 12) command, which allows us to specify a specific font and point size.

Our next example will build on what we’ve learned so far, but also introduce us to the concept of “flowables”.

Going with the Flow

If you’re in advertising or do any kind of work with form letters, then Reportlab makes for an excellent addition to your arsenal. We use it to create form letters for people who have overdue parking tickets. The following example is based on some code I wrote for that application, although the letter is quite a bit different. (Note that the code below will not run without the Python Imaging Library)

import time
from reportlab.lib.enums import TA_JUSTIFY
from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Image
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.lib.units import inch
 
doc = SimpleDocTemplate("form_letter.pdf",pagesize=letter,
                        rightMargin=72,leftMargin=72,
                        topMargin=72,bottomMargin=18)
Story=[]
logo = "python_logo.png"
magName = "Pythonista"
issueNum = 12
subPrice = "99.00"
limitedDate = "03/05/2010"
freeGift = "tin foil hat"
 
formatted_time = time.ctime()
full_name = "Mike Driscoll"
address_parts = ["411 State St.", "Marshalltown, IA 50158"]
 
im = Image(logo, 2*inch, 2*inch)
Story.append(im)
 
styles=getSampleStyleSheet()
styles.add(ParagraphStyle(name='Justify', alignment=TA_JUSTIFY))
ptext = '<font size=12>%s</font>' % formatted_time
 
Story.append(Paragraph(ptext, styles["Normal"]))
Story.append(Spacer(1, 12))
 
# Create return address
ptext = '<font size=12>%s</font>' % full_name
Story.append(Paragraph(ptext, styles["Normal"]))
for part in address_parts:
    ptext = '<font size=12>%s</font>' % part.strip()
    Story.append(Paragraph(ptext, styles["Normal"]))
 
Story.append(Spacer(1, 12))
ptext = '<font size=12>Dear %s:</font>' % full_name.split()[0].strip()
Story.append(Paragraph(ptext, styles["Normal"]))
Story.append(Spacer(1, 12))
 
ptext = '<font size=12>We would like to welcome you to our subscriber base for %s Magazine! \
        You will receive %s issues at the excellent introductory price of $%s. Please respond by\
        %s to start receiving your subscription and get the following free gift: %s.</font>' % (magName,
                                                                                                issueNum,
                                                                                                subPrice,
                                                                                                limitedDate,
                                                                                                freeGift)
Story.append(Paragraph(ptext, styles["Justify"]))
Story.append(Spacer(1, 12))
 
 
ptext = '<font size=12>Thank you very much and we look forward to serving you.</font>'
Story.append(Paragraph(ptext, styles["Justify"]))
Story.append(Spacer(1, 12))
ptext = '<font size=12>Sincerely,</font>'
Story.append(Paragraph(ptext, styles["Normal"]))
Story.append(Spacer(1, 48))
ptext = '<font size=12>Ima Sucker</font>'
Story.append(Paragraph(ptext, styles["Normal"]))
Story.append(Spacer(1, 12))
doc.build(Story)

Well, that’s a lot more code than our previous examples contained. We’ll need to look over it slowly to understand everything that’s going on. When you’re ready, just continue reading.

The first part that we need to look at are the new imports:

from reportlab.lib.enums import TA_JUSTIFY
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Image
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.lib.units import inch

From enums, we import “TA_JUSTIFY”, which allows our strings to have the justified format. There are a number of other constants we could import that would allow us to right or left justify our text and do other fun things. Next is the platypus (which stands for Page Layout and Typography Using Scripts) module. It contains lots of modules, but probably the most important of them are the flowables, such as Paragraph. A flowable typically has the following abilities: wrap, draw and sometimes split. They are used to make writing paragraphs, tables and other constructs over multiple pages easier to do.

The SimpleDocTemplate class allows us to set up margins, page size, filename and a bunch of other settings for our document all in one place. A Spacer is good for adding a line of blank space, like a paragraph break. The Image class utilizes the Python Image Library to allow easy insertion and manipulation of images in your PDF.

The getSampleStyleSheet gets a set of default styles that we can use in our PDF. ParagraphStyle is used to set our paragraph’s text alignment in this example, but it can do much more than that (see page 67 of the user guide). Finally, the inch is a unit of measurement to help in positioning items on your PDF. You can see this in action where we position the logo: Image(logo, 2*inch, 2*inch). This means that the logo will be two inches from the top and two inches from the left.

I don’t recall the reason why Reportlab’s examples use a Story list, but that’s how we’ll do it here as well. Basically you create a line of text, a table, and image or whatever and append it to the Story list. You’ll see that throughout the entire example. The first time we use it is when we add the image. Before we look at the next instance, we’ll need to look at how we add a style to our styles object:

styles.add(ParagraphStyle(name='Justify', alignment=TA_JUSTIFY))

The reason this is important is because you can use the style list to apply various paragraph alignment settings (and more) to text in your document. In the code above, we create a ParagraphStyle called “Justify”. All it does is justify our text. You’ll see an example of this later in the text. For now, let’s look at a quick example:

ptext = '<font size=12>%s</font>' % formatted_time
Story.append(Paragraph(ptext, styles["Normal"]))

For our first line of text, we use the Paragraph class. As you can see, the Paragraph class accepts some HTML-like tags. In this instance, we set the font’s point size to 12 and use the normal style (which is left aligned, among other things). The rest of the example is pretty much the same, just with Spacers thrown in here and there. At the end, we call doc.build to create the document.

Wrapping Up

Now you know the basics for creating PDFs in Python using Reportlab. We didn’t even scratch the surface of what all you can do with Reportlab though. Some examples include tables, graphs, paginating, color overprinting, hyperlinks, graphics and much more. I highly recommend that you download the module along with its user guide and give it a try!

Further Reading

• Reportlab Home Page
• Generating Reports with Charts
• A series on Reportlab