Once you have WeasyPrint installed </install>
, you should have a weasyprint
executable. Using it can be as simple as this:
weasyprint http://weasyprint.org /tmp/weasyprint-website.pdf
You may see warnings on stderr about unsupported CSS properties. See command-line-api
for the details of all available options.
In particular, the -s
option can add a filename for a user stylesheet <stylesheet-origins>
. For quick experimentation however, you may not want to create a file. In bash or zsh, you can use the shell’s redirection instead:
weasyprint http://weasyprint.org /tmp/weasyprint-website.pdf \
-s <(echo 'body { font-family: serif !important }')
If you have many documents to convert you may prefer using the Python API in long-lived processes to avoid paying the start-up costs every time.
weasyprint
The Python version of the above example goes like this:
from weasyprint import HTML
HTML('http://weasyprint.org/').write_pdf('/tmp/weasyprint-website.pdf')
… or with the inline stylesheet:
from weasyprint import HTML, CSS
HTML('http://weasyprint.org/').write_pdf('/tmp/weasyprint-website.pdf',
stylesheets=[CSS(string='body { font-family: serif !important }')])
If you have a file name, an absolute URL or a readable file-like object, you can just pass it to HTML
or CSS
to create an instance. Alternatively, use a named argument so that no guessing is involved:
from weasyprint import HTML
HTML('../foo.html') # Same as …
HTML(filename='../foo.html')
HTML('http://weasyprint.org') # Same as …
HTML(url='http://weasyprint.org')
HTML(sys.stdin) # Same as …
HTML(file_obj=sys.stdin)
If you have a byte string or Unicode string already in memory you can also pass that, although the argument must be named:
from weasyprint import HTML
# HTML('<h1>foo') would be filename
HTML(string='''
<h1>The title</h1>
<p>Content goes here
''')
CSS(string='@page { size: A3; margin: 1cm }')
If you have @font-face
rules in your CSS, you have to create a FontConfiguration
object:
from weasyprint import HTML, CSS
from weasyprint.fonts import FontConfiguration
font_config = FontConfiguration()
html = HTML(string='<h1>The title</h1>')
css = CSS(string='''
@font-face {
font-family: Gentium;
src: url(http://example.com/fonts/Gentium.otf);
}
h1 { font-family: Gentium }''', font_config=font_config)
html.write_pdf(
'/tmp/example.pdf', stylesheets=[stylesheet],
font_config=font_config)
Once you have a HTML
object, call its ~HTML.write_pdf
or ~HTML.write_png
method to get the rendered document in a single PDF or PNG file.
Without arguments, these methods return a byte string in memory. If you pass a file name or a writable file-like object, they will write there directly instead. (Warning: with a filename, these methods will overwrite existing files silently.)
weasyprint.document
If you want more than a single PDF, the ~weasyprint.HTML.render
method gives you a Document
object with access to individual Page
objects. Thus you can get the number of pages, their size1, the details of hyperlinks and bookmarks, etc. Documents also have ~Document.write_pdf
and ~Document.write_png
methods, and you can get a subset of the pages with ~Document.copy()
. Finally, for ultimate control, ~Page.paint
individual pages anywhere on any type of cairo surface.
See the python-api
for details. A few random example:
# Write odd and even pages separately:
# Lists count from 0 but page numbers usually from 1
# [::2] is a slice of even list indexes but odd-numbered pages.
document.copy(document.pages[::2]).write_pdf('odd_pages.pdf')
document.copy(document.pages[1::2]).write_pdf('even_pages.pdf')
# Write one PNG image per page:
for i, page in enumerate(document.pages):
document.copy([page]).write_png('page_%s.png' % i)
# Some previous versions of WeasyPrint had a method like this:
def get_png_pages(document):
"""Yield (png_bytes, width, height) tuples."""
for page in document.pages:
yield document.copy([page]).write_png()
# Print the outline of the document.
# Output on http://www.w3.org/TR/CSS21/intro.html
# 1. Introduction to CSS 2.1 (page 2)
# 1. A brief CSS 2.1 tutorial for HTML (page 2)
# 2. A brief CSS 2.1 tutorial for XML (page 5)
# 3. The CSS 2.1 processing model (page 6)
# 1. The canvas (page 7)
# 2. CSS 2.1 addressing model (page 7)
# 4. CSS design principles (page 8)
def print_outline(bookmarks, indent=0):
for i, (label, (page, _, _), children) in enumerate(bookmarks, 1):
print('%s%d. %s (page %d)' % (
' ' * indent, i, label.lstrip('0123456789. '), page))
print_outline(children, indent + 2)
print_outline(document.make_bookmark_tree())
# PostScript on standard output:
surface = cairo.PSSurface(sys.stdout, 1, 1)
context = cairo.Context(surface)
for page in document.pages:
# 0.75 = 72 PostScript point per inch / 96 CSS pixel per inch
surface.set_size(page.width * 0.75, page.height * 0.75)
page.paint(context, scale=0.75)
surface.show_page()
surface.finish()
WeasyPrint goes through a URL fetcher to fetch external resources such as images or CSS stylesheets. The default fetcher can natively open file and HTTP URLs, but the HTTP client does not support advanced features like cookies or authentication. This can be worked-around by passing a custom url_fetcher
callable to the HTML
or CSS
classes. It must have the same signature as ~weasyprint.default_url_fetcher
.
Custom fetchers can choose to handle some URLs and defer others to the default fetcher:
from weasyprint import default_url_fetcher, HTML
def my_fetcher(url):
if url.startswith('graph:'):
graph_data = map(float, url[6:].split(','))
return dict(string=generate_graph(graph_data),
mime_type='image/png')
else:
return weasyprint.default_url_fetcher(url)
source = '<img src="graph:42,10.3,87">'
HTML(string=source, url_fetcher=my_fetcher).write_pdf('out.pdf')
Flask-WeasyPrint makes use of a custom URL fetcher to integrate WeasyPrint with a Flask application and short-cut the network for resources that are within the same application.
Most errors (unsupported CSS property, missing image, ...) are not fatal and will not prevent a document from being rendered.
WeasyPrint uses the logging
module from the Python standard library to log these errors and let you know about them. When WeasyPrint is launched in a terminal, logged messaged will go to stderr by default. You can change that by configuring the weasyprint
logger object:
import logging
logger = logging.getLogger('weasyprint')
logger.handlers = [] # Remove the default stderr handler
logger.addHandler(logging.FileHandler('/path/to/weasyprint.log'))
The INFO
level is used to report the rendering progress. It is useful to get feedback when WeasyPrint is launched in a terminal (using the --verbose
option), or to give this feedback to end users when used as a library. To catch these logs, you can for example use a filter:
import logging
class LoggerFilter(logging.Filter):
def filter(self, record):
if record.level == logging.INFO:
print(record.getMessage())
return False
logger = logging.getLogger('weasyprint')
logger.addFilter(LoggerFilter())
See the documentation of the logging
module for details.
WeasyPrint Navigator is a very limited web browser, running in your web browser. Start it with:
python -m weasyprint.navigator
… and open your browser at http://127.0.0.1:5000/.
It does not support cookies, forms, or many other things that you would expect from a “real” browser. It only shows the PNG output from WeasyPrint with overlaid clickable hyperlinks. It is mostly useful for playing and testing.
If you get an exception during rendering, it is probably a bug in WeasyPrint. Please copy the full traceback and report it on our issue tracker.
HTML documents are rendered with stylesheets from three origins:
- The HTML5 user agent stylesheet (defines the default appearance of HTML elements);
- Author stylesheets embedded in the document in
<style>
elements or linked by<link rel=stylesheet>
elements; - User stylesheets provided in the API.
Keep in mind that user stylesheets have a lower priority than author stylesheets in the cascade, unless you use !important in declarations to raise their priority.
Pages in the same document do not always have the same size.↩