Hello World!
""" MEDIABOX = pymupdf.paper_rect("letter") # output page format: Letter WHERE = MEDIABOX + (36, 36, -36, -36) # leave borders of 0.5 inches story = pymupdf.Story(html=HTML) # create story from HTML writer = pymupdf.DocumentWriter("output.pdf") # create the writer more = 1 # will indicate end of input once it is set to 0 while more: # loop outputting the story device = writer.begin_page(MEDIABOX) # make new page more, _ = story.place(WHERE) # layout into allowed rectangle story.draw(device) # write on page writer.end_page() # finish page writer.close() # close output file .. note:: The above effect (sans-serif and blue text) could have been achieved by using a separate CSS source like so:: import pymupdf CSS = """ body { font-family: sans-serif; color: blue; } """ HTML = """Hello World!
""" # the story would then be created like this: story = pymupdf.Story(html=HTML, user_css=CSS) ----- The Python API variant -- everything is created programmatically:: import pymupdf MEDIABOX = pymupdf.paper_rect("letter") WHERE = MEDIABOX + (36, 36, -36, -36) story = pymupdf.Story() # create an empty story body = story.body # access the body of its DOM with body.add_paragraph() as para: # store desired content para.set_font("sans-serif").set_color("blue").add_text("Hello World!") writer = pymupdf.DocumentWriter("output.pdf") more = 1 while more: device = writer.begin_page(MEDIABOX) more, _ = story.place(WHERE) story.draw(device) writer.end_page() writer.close() Both variants will produce the same output PDF. ----- .. _RecipesStories_B: How to use Images ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Images can be referenced in the provided HTML source, or the reference to a desired image can also be stored via the Python API. In any case, this requires using an :ref:`Archive`, which refers to the place where the image can be found. .. note:: Images with the binary content embedded in the HTML source are **not supported** by stories. We extend our "Hello World" example from above and display an image of our planet right after the text. Assuming the image has the name "world.jpg" and is present in the script's folder, then this is the modified version of the above Python API variant:: import pymupdf MEDIABOX = pymupdf.paper_rect("letter") WHERE = MEDIABOX + (36, 36, -36, -36) # create story, let it look at script folder for resources story = pymupdf.Story(archive=".") body = story.body # access the body of its DOM with body.add_paragraph() as para: # store desired content para.set_font("sans-serif").set_color("blue").add_text("Hello World!") # another paragraph for our image: with body.add_paragraph() as para: # store image in another paragraph para.add_image("world.jpg") writer = pymupdf.DocumentWriter("output.pdf") more = 1 while more: device = writer.begin_page(MEDIABOX) more, _ = story.place(WHERE) story.draw(device) writer.end_page() writer.close() ----- .. _RecipesStories_C: How to Read External HTML and CSS for a Story ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These cases are fairly straightforward. As a general recommendation, HTML and CSS sources should be **read as binary files** and decoded before using them in a story. The Python `pathlib.Path` provides convenient ways to do this:: import pathlib import pymupdf htmlpath = pathlib.Path("myhtml.html") csspath = pathlib.Path("mycss.css") HTML = htmlpath.read_bytes().decode() CSS = csspath.read_bytes().decode() story = pymupdf.Story(html=HTML, user_css=CSS) ----- .. _RecipesStories_D: How to Output Database Content with Story Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This script demonstrates how to report SQL database content using an **HTML template**. The example SQL database contains two tables: 1. Table "films" contains one row per film with the fields **"title"**, **"director"** and (release) **"year"**. 2. Table "actors" contains one row per actor and film title (fields (actor) **"name"** and (film) **"title"**). The story DOM consists of a template for one film, which reports film data together with a list of casted actors. **Files:** * `docs/samples/filmfestival-sql.py` * `docs/samples/filmfestival-sql.db` |toggleStart| .. literalinclude:: samples/filmfestival-sql.py |toggleEnd| ----- .. _RecipesStories_E: How to Integrate with Existing PDFs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because a :ref:`DocumentWriter` can only write to a new file, stories cannot be placed on existing pages. This script demonstrates a circumvention of this restriction. The basic idea is letting :ref:`DocumentWriter` output to a PDF in memory. Once the story has finished, we re-open this memory PDF and put its pages to desired locations on **existing** pages via method :meth:`Page.show_pdf_page`. **Files:** * `docs/samples/showpdf-page.py` |toggleStart| .. literalinclude:: samples/showpdf-page.py |toggleEnd| ----- .. _RecipesStories_F: How to Make Multi-Columned Layouts and Access Fonts from Package `pymupdf-fonts`_ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This script outputs an article (taken from Wikipedia) that contains text and multiple images and uses a 2-column page layout. In addition, two "Ubuntu" font families from package `pymupdf-fonts`_ are used instead of defaulting to Base-14 fonts. Yet another feature used here is that all data -- the images and the article HTML -- are jointly stored in a ZIP file. **Files:** * `docs/samples/quickfox.py` * `docs/samples/quickfox.zip` |toggleStart| .. literalinclude:: samples/quickfox.py |toggleEnd| ----- .. _RecipesStories_G: How to Make a Layout which Wraps Around a Predefined "no go area" Layout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a demo script using PyMuPDF's Story class to output text as a PDF with a two-column page layout. The script demonstrates the following features: * Layout text around images of an existing ("target") PDF. * Based on a few global parameters, areas on each page are identified, that can be used to receive text layouted by a Story. * These global parameters are not stored anywhere in the target PDF and must therefore be provided in some way: - The width of the border(s) on each page. - The fontsize to use for text. This value determines whether the provided text will fit in the empty spaces of the (fixed) pages of target PDF. It cannot be predicted in any way. The script ends with an exception if target PDF has not enough pages, and prints a warning message if not all pages receive at least some text. In both cases, the FONTSIZE value can be changed (a float value). - Use of a 2-column page layout for the text. * The layout creates a temporary (memory) PDF. Its produced page content (the text) is used to overlay the corresponding target page. If text requires more pages than are available in target PDF, an exception is raised. If not all target pages receive at least some text, a warning is printed. * The script reads "image-no-go.pdf" in its own folder. This is the "target" PDF. It contains 2 pages with each 2 images (from the original article), which are positioned at places that create a broad overall test coverage. Otherwise the pages are empty. * The script produces "quickfox-image-no-go.pdf" which contains the original pages and image positions, but with the original article text laid out around them. **Files:** * `docs/samples/quickfox-image-no-go.py` * `docs/samples/quickfox-image-no-go.pdf` * `docs/samples/quickfox.zip` |toggleStart| .. literalinclude:: samples/quickfox-image-no-go.py |toggleEnd| ----- .. _RecipesStories_H: How to Output an HTML Table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Outputting HTML tables is supported as follows: * Flat table layouts are supported ("rows x columns"), no support of the "colspan" / "rowspan" attributes. * Table header tag :htmlTag:`th` supports attribute "scope" with values "row" or "col". Applicable text will be bold by default. * Column widths are computed automatically based on column content. They cannot be directly set. * Table **cells may contain images** which will be considered in the column width calculation magic. * Row heights are computed automatically based on row content - leading to multi-line rows where needed. * The potentially multiple lines of a table row will always be kept together on one page (respectively "where" rectangle) and not be split. * Table header rows are only **shown on the first page / "where" rectangle.** * The "style" attribute is ignored when given directly in HTML table elements. Styling for a table and its elements must happen separately, in CSS source or within the :htmlTag:`style` tag. * Styling for :htmlTag:`tr` elements is not supported and ignored. Therefore, a table-wide grid or alternating row background colors are not supported. One of the following example scripts however shows an easy way to deal with this limitation. **Files:** * `docs/samples/table01.py` This script reflects basic features. |toggleStart| .. literalinclude:: samples/table01.py |toggleEnd| * `docs/samples/national-capitals.py` Advanced script extending table output options using simple additional code: - Multi-page output simulating **repeating header rows** - Alternating table row background colors - Table rows and columns delimited by gridlines - Table rows dynamically generated / filled with data from an SQL database |toggleStart| .. literalinclude:: samples/national-capitals.py |toggleEnd| ----- .. _RecipesStories_I: How to Create a Simple Grid Layout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By creating a sequence of :ref:`Story` objects within a grid created via the :ref:`make_table