CourtBouillon

Big Changes

As explained in the previous article, a lot of things are about to change in the next version of WeasyPrint. The second beta is probably the last one, here is a nice reminder: it’s time to test this new version!

Here is a summary of what you should know:

• no more built-in PNG export, even if PDF files can easily be converted into images using third-party tools;
• changes in SVG rendering with simple inline SVG support, bug fixes, new bugs and unsupported features;
• modified text rendering with better kerning, missing colored emojis, and more;
• differences in performance with generally smaller PDF size and various results for memory and time consumption.

PNG Export

PNG export was one of the "free" features included in Cairo. Now that Cairo has been removed and replaced by pydyf, PNG export is not available anymore.

The --format and --resolution options have thus been deprecated.

It doesn’t mean that getting images is not possible anymore: third-party tools are able to transform PDF files into raster images, with many useful features that were not available in WeasyPrint. In the Free Software world, Ghostscript and Poppler are the usual suspects when dealing with PDF files, and they indeed offer nice possibilities to get your generated images back. You’ll also get all the nice features they provide, and that were not possible before with WeasyPrint.

Please note that Ghostscript and Poppler are released under AGPL and GPL licenses respectively. WeasyPrint is explicitly allowed to use Ghostscript for tests, but using these tools in other circumstances may raise licensing questions.

SVG Rendering

SVG rendering is another collateral victim of Cairo’s removal. WeasyPrint was using CairoSVG to render SVG, and as the library’s name suggests, it’s not possible anymore to use it.

We had to find another solution. So we actually built our own SVG renderer and included it in WeasyPrint. The new renderer is of course highly inspired by CairoSVG, that’s also a CourtBouillon library. Nevertheless, it is really different because it uses pydyf.

This change means that you can expect differences in SVG rendering. Some features are known to be missing (clipping, for example), but some bugs have been fixed too (including many gradients). We even have basic support for inline SVG, a long-awaited feature.

Now, you know. Testing your real world SVG documents and reporting bugs is a good idea!

Text Rendering

Text layout and rendering is one of the major features of WeasyPrint, and removing Cairo changed a lot of things in the way letters are now rendered.

First of all: text layout shouldn’t change in this version. It means that text should be put at the same position as it was in previous versions, in most of the cases. We use Pango for this work, almost the same way as we always did.

What actually changed is the way fonts and letters are stored in the PDF. These parts were done by Cairo, and they are now done by WeasyPrint and pydyf.

Fonts are included in PDF documents as TTF and OTF files. Unused letters are removed from them by default, but can be kept if you prefer to generate big files faster. WOFF and WOFF2 fonts are now supported, they are automatically converted to TTF or OTF fonts (note that it may take some time, prefer TTF or OTF if performance is important for you).

Working with fonts is provided by fontTools, an incredible Python library with a lot of useful features. Thanks a lot to the developers for their hard work on this library, we may benefit from additional features in the future.

For example, fontTools could help us to get one feature back: colored emojis are not supported anymore. With Cairo, WeasyPrint was able to include images for emojis, with a pretty bad quality due to a low resolution used for image resizing. This possibility is not included anymore, even if emojis rendered as "normal black characters" are correctly handled.

Kerning should be better with this new version of Pango. Requiring version 1.44 of Pango gives us the possibility not to round glyph positions, and thus finely handle kerning with small font sizes.

One last change: text-related modules have been reorganized. For users, the most important consequence of these modifications is that FontConfiguration is now part of weasyprint.text.fonts. Don’t forget to change your imports if you use this class!

Performance

Now that we generate our own PDF files, we have good news: your generated PDF documents will probably be smaller. As many rules, this one is not always, always true… But you can be pretty optimistic: for our reference tests, PDF size is between 50% and 100% of the same document generated by WeasyPrint 52.

Speed is another question. Dropping Cairo and replacing it by manual PDF generation made WeasyPrint globally slower. Why? The obvious answer is: Cairo is written in C, pydyf is written in Python. It’s obvious, but it’s also wrong! Of course, C is faster but that’s not the main reason. As explained in the documentation, code simplicity, maintainability and flexibility are the most important goals for this library, and that’s true for PDF generation too.

Without Cairo, the way fonts and images are included also changed. Depending on the formats and properties of your document, you may get very different results regarding speed and memory consumption. As usual, testing various formats is the best way to get a setup adapted for your use.

But in 53.0b2 we implemented an old idea: lazy CSS loading. That was Simon’s idea, and that was a good idea.

CSS values used to be calculated for each HTML node after all the stylesheets are found. But among all the CSS properties, many are actually useless and do not need to be calculated at all. Why calculating the value of color when we already have display: none?

This idea appeared almost as soon as cascading was handled by WeasyPrint, but it was seen as pretty complicated. Actually, it wasn’t: less than one hour was necessary to get a proof of concept. Who said that developers are bad at time estimation?

Lazy CSS loading greatly improved WeasyPrint’s speed, at least for documents with both a lot of CSS and HTML. It also improved memory consumption, as we don’t have to store all the CSS values anymore.

It’s Time to Test

All in all, here is our advice: you should test 53.0b2.

WeasyPrint 53 will be a major release, and we really hope that it will improve your workflow. Please report any problem we could get with the current beta, we’ll do our best to provide a high-quality release that fits your needs.

Don’t hesitate to tell us what you want in this short survey. Generating PDF documents with our own library gives us the possibility to add features more easily in the future, and to fix many bugs. Test, don’t hesitate to report issues, and you’ll safely benefit from the new version’s improvements as soon as it is released.