latexwalker — Calling Parsers for LaTeX Code¶

The latexwalker module provides a simple API for parsing LaTeX snippets, and representing the contents using a data structure based on node classes.

LatexWalker will understand the syntax of most common macros. However, latexwalker is NOT a replacement for a full LaTeX engine. (Originally, latexwalker was designed to extract useful text for indexing for text database searches of LaTeX content.)

Since pylatexenc 3, the parsing work itself is carried out by parser objects, which are specialized in parsing a given LaTeX construct and which are provided by pylatexenc.latexnodes.parsers. A LatexWalker instance holds the LaTeX code along with the information required to parse it (the “latex context”, see below), and it runs such parser objects on that code with LatexWalker.parse_content().

The result of the parsing is a node tree, along with any information about parsing state changes that the parsed code caused (say, a \newcommand). The nodes are instances of the classes provided in pylatexenc.latexnodes.nodes, and lists of nodes are wrapped in a LatexNodeList object. (For compatibility with earlier versions, the node classes can also be imported directly from pylatexenc.latexwalker.)

Simple example usage:

>>> from pylatexenc.latexwalker import LatexWalker
>>> from pylatexenc.latexnodes.nodes import LatexEnvironmentNode
>>> w = LatexWalker(r"""
... \textbf{Hi there!} Here is \emph{a list}:
... \begin{enumerate}[label=(i)]
... \item One
... \item Two
... \end{enumerate}
... and $x$ is a variable.
... """)
>>> nodelist, parsing_state_delta = w.parse_content()
>>> nodelist[1].macroname
'textbf'
>>> (nodelist[1].pos, nodelist[1].pos_end)
(1, 19)
>>> nodelist[1].latex_verbatim()
'\\textbf{Hi there!}'
>>> nodelist[5].isNodeType(LatexEnvironmentNode)
True
>>> nodelist[5].environmentname
'enumerate'
>>> nodelist[7].latex_verbatim()
'$x$'

Macro, environment and specials arguments are collected in a pylatexenc.latexnodes.ParsedArguments object stored as the node’s nodeargd attribute. Use pylatexenc.latexnodes.ParsedArgumentsInfo to inspect them, by position or by argument name:

>>> from pylatexenc.latexnodes import ParsedArgumentsInfo
>>> arguments = ParsedArgumentsInfo(node=nodelist[5]).get_all_arguments_info()
>>> arguments[0].get_content_nodelist().latex_verbatim()
'label=(i)'

You can also use latexwalker directly in command-line, producing a human-readable node tree or JSON:

$ latexwalker --code '\textit{italic} text'
--- NODES ---

* \textit
    {.}: Group:
        * 'italic'
* ' text'

-------------

$ latexwalker --output-format=json --code '\textit{italic} text'
{
  "nodelist": [
    {
      "nodetype": "LatexMacroNode",
      "pos": 0,
      "pos_end": 15,
      "parsing_state": {
[...]

$ latexwalker --help
[...]

The parser can be influenced by specifying a collection of known macros and environments (the “latex context”) that are specified using pylatexenc.macrospec.MacroSpec and pylatexenc.macrospec.EnvironmentSpec objects in a pylatexenc.macrospec.LatexContextDb object. See the doc of the module pylatexenc.macrospec for more information.

Changed in version 3.0: Parsing is now carried out by parser objects that are invoked via LatexWalker.parse_content(), in a significant API redesign. See What’s new in pylatexenc 3 for the differences between the two interfaces, and the list of changes that might affect existing code.

The pylatexenc 2 interface of LatexWalker — get_latex_nodes(), get_token(), get_latex_expression(), get_latex_braced_group(), get_latex_environment() and get_latex_maybe_optional_arg() — remains fully supported and should work in the vast majority of cases without code changes.

The main LatexWalker class ¶

class pylatexenc.latexwalker.LatexWalker(s, latex_context=None, **kwargs)¶

A parser which walks through an input stream, parsing it as LaTeX markup.

Arguments:

s: the string to parse as LaTeX code

default_parsing_state: The default parsing state to use to parse the content. This should be a :py:class`pylatexenc.latexnodes.ParsingState` instance (or a subclass instance). The parsing state also specifies the latex context, so if you specify default_parsing_state= you cannot also specify latex_context=. If set to None, we’ll pick a default parsing state.

When parsing parts of the string you will still be able to provide custom parsing states; the parsing state specified here serves as the default for when you don’t manually specify a parsing state to, e.g., parse_content().

This object sets the default parsing state for the make_parsing_state() method. That method returns a sub-context of the default parsing state with the specified attributes set.

This argument is keyword-only.

latex_context: Instead of providing a parsing state, you can provide the latex context only. This should be a pylatexenc.macrospec.LatexContextDb object that provides macro and environment specifications with instructions on how to parse arguments, etc. If you don’t specify this argument, or if you specify None, then the default database is used. The default database is obtained with get_default_latex_context_db().

It is strongly recommended to specify this argument as a keyword argument; we still accept a positional arg for backwards compatibility.

Added in version 2.0: This latex_context argument was introduced in version 2.0.

Additional keyword arguments are flags which influence the parsing. Accepted flags are:

tolerant_parsing=True|False If set to True, then the parser generally ignores syntax errors rather than raising an exception.

strict_braces=True|False This option refers specifically to reading a encountering a closing brace when an expression is needed. You generally won’t need to specify this flag, use tolerant_parsing instead.

The main entry point for parsing is the parse_content() method. It parses the string s you provided in the class’ constructor, using the provided parser (or the default parser, if no parser is provided). It returns a node tree, along with information about how the parsing state was updated during the parsing (e.g., new macro definitions).

This class also provides the get_***() methods inherited from pylatexenc 2 (get_latex_nodes(), get_latex_expression(), get_latex_braced_group(), get_latex_environment(), get_latex_maybe_optional_arg()). While these methods remain supported, they are subject to a SOFT DEPRECATION notice — avoid their use in new code, as they are likely to become eventually deprecated. Unless otherwise documented, they return a tuple (node, pos, len), where node is a LatexNode describing the parsed content, pos is the position at which the LaTeX element of interest was encountered, and len is the length of the string that is considered to be part of the node. That is, the position in the string that is immediately after the node is pos+len. New code should avoid the get_*** methods in favor of pylatexenc 3’s parse_content(), which is more powerful and more flexible. If you’re porting code, note the return value is slighlty different: parse_content() returns a tuple (nodes, parsing_state_delta), and the position information is carried by the nodes themselves in their pos and pos_end attributes rather than being returned alongside them. See the documentation of each of the get_***() methods for more information on migration to the new scheme.

The following obsolete flag is accepted by the constructor for backwards compatibility with pylatexenc 1.x:

macro_dict: This argument is kept for compatibility with pylatexenc 1.x. This is a dictionary of known LaTeX macro specifications. If specified, this should be a dictionary where the keys are macro names and values are pylatexenc.macrospec.MacroSpec instances, as returned for instance by the pylatexenc 1.x-emulating function MacrosDef(). If you specify this argument, you cannot provide a custom latex_context. This argument is superseded by the latex_context argument. Furthermore, if you specify this argument, no specials are parsed so that the behavior closer to pylatexenc 1.x.

Deprecated since version 2.0: The macro_dict argument has been replaced by the much more powerful latex_context argument which allows you to further provide environment specifications, etc.

keep_inline_math=True|False: Obsolete option. In pylatexenc 1.x, this option triggered a weird behavior especially since there is a similarly named option in pylatexenc.latex2text.LatexNodes2Text with a different meaning. [See Issue #14.] You should now only use the option math_mode= in pylatexenc.latex2text.LatexNodes2Text.

Deprecated since version 2.0: This option is ignored starting from pylatexenc 2. Instead, you should set the option math_mode= accordingly in pylatexenc.latex2text.LatexNodes2Text.

s¶

The string that is being parsed.

Do NOT modify this attribute.

make_latex_group_parser¶: alias of LatexDelimitedGroupParser

make_parsing_state(**kwargs)¶

Return a new parsing state object that corresponds to the current string that we are parsing (s provided to the constructor) and the current latex context (latex_context provided to the constructor).

If no arguments are provided, this returns (a copy of) the default parsing state.

If keyword arguments are provided, then they can override fields from the default parsing state. For instance, if we enter math mode, you might use:

parsing_state_mathmode = \
    my_latex_walker.make_parsing_state(in_math_mode=True)

parse_flags()¶: The parse flags currently set on this object. Returns a dictionary with keys ‘keep_inline_math’, ‘tolerant_parsing’ and ‘strict_braces’.

Deprecated since version 2.0: The ‘keep_inline_math’ key is always set to None starting in pylatexenc 2 and might be removed entirely in future versions.

check_tolerant_parsing_ignore_error(exc)¶

Check if we should attempt to recover from the given error in tolerant parsing mode.

If tolerant parsing mode is not enabled, or if exc is not an instance of LatexWalkerError (e.g., LatexWalkerParseError or LatexWalkerEndOfStream), then exc is returned unchanged. Otherwise, None is returned.

Calling code should check the return value; if None was returned, then recovery from that error should be attempted, otherwise, the returned exception object should be raised.

new_parsing_open_context(open_context_name=None, open_context_token=None)¶

Create a context manager to capture parse errors and attempt recovery from them in tolerant parsing mode.

Use as follows:

tok = ... # token representing \mymacro
with latex_walker.new_parsing_open_context(r"\mymacro invocation", tok) as pc:

    # parse stuff associated with \mymacro, perhaps custom
    # arguments
    ...

if pc.recovery_from_exception is not None:
    # attempt recovery from the exception object stored in
    # the attribute `pc.recovery_from_exception`.  The method
    # `pc.perform_recovery_nodes_and_parsing_state_delta()` can be
    # useful.
    ...

The context manager has a method perform_recovery_nodes_and_parsing_state_delta(token_reader) that will attempt to recover a nodes object from the parse error exception object and any parsing state changes information, which might have resulted from the parsing of a latex construct, and will attempt to reset the token reader’s position in order to continue parsing. The method returns a tuple (nodes, parsing_state_delta) with the hopefully recovered node list and parsing state changes information dictionary.

The open_context_name is a textual description of the context to open, and the open_context_token is the token instance that is associated with the opening of this context.

make_token_reader(pos=None)¶: Create an instance of LatexTokenReader initialized to parse the string (self.s) of this LatexWalker object. If pos is provided, then the token reader is initialized to start parsing at the position index pos in the string.

parse_content(parser=None, token_reader=None, parsing_state=None, open_context=None)¶

The main entry point to parse the stored LaTeX code into a node structure.

Arguments:

The parser must be a callable object that can be called with the keyword arguments latex_walker, token_reader and parsing_state. The return value of parser(…) should be a LatexNode or LatexNodeList instance.

If parser is None, then a plain LatexGeneralNodesParser instance is used. That parser reads general LaTeX content until the end of the stream, which is what one usually wants when parsing an entire document; so lw.parse_content() parses all the LaTeX code that was given to the constructor.

This default is a convenience offered by this class, and not part of the pylatexenc.latexnodes.LatexWalkerBase interface. A latex walker class that is derived directly from LatexWalkerBase is not required to accept parser=None.
token_reader is a LatexTokenReader instance that is tasked with converting the raw string into tokens. If None, then make_token_reader() is called to create a token reader instance.
parsing_state is a ParsingState instance that represents the current parsing state. If None, then make_parsing_state() is called to create a parsing state.
open_context, if non-None, is a tuple ( open_context_name, open_context_token ) with a textual description of the open context this construct represents (e.g., r"Argument of \mymacro") and the token that initiated this new context (e.g. the token representing the macro \mymacro). The information about open contexts is used in error messages.

The return value is a tuple (result, parser_parsing_state_delta) where result is the return value of the parser, which is expected to be a LatexNode or LatexNodeList instance, and where parsing_state_delta, if non-None, is a parsing state delta object, see pylatexenc.latexnodes.ParsingStateDelta. It represents changes to the parsing state for parsing subsequent content.

make_nodes_collector(token_reader, parsing_state, **kwargs)¶

Create and return a pylatexenc.latexnodes.LatexNodesCollector instance that reads tokens from token_reader with the given parsing_state. Any further keyword arguments are supplied directly to the nodes collector’s constructor.

Reimplemented from pylatexenc.latexnodes.LatexWalkerBase.make_nodes_collector().

make_node(node_class, **kwargs)¶

Create and return a node of type node_class which holds a representation of the latex code between positions pos and pos_end in the parsed string.

The node class should be a LatexNode subclass. Keyword arguments are supplied directly to the constructor of the node class.

Mandatory keyword-only arguments are ‘pos’, ‘pos_end’, and ‘parsing_state’.

For compatibility with pylatexenc 2.0, you can also specify len= instead of pos_end=.

All nodes produced by get_latex_nodes() and friends use this method to create node classes.

Added in version 2.0: This method was introduced in pylatexenc 2.0.

Changed in version 3.0: The mandatory len= keyword argument was replaced by the mandatory keyword argument pos_end=. For backwards compatibility, you can still specify len= instead of pos_end=.

make_nodelist(nodelist, **kwargs)¶

Create and return a LatexNodeList instance that holds the nodes given in the list nodelist.

Keyword arguments are supplied directly to the constructor of LatexNodeList. The parsing_state keyword argument is mandatory.

All node lists produced while parsing use this method, so you can reimplement it in a subclass to customize the node list objects that are created. See also make_node().

Added in version 3.0: This method was introduced in pylatexenc 3.0.

format_pos(pos)¶

Return a short human-readable string describing the position pos in the parsed string, for use in error and warning messages.

The position is reported as a line and column number, e.g. '@ (line 3, col 12)'. If pos is None, then '(location unknown)' is returned.

This method is used by pylatexenc.latexnodes.nodes.LatexNode.format_pos().

pos_to_lineno_colno(pos, as_dict=False)¶

Return the line and column number corresponding to the given pos in our string self.s.

The first time this function is called, line numbers are calculated for the entire string. These are cached for future calls which are then fast.

Return a tuple (lineno, colno) giving line number and column number. Line numbers start at 1 and column numbers start at zero, i.e., the beginning of the document (pos=0) has line and column number (1,0). If as_dict=True, then a dictionary with keys ‘lineno’, ‘colno’ is returned instead of a tuple.

get_latex_braced_group(pos, brace_type='{', parsing_state=None)¶

Parses the latex content given to the constructor (and stored in self.s), starting at position pos, to read a latex group delimited by braces.

Reads a latex expression enclosed in braces { ... }. The first token of s[pos:] must be an opening brace.

Parsing might be influenced by the parsing_state. See doc for ParsingState. If parsing_state is None, the default parsing state is used.

Returns a tuple (node, pos, len), where node is a LatexGroupNode instance, pos is the position of the first char of the expression (which has to be an opening brace), and len is the length of the group, including the closing brace (relative to the starting position).

The group must be delimited by the given brace_type. brace_type may be one of {, [, ( or <, or a 2-item tuple of two distinct single characters providing the opening and closing brace chars (e.g., ("<", ">")).

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE Since pylatexenc 3 you can parse the same content with LatexWalker.parse_content(LatexDelimitedGroupParser(), ...). That call returns a tuple (nodes, parsing_state_delta) instead of (node, pos, len), with the positions carried by the node itself, so it is not a mechanical substitution.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

get_latex_environment(pos, environmentname=None, parsing_state=None)¶

Parses the latex content given to the constructor (and stored in self.s), starting at position pos, to read a latex environment.

Reads a latex expression enclosed in a \begin{environment}...\end{environment}. The first token in the stream must be the \begin{environment}.

If environmentname is given and nonempty, then additionally a LatexWalkerParseError is raised if the environment in the input stream does not match the provided environment name.

Arguments to the begin environment command are parsed according to the corresponding specification in the given latex context latex_context provided to the constructor. The environment name is looked up as a “macro name” in the macro spec.

Parsing might be influenced by the parsing_state. See doc for ParsingState. If parsing_state is None, the default parsing state is used.

Returns a tuple (node, pos, len) where node is a LatexEnvironmentNode.

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE. Since pylatexenc 3 you can parse the same content with LatexWalker.parse_content(LatexSingleNodeParser(), ...) positioned at the beginning of the environment. That call returns a tuple (nodes, parsing_state_delta) instead of (node, pos, len), with the positions carried by the node itself, so it is not a mechanical substitution.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

get_latex_expression(pos, strict_braces=None, parsing_state=None)¶

Parses the latex content given to the constructor (and stored in self.s), starting at position pos, to parse a single LaTeX expression.

Reads a latex expression, e.g. macro argument. This may be a single char, an escape sequence, or a expression placed in braces. This is what TeX calls a “token” (and not what we call a token… anyway).

Parsing might be influenced by the parsing_state. See doc for ParsingState. If parsing_state is None, then the default parsing state is used.

Returns a tuple (node, pos, len), where pos is the position of the first char of the expression and len the length of the expression.

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE. Since pylatexenc 3 you can parse the same content with LatexWalker.parse_content(LatexExpressionParser(), ...). That call returns a tuple (nodes, parsing_state_delta) instead of (node, pos, len), with the positions carried by the node itself, so it is not a mechanical substitution.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

get_latex_maybe_optional_arg(pos, parsing_state=None)¶

Parses the latex content given to the constructor (and stored in self.s), starting at position pos, to attempt to parse an optional argument.

Parsing might be influenced by the parsing_state. See doc for ParsingState. If parsing_state is None, the default parsing state is used.

Attempts to parse an optional argument. If this is successful, we return a tuple (node, pos, len) if success where node is a LatexGroupNode. Otherwise, this method returns None.

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE. Since pylatexenc 3 you can parse the same content with the more flexible parsers mechanism, e.g., LatexWalker.parse_content(LatexOptionalSquareBracketsParser(), ...). That call returns a tuple (nodes, parsing_state_delta) instead of (node, pos, len) or None, with the positions carried by the node itself, so it is not a mechanical substitution.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

get_latex_nodes(pos=0, stop_upon_closing_brace=None, stop_upon_end_environment=None, stop_upon_closing_mathmode=None, read_max_nodes=None, parsing_state=None)¶

Parses the latex content given to the constructor (and stored in self.s) into a list of nodes.

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE. Since pylatexenc 3 you can also parse the same content with parse_content() and a parser object. The two calls do not return the same thing, so this is not a mechanical substitution; you’d write:

# pylatexenc 2 style interface, still supported:

#nodelist, npos, nlen = my_latex_walker.get_latex_nodes(
#    parsing_state=parsing_state
#)

# pylatexenc 3 style interface:

nodelist, parsing_state_delta = my_latex_walker.parse_content(
    latexnodes.parsers.LatexGeneralNodesParser(),
    parsing_state=parsing_state
)
npos = nodelist.pos
nlen = nodelist.len # or nodelist.pos_end - nodelist.pos

The LatexGeneralNodesParser() instance shown here is also parse_content()’s default parser, so it can simply be omitted.

See the documentation for LatexGeneralNodesParser for information on how to implement similar behavior as with the stop_upon_*= arguments, or by read_max_nodes=. See also, for instance, the LatexSingleNodeParser parser class.

Returns a tuple (nodelist, pos, len) where:

nodelist is a list of LatexNode‘s representing the parsed LaTeX code.
pos is the same as the pos given as argument; if there is leading whitespace it is reported in nodelist using a LatexCharsNode.
len is the length of the parsed expression. If one of the stop_upon_…= arguments are provided (cf below), then the len includes the length of the token/expression that stopped the parsing.

If stop_upon_closing_brace is given and set to a character, then parsing stops once the given closing brace is encountered (but not inside a subgroup). The brace is given as a character, ‘]’, ‘}’, ‘)’, or ‘>’. Alternatively you may specify a 2-item tuple of two single distinct characters representing the opening and closing brace chars. The returned len includes the closing brace, but the closing brace is not included in any of the nodes in the nodelist.

If stop_upon_end_environment is provided, then parsing stops once the given environment was closed. If there is an environment mismatch, then a LatexWalkerParseError is raised except in tolerant parsing mode (see parse_flags()). Again, the closing environment is included in the length count but not the nodes.

If stop_upon_closing_mathmode is specified, then the parsing stops once the corresponding math mode (assumed already open) is closed. This argument may take the values None (no particular request to stop at any math mode token), or one of $, $$, \) or \] indicating a closing math mode delimiter that we are expecting and at which point parsing should stop.

If the token ‘$’ (respectively ‘$$’) is encountered, it is interpreted as the beginning of a new math mode chunk unless the argument stop_upon_closing_mathmode=… has been set to ‘$’ (respectively ‘$$’).

If read_max_nodes is non-None, then it should be set to an integer specifying the maximum number of top-level nodes to read before returning. (Top-level nodes means that macro arguments, environment or group contents, etc., do not count towards read_max_nodes.) If None, the entire input string will be parsed.

Note

There are a few important differences between get_latex_nodes(read_max_nodes=1) and get_latex_expression(): The former reads a logical node of the LaTeX document, which can be a sequence of characters, a macro invocation with arguments, or an entire environment, but the latter reads a single LaTeX “token” in a similar way to how LaTeX parses macro arguments.

For instance, if a macro is encountered, then get_latex_nodes(read_max_nodes=1) will read and parse its arguments, and include it in the corresponding LatexMacroNode, whereas get_latex_expression() will return a minimal LatexMacroNode with no arguments regardless of the macro’s argument specification. The same holds for latex specials. For environments, get_latex_nodes(read_max_nodes=1) will return the entire parsed environment into a LatexEnvironmentNode, whereas get_latex_expression() will return a LatexMacroNode named ‘begin’ with no arguments.

Parsing might be influenced by the parsing_state. See doc for ParsingState. If parsing_state is None, the default parsing state is used.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

get_token(pos, include_brace_chars=None, environments=True, keep_inline_math=None, parsing_state=None, **kwargs)¶

Parses the latex content given to the constructor (and stored in self.s), starting at position pos, to parse a single “token”, as defined by LatexToken.

This method is the pylatexenc 2 style interface and it remains supported; it is subject to SOFT DEPRECATION - AVOID USE IN NEW CODE. Since pylatexenc 3 you can also read tokens with a token reader object, see make_token_reader() and LatexTokenReader. A token reader keeps track of its own position in the string as it reads and it exposes several reading methods (peek_token(), next_token(), …), so moving to it is not simply a matter of replacing one call by another.

Parse the token in the stream pointed to at position pos.

Returns a LatexToken. Raises LatexWalkerEndOfStream if end of stream reached.

For tokens of type ‘char’, usually a single character is returned. The only exception is at paragraph boundaries, where a single ‘char’-type token has argument ‘\n\n’.

Normally whitespace cannot be part of a latex-specials. As an exception, you can declare a SpecialsSpec in your latex_context with the chars "\n\n", and it will be reported at paragraph breaks caused by a double newline.

The argument include_brace_chars= allows to specify additional pairs of single characters which should be considered as braces (i.e., of ‘brace_open’ and ‘brace_close’ token types). It should be a list of 2-item tuples, for instance [('[', ']'), ('<', '>')]. The pair (‘{’, ‘}’) is always considered as braces. The delimiters may not have more than one character each.

If environments=False, then \begin and \end tokens count as regular ‘macro’ tokens (see LatexToken); otherwise (the default) they are considered as the token types ‘begin_environment’ and ‘end_environment’.

The parsing of the tokens might be influcenced by the parsing_state (a ParsingState instance). Currently, the only influence this has is that some latex specials are parsed differently if in math mode. See doc for ParsingState. If parsing_state is None, the default parsing state returned by make_parsing_state() is used.

Deprecated since version 2.0: The flag keep_inline_math is only accepted for compatibiltiy with earlier versions of pylatexenc, but it has no effect starting in pylatexenc 2. See the LatexWalker class doc.

Deprecated since version 2.0: If brackets_are_chars=False, then square bracket characters count as ‘brace_open’ and ‘brace_close’ token types (see LatexToken); otherwise (the default) they are considered just like other normal characters.

Added in version 2.0: The parsing_state argument was introduced in version 2.0.

pylatexenc.latexwalker.get_default_latex_context_db()¶

Return a pylatexenc.macrospec.LatexContextDb instance initialized with a collection of known macros and environments.

The definitions are grouped into the following categories, which you can select or discard individually with pylatexenc.macrospec.LatexContextDb.filter_context():

'latex-paragraph' — the paragraph break (a blank line) as a “specials” definition.

'latex-base' — the bulk of the standard LaTeX macros, environments and specials, i.e., what you can expect to be available in a plain LaTeX document.

'latex-base-subsuperscripts' — the ^ and _ characters as “specials” definitions. They belong to the base LaTeX definitions but have a category of their own, so that you can discard them and get back the pylatexenc 2 behavior in which ^ and _ were ordinary characters.

'nonascii-specials' — character sequences that LaTeX gives a special meaning: the non-breaking space ~, the quote and dash “fake ligatures” (a pair of backticks, '', -- and ---), and the inverted punctuation marks (an exclamation mark or a question mark followed by a backtick).

'verbatim' — the \verb macro and the {verbatim} environment.

'lstlisting' — the {lstlisting} environment of the listings package, whose body is also read verbatim.

'theorems' — theorem-like environments ({theorem}, {lemma}, {proof}, etc., along with common short forms).

'enumitem' — the {enumerate}, {itemize} and {description} environments with the optional argument that the enumitem package gives them.

'natbib' — the citation macros of the natbib package (\citet, \citep, etc.).

'latex-ethuebung' — macros of the ethuebung LaTeX package.

If you want to add your own definitions, you should use the pylatexenc.macrospec.LatexContextDb.add_context_category() method. If you would like to override some definitions, use that method with the argument prepend=True. See docs for pylatexenc.macrospec.LatexContextDb.add_context_category().

If there are too many macro/environment definitions, or if there are some irrelevant ones, you can always filter the returned database using pylatexenc.macrospec.LatexContextDb.filter_context().

Added in version 2.0: The pylatexenc.macrospec.LatexContextDb class as well as this method, were all introduced in pylatexenc 2.0.

Exception Classes ¶

class pylatexenc.latexwalker.LatexWalkerError¶: Moved to pylatexenc.latexnodes.LatexWalkerError.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes as pylatexenc.latexnodes.LatexWalkerError. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexWalkerParseError¶: Moved to pylatexenc.latexnodes.LatexWalkerParseError.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes as pylatexenc.latexnodes.LatexWalkerParseError. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexWalkerEndOfStream¶: Moved to pylatexenc.latexnodes.LatexWalkerEndOfStream.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes as pylatexenc.latexnodes.LatexWalkerEndOfStream. It is aliased in pylatexenc.latexwalker for backwards compatibility.

Data Node Classes ¶

class pylatexenc.latexwalker.LatexNode¶: Moved to pylatexenc.latexnodes.nodes.LatexNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexCharsNode¶: Moved to pylatexenc.latexnodes.nodes.LatexCharsNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexCharsNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexGroupNode¶: Moved to pylatexenc.latexnodes.nodes.LatexGroupNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexGroupNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexCommentNode¶: Moved to pylatexenc.latexnodes.nodes.LatexCommentNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexCommentNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexMacroNode¶: Moved to pylatexenc.latexnodes.nodes.LatexMacroNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexMacroNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexEnvironmentNode¶: Moved to pylatexenc.latexnodes.nodes.LatexEnvironmentNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexEnvironmentNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexSpecialsNode¶: Moved to pylatexenc.latexnodes.nodes.LatexSpecialsNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexSpecialsNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexMathNode¶: Moved to pylatexenc.latexnodes.nodes.LatexMathNode.

Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes.nodes as pylatexenc.latexnodes.nodes.LatexMathNode. It is aliased in pylatexenc.latexwalker for backwards compatibility.

Parsing helpers ¶

class pylatexenc.latexwalker.ParsingState¶: Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes. It is aliased in pylatexenc.latexwalker for backwards compatibility.

class pylatexenc.latexwalker.LatexToken¶: Deprecated since version 3.0: Since Pylatexenc 3.0, this class now resides in the new module pylatexenc.latexnodes. It is aliased in pylatexenc.latexwalker for backwards compatibility.

Legacy Macro Definitions (for pylatexenc 1.x)¶

pylatexenc.latexwalker.MacrosDef(macname, optarg, numargs)¶: Deprecated since version 2.0: Use pylatexenc.macrospec.std_macro() instead which does the same thing, or invoke the MacroSpec class directly (or a subclass).

In pylatexenc 1.x, MacrosDef was a class. Since pylatexenc 2.0, MacrosDef is a function which returns a MacroSpec instance. In this way the earlier idiom MacrosDef(...) still works in pylatexenc 2. The field names of the constructed object might have changed since pylatexenc 1.x, so you might have to adapt existing code if you were accessing individual fields of MacrosDef objects.

In the object returned by MacrosDef(), we provide the legacy attributes macname, optarg, and numargs, so that existing code accessing those properties can continue to work.

pylatexenc.latexwalker.default_macro_dict¶

A lazy dictionary that loads its data when it is first queried.

This is used to store the legacy pylatexenc.latexwalker.default_macro_dict as well as pylatexenc.latex2text.default_macro_dict etc. Such that these “dictionaries” are still exposed at the module-level, but the data is loaded only if they are actually queried.

pylatexenc

Navigation

Related Topics

latexwalker — Calling Parsers for LaTeX Code¶

The main LatexWalker class ¶

Exception Classes ¶

Data Node Classes ¶

Parsing helpers ¶

Legacy Macro Definitions (for pylatexenc 1.x)¶

latexwalker — Calling Parsers for LaTeX Code¶

The main LatexWalker class¶

Exception Classes¶

Data Node Classes¶

Parsing helpers¶

Legacy Macro Definitions (for pylatexenc 1.x)¶

The main LatexWalker class ¶

Exception Classes ¶

Data Node Classes ¶

Parsing helpers ¶