Library usage

Understanding PyLaTeX

PyLaTeX is structured around two main tasks: Generating LaTeX code, and compiling LaTeX documents. The package is flexible, and can either work with your pre-existing code or generate new code with its system of classes. In turn, LaTeX code can be used to generate a document, or can be exported as-is.

The Classes

PyLaTeX uses a set of classes to turn LaTeX document generation into a set of pythonic components. For example, a Document might be comprised of Section objects, which in turn might have List objects, Figure objects, or custom Command objects.

Classes can be part of a single document, or can act as pieces on their own. With the dumps method, most classes can return their LaTeX-formatted code, and with the generate_tex method, this code can be written to a file.

Containers / Documents

A Container is an object that groups other LaTeX classes. Containers function like lists; they can be indexed and appended to.

One of the most important container classes is the Document class. Documents create a full LaTeX document that can create a PDF file with generate_pdf . Unless you are only generating LaTeX snippets, you will likely want to enclose your code inside a Document.

Additionally, a number of section containers are available, which correspond to the standard \section commands of LaTeX. As with documents, these can be appended to. A Section can further include a Subsection or a Subsubsection object.

Tables, Images, Math, etc.

PyLaTeX has a number of classes that are useful in generating difficult-to-format LaTeX code. See the API documentation and code examples for information on a specific environment.

Commands, Options, and Arguments

Although PyLaTeX has implemented many useful commands, it is easy to create a custom command with the Command class. Commands can be supplied with {} arguments or [] options, with either a single option as a string, or multiple options in a list.

Additionally, Options and Arguments can be placed in an Options object or a Arguments object.

Formatting Strings

A number of functions are available in utils that are helpful in formatting text. For example, the functions bold and italic exist to format text appropriately.

Extending PyLaTeX

Because of all the base classes supplied by PyLaTeX, it is very easy to extend its support in LaTeX features. Just pick one of the existing (base) classes that fits best and extend that with the needed functionality.

All LaTeX objects come from LatexObject , but it is probably more useful to extend one of the other base subclasses, like Environment or CommandBase. Consult the API documentation to see the variety of base classes available for use.

Plain LaTeX Strings

Although PyLaTeX contains classes and functions to make generating LaTeX formatted text easy, at its core it is a nice wrapper around string manipulations. This is why all of them also accept raw LaTeX strings. That way you can just use regular LaTeX strings when something is not supported directly by the library.

Unescaping Strings

Using regular LaTeX strings may not be as simple as is seems though, because by default almost all strings are escaped. This is done for security reasons and to make sure valid LaTeX code will be generated at all times. However, there are cases where raw LaTeX strings should just be used directly in the document. This is why the NoEscape string type exists. This is just a subclass of str, but it will not be escaped. One important thing to note about this class is that appending a NoEscape type string to a regular string results in a regular string, since one type has to be chosen and the most conservative approach is taken.

Another way to make sure strings are not escaped is by setting the escape attribute to False on the class that is the container of the string. Keep in mind though that any strings that are added to that object will not be escaped when doing this. So, only use this method for objects that don’t contain possibly unsafe strings.