rvid.tex-runner 0.2.0

Utility functions for rendering XeLaTeX documents from Python

rvid.tex-runner

A small utility to ease programmatic usage of LaTeX from Python.

Calling XeLaTeX on output

If you just run the xelatex command, you'll get a bunch of temp files output to your current working directory. You also get a few screenfulls of debug out that you only really want to see if something goes wrong. No big deal, but a bit of faff.

The function rvid.tex_runner.make_pdf_at_path() finds the xelatex-command, creates a temp-directory, runs the command, moves the PDF-file into the location you specified and then cleans up all the temp files.

def make_pdf_at_path(
    tex_content=a_string_that_holds_tex_source,
    target_path="/home/apa/bepa.pdf"
) 

If you want the resulting PDF returned as a bytestream instead written to disk, just use rvid.tex_runner.make_pdf_as_bytestream() instead.

When there is an error

XeLaTeX is run in nonstop mode and will not drop to an interactive prompt if there is a problem. If a non-zero exit code is returned, the XeLaTeX output will be dumped to stdout, even in silent mode.

Handling paths to external resources

To handle external resources that are needed to build your PDF files, tex-runner has a concept of ExternalResource. This is a Python object that contains a sequence of absolute file paths and a relative target path (basedir) where your .tex files expect to be able to include them from. For example:

ExternalResource(
    basedir="images",
    files=[
        "/Users/sean.banan/tex/img1.png",
        "/Users/sean.banan/tex/img2.png",
    ]
)

This concept also comes in handy if you have differing paths in different deployment environments, since it allows you to abstract that away programmatically.

Auto-generating ExternalResource-libraries

There is a utility function for auto-generating ExternalResource-objects from filesystem paths:

>>> make_external_resource_library(source_directory="c:/pix", relative_target_directory="img")
ExternalResource(basedir="img", files=["c:/pix/q1.jpg"])

Debugging

Change rvid.tex_runner.latex:make_pdf_in_tempdir() so that it doesn't delete the tempdir after finishing the run.