A Review of ReportLab: PDF Processing with Python

The Technical

This book is available in digital format (PDF natch), and can be found on the author’s website.

There is a lot of content in this book. It contains 428 pages of examples and deep dives into the API of the library. Seriously, if there is something you wish you could do with a PDF and ReportLab can do it, then this book will get you started.

The Good

Because the bitter is often softened by the sweet, I’ll start with the sweet things about this book.

It is clear that the author, Michael Driscoll, knows ReportLab very well, and he knows how to construct illustrative snippets of code that demonstrate his material. From the start to finish this book is full of clear, useful code that works (this cannot be underlined enough), the code that is in the book will work if you copy it, which is sadly a rarity for many resources about computing. Big publishing names like O’Reilly and Wrox who have editorial staff often publish books with broken examples. Full disclosure, I did not run every single piece of code, but I did sample about 40% of the code and none of it was broken.

Driscoll also does a very good job of building up his examples. Every book on programming starts with its “Hello, World!” example, and this book is no exception, but in my experience, the poorer books out there fail to continue a steady progression of ideas that layer logically one on top of the other, which can leave a reader feeling lost and frustrated. Driscoll, on the other hand, does a very good job of steadily incrementing the work already done with the new examples.

Almost every example in this book shows its result as an embedded image. This, of course, makes sense for a book about a library that works with PDFs. It is also another one of those touches that highlight the accuracy of the code. It’s one thing to say, “Hey, cool, the code I just worked through ran,” and another to be able to compare your results visually with the source.

The Not So Good

I have one major complaint about this book and a few minor editorial quibbles.

Who is the intended audience for this book?

While the parts of the book that actually deal with ReportLab are extremely well organized, the opening of the book is a mess of instructions that might turn off novice programmers, and are a little muddled for experienced developers.

The first section “Conventions” discusses the Python prompt which indicate a focus on beginners, but then the very next section jumps right into setting up a virtual environment. Wait, I’m a beginner, what is the “interpreter”? What is IDLE? What is going on here? On the flip side, if this book was targeted at more experienced developers, much of this could be boiled down into a single dependencies and style section.

The author also adds a section about using virtualenv and dependencies, but the discussion of virtualenvs takes place before a discussion about Python. For the beginner this could possibly stop them all together as they tried to install virtualenv on a machine that doesn’t already have Python installed.

To be fair, none of this is a problem for an experienced developer, and with a specialized topic like working with a fairly extensive and powerful library like ReportLab, the author can be forgiven for assuming a more experienced readership. However, this should be spelled out at the beginning of the book. Who is the book for? What skill level is needed to get the most from the book?

Quibble: Code Styling Is Inconsistent

This is certainly a minor quibble — the code working is much more important — but quite often I would see weird switches in style from example to example and sometimes within examples.

First off, ReportLab itself uses lowerCamelCase for class methods and functions rather than snake_case, which sometimes bleeds over into the author’s choice of variable names. For example, on page 57, the author is showing us how to use ReportLab to build form letters, and his example contains the following variable styles:

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.", "Waterloo, IA 50158"]

Is this minor? Yes. Does it make my hand itch? Yes.

Quibble: Stick with a single way of doing things.

Sometimes the author switches between a Python 2 idiom and a Python 3 idiom for doing a thing. In the same code example I noted in the above quibble, the author uses the Python 2 % operator to do string interpolation, and in the same block of code throws in a Python 3 .format() for the exact same purpose. I noticed this only a couple of times so again — minor. But these sorts of things can throw a new developer who is trying to grasp the material and perhaps a new language.

Conclusion

If you are interested in learning how to automate the generation of PDFs for your projects and you plan on using ReportLab, then this book is a great choice. It covers in detail every aspect of the ReportLab library in a clear and iteratively more complex manner. Also, the code examples work!

Aside from a slightly unfocused introduction, which could hinder a new developer from approaching the material and some style inconsistencies, the author has produced a solid instructional book. It’s a great reference when you need to brush up on how to accomplish some arcane bit of PDF magic.

Note: This review was solicited by the author of the book, and my company received a free copy for review. However, all opinions are my own.