LaTeX¶

Author: Marcel Simader
Date: 29.06.2021

New in version v0.1.0.

LaTeXResource¶

class LaTeXResource(*, can_reopen=False)¶

An abstract base class for the LaTeX extension of TeXResource. This class requires to_latex() to be implemented, and maps the methods __str__(), and to_tex() to this method.

abstract to_latex()¶

Converts this object to a LaTeX string.

to_tex()¶

Converts this object to a TeX string.

LaTeXDocument¶

class LaTeXDocument(path, document_class='article', document_options='a4paper, 12pt', default_packages=(), title=None, subtitle=None, author=None, *, show_date=False, show_page_numbers=False, line_wrap_length=None, encoding='utf-8')¶

LaTeXDocument represents a LaTeX document that can be written to in a similar fashion as a text file. To do so, one must use the context manager of this object, or retrieve the file path to write to it directly. The context manager will return the document object itself, which contains the preamble and body handler for writing to the document.

Example usage of the context manager:

with LaTeXDocument("abc.tex") as latex_document:
        latex_document.use_package("abc123", "cde456")
        latex_document.body.write(r"This is some \LaTeX.")

For extensions to the functionality of this class, see LaTeXEnvironment as base class.

Warning

The data stored in and added to this LaTeXDocument instance is only saved once the context manager is closed!

Parameters

path (Union[AnyStr, PathLike]) – the path to the main .tex file
document_class (AnyStr) – the name of the document class to include at the start of the document
document_options (AnyStr) – the options to pass to the chosen document class
default_packages (Collection[AnyStr]) – the packages to include right at the beginning of initialization
title (Optional[AnyStr]) – the title of the document
subtitle (Optional[AnyStr]) – the subtitle of the document, is ignored unless title is not None
author (Optional[AnyStr]) – the author of the document
show_date (bool) – keyword-only argument, determines whether or not to include a date in the title
show_page_numbers (bool) – keyword-only argument, determines whether or not to show page numbers on all pages
line_wrap_length (Optional[int]) – keyword-only argument, if set to an int this value will dictate how long a line can be before a pseudo soft-wrap is applied (see LaTeXHandler for details)
encoding (str) – the string specifying how to encode the bytes of text stored in this instance, defaults to utf-8

property path: os.PathLike¶

Returns: the path of the .tex file that is to be written

property successfully_saved_tex: bool¶

Returns: whether or not this LaTeX document has been successfully saved to its .tex path

property preamble: SEPTeX.TeXBase.TeXHandler¶

Raises: TeXError – if the document has not been opened

property body: SEPTeX.TeXBase.TeXHandler¶

Raises: TeXError – if the document has not been opened

property document_class: AnyStr¶

Returns: the document class

property document_options: AnyStr¶

Returns: the options passed to the document class

property definitions: Tuple[Tuple]¶

Returns: a tuple of tuples of the definitions already placed in this instance, one entry consists of a definition key (e.g. “usepackage”), and a definition value (e.g. “amsmath”)

property line_wrap_length: Optional[int]¶

Returns: the line wrap length of the body, see TeXHandler.line_wrap_length for details

property title: Optional[AnyStr]¶

Returns: the title of this document

property subtitle: Optional[AnyStr]¶

Returns: the subtitle of this document

property author: Optional[AnyStr]¶

Returns: the author of this document

property show_date: bool¶

Returns: whether or not the title shows date of creation

property show_page_numbers: bool¶

Returns: whether or not the document has page numbers

property encoding¶

Returns: the text encoding used by this document

use_package(*package)¶

Include a usepackage statement in this document. This function checks the list of already included packages to avoid duplicates.

Parameters: package (AnyStr) – the name or names of the package to include

use_tikz_library(*library)¶

Include a usetikzlibrary statement in this document. This function checks the list of already included libraries to avoid duplicates. This function implicitly includes the TikZ package.

Parameters: library (AnyStr) – the name or names of the TikZ library to include

page_break()¶

Inserts a page break.

to_pdf(out_file_path, overwrite=False, delete_aux_files=True, engine='pdflatex', *custom_options)¶

Compile the LaTeX document at path to a PDF file. The document must be closed before attempting to perform this operation.

Parameters

out_file_path (Union[os.PathLike, AnyStr]) – which path to output the file to
overwrite (bool) – whether or not to overwrite a file that already exists
delete_aux_files (bool) – delete the generated auxiliary files after compilation of the document is complete
engine (Literal[pdftex, pdflatex]) – which engine to use for conversion between the TeX and PDF files (specifically which string to use to call said engine), currently only pdftex/pdflatex is supported
custom_options (AnyStr) – options to directly pass to the engine which are not included as argument to this function

Raises

TeXError – if the document was still opened while calling this function or if there was an error while executing the engine command in the subshell
FileExistsError – if the file is already exists and overwrite is not set to True

to_latex()¶

Converts this object to a LaTeX string.

LaTeXEnvironment¶

class LaTeXEnvironment(parent_env, environment_name, options='', required_packages=(), indent_level=1)¶

Base class for an environment in a LaTeX document (see LaTeXDocument). This class usually acts as base class for extensions that add simpler ways to write to an environment but it can also be used directly, if an environment that is not necessarily worth implementing is desired.

Example usage of this class with two nested context managers:

...
with LaTeXEnvironment(document, "center") as env_center:
        with LaTeXEnvironment(env_center, "equation", required_packages=("amsmath",)) as env_eq:
                env_eq.write(r"\forall a, b \in \mathbb{R}, \exists c \in \mathbb{R} \colon a^2 + b^2 = c^2")

Note

When inheriting from this class, one should usually only overwrite the following methods: __init__(), write(), and newline(). Overwriting other methods is allowed if needed, unless marked as final.

It is highly recommended to use either a super call to this class or at least the private methods _write() and _newline() to handle internal write calls to the TeXHandler instance, since these may perform additional actions.

Parameters

parent_env (Union[LaTeXDocument, LaTeXEnvironment]) – the parent LaTeXDocument or LaTeXEnvironment to this environment
environment_name (AnyStr) – the name of the environment, this value is put for the \begin and \end commands
options (AnyStr) – the options to pass to the environment, this value is put after the \begin command
required_packages (Collection[AnyStr]) – the packages which are required to use this environment
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

property document: SEPTeX.LaTeX.LaTeXDocument¶

Returns: the root document of this environment stack
Raises: TeXError – if one of the parent environments is neither of type LaTeXDocument nor LaTeXEnvironment

property parent_env: Union[SEPTeX.LaTeX.LaTeXDocument, SEPTeX.LaTeX.LaTeXEnvironment]¶

Returns: the parent TeXResource of this environment

property parent_handler: SEPTeX.TeXBase.TeXHandler¶

Returns: the handler of the parent_env resource, in the case of LaTeXDocument this function will return the handler of the body

property environment_name: AnyStr¶

Returns: the name of this environment

property options: AnyStr¶

Returns: the options passed to this environment

property begin_text: str¶

Returns: the definition text to open this environment in the LaTeX source

property end_text: str¶

Returns: the definition text to close this environment in the LaTeX source

write(s)¶

Shorthand for writing to the handler of this instance.

Raises: TeXError – if the document has not been opened

newline()¶

Shorthand for writing a newline the handler of this instance.

Raises: TeXError – if the document has not been opened

to_latex()¶

Converts this object to a LaTeX string.

Center¶

final class Center(parent_env, indent_level=1)¶

Center represents the standard LaTeX center environment. It has no options and no required packages.

Parameters

parent_env (Union[LaTeXDocument, LaTeXEnvironment]) – the parent LaTeXDocument or LaTeXEnvironment to this environment
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

Figure¶

class Figure(parent_env, caption=None, label=None, options='h!', indent_level=1)¶

Figure represents the standard LaTeX figure environment. It can be initialized with a caption, a label, and options. The options default to h! to force placement at the location of the definition of the figure.

When referencing this figure, use the label property as follows, as it adds the fig: prefix automatically when left out and makes referencing easier and less error-prone:

with LaTeXDocument("ham.tex") as doc:
        f1 = Figure(doc, "Caption.", "a-label")
        assert f1.label == "fig:a-label"

        f2 = Figure(doc, "Spam Ham Caption.", "fig:label-label")
        assert f2.label == "fig:label-label"

Parameters

parent_env (Union[LaTeXDocument, LaTeXEnvironment]) – the parent LaTeXDocument or LaTeXEnvironment to this environment
caption (Optional[AnyStr]) – the caption of the figure, may be None
label (Optional[AnyStr]) – the label of the figure, can include fig: as prefix but if this is absent the prefix will be added automatically by the label property, may be None
options (AnyStr) – the options to pass to the environment, this value is put after the \begin command
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

property caption: Optional[AnyStr]¶

Returns: the caption of this figure

property label: Optional[AnyStr]¶

Returns: the label referencing this figure, automatically adds fig: prefix if missing

write_figure_table()¶

Write a table of the figures in this document at this location.

MathsEnvironment¶

class MathsEnvironment(parent_env, env_name, star=True, indent_level=1)¶

MathsEnvironment represents a base implementation of any amsmath math environment which uses a star, and non-star version. It can be passed the star flag upon creation, which will be inserted at the start of the environment name. When writing to this instance, text will automatically be formatted using tex_maths_string() and the newline() method will write a double backslash \\ instead of the newline character \n.

Parameters

parent_env (Union[LaTeXDocument, LaTeXEnvironment]) – the parent LaTeXDocument or LaTeXEnvironment to this environment
env_name (str) – the parent environment or document to this environment
star (bool) – whether or not to prefix the environment name with a star like so: *env_name or env_name
indent_level (int) – the number of tab characters to indent this environment relative to the parent environment

write(s)¶

Shorthand for writing to the handler of this instance. Automatically applies tex_maths_string() to every s object passed to it.

Raises: TeXError – if the document has not been opened

newline()¶

Shorthand for writing a newline to the handler of this instance. Instead of \n this method places \\ to cause a line break.

Raises: TeXError – if the document has not been opened