PyLaTeX Documentation

PyLaTeX is designed for two distinct workflows:

1. Generating full PDFs: Best used when all content in the PDF is generated by Python (e.g., exporting data from a database).
2. Generating LaTeX snippets: Best used when some text is written manually, but specific elements (like Matplotlib plots) need to be automatically generated and inserted into a report.

PyLaTeX is designed around two primary tasks:

1. Generating LaTeX code: Using a system of Python classes to represent LaTeX components.
2. Compiling LaTeX documents: Turning that generated code into a document (like a PDF).

You can use PyLaTeX to wrap existing LaTeX code or to build new documents from scratch using its class hierarchy. Generated code can either be exported as raw LaTeX strings or compiled into a file.

PyLaTeX uses Container objects to group other LaTeX classes. Containers behave like Python lists: they can be indexed and appended to.

• Document: The most critical container. It represents a full LaTeX document. Use Document.generate_pdf() to compile the document into a PDF file. Unless you are only generating small snippets, you should wrap your content in a Document object.
• Sections: PyLaTeX provides container classes for standard LaTeX sections, such as Section, Subsection, and Subsubsection. These can also be appended to and can contain other objects.

By default, PyLaTeX escapes almost all strings for security and to ensure valid LaTeX generation. If you need to use raw LaTeX strings that should not be escaped, you have two primary methods:

1. Use NoEscape

Use the NoEscape string type (a subclass of str). This tells PyLaTeX to treat the string as raw LaTeX. Warning: Appending a NoEscape string to a regular str will result in a regular str (the most conservative type is chosen). Use it as a standalone object or ensure the final result remains NoEscape.

2. Disable escaping on a container

You can set the LatexObject.escape attribute to False on a container object. Warning: This affects all strings added to that object. Only use this for containers that are guaranteed not to hold potentially unsafe or unformatted text.

If you are using Ubuntu, you can install the necessary LaTeX processing tools and extra packages using apt-get. This includes latexmk and various TeX Live packages required for scientific and picture-based LaTeX content.

sudo apt-get install texlive-pictures texlive-science \
texlive-latex-extra latexmk

To add support for new LaTeX features, extend the existing base classes. While all objects derive from LatexObject, it is usually more effective to extend specific base subclasses that match your needs, such as:

• Environment
• CommandBase

Consult the API documentation to find the most appropriate base class for your extension.

Certain PyLaTeX features require additional libraries. You can install these dependencies using pip extras.

To install support for matrices, matplotlib, and quantities, run:

pip install pylatex[matrices]

Note: The documentation mentions that features requiring additional libraries include:

• matrices (requires Numpy)
• matplotlib
• quantities

Install the PyLaTeX library using pip. Note that after installing the Python package, you must also install a LaTeX processor (like TeX Live) and other system dependencies to enable file compilation.

pip install pylatex

If your LaTeX compiler requires multiple passes to complete a document (e.g., to resolve references or citations), PyLaTeX can handle this automatically if latexmk is installed on your system. PyLaTeX will detect the presence of latexmk and use it instead of a standard LaTeX compiler to ensure the document is fully processed.

To enable this functionality, install latexmk using your system's package manager.

Most PyLaTeX classes inherit from LatexObject and provide methods to retrieve their LaTeX representation:

• LatexObject.dumps(): Returns the LaTeX-formatted code as a string.
• LatexObject.generate_tex(): Writes the LaTeX-formatted code directly to a file.

You can create custom LaTeX commands using the Command class. Commands support:

• Arguments: Supplied via {}.
• Options: Supplied via [].

Arguments and options can be passed as single strings or lists. For more complex structures, you can use Arguments or Options objects.