utils.latex¶

Warning

These are internal functions that you probably don't want to interact with directly.

Functions implementing conversions to and from LaTeX/BibTeX formats.

BIBTEX_FIELD_NEEDS_ENCODING `module-attribute` ¶

BIBTEX_FIELD_NEEDS_ENCODING = {
    "journal",
    "address",
    "publisher",
    "note",
}

Any BibTeX field whose value should be LaTeX-encoded first.

BIBTEX_MONTHS `module-attribute` ¶

BIBTEX_MONTHS = {
    "january": "jan",
    "february": "feb",
    "march": "mar",
    "april": "apr",
    "may": "may",
    "june": "jun",
    "july": "jul",
    "august": "aug",
    "september": "sep",
    "october": "oct",
    "november": "nov",
    "december": "dec",
}

A mapping of month names to BibTeX macros.

FAST_LATEX_TABLE `module-attribute` ¶

FAST_LATEX_TABLE = _build_fast_latex_table()

str.translate() table equivalent to LATEXENC.unicode_to_latex(); see the note on LATEXENC above.

LATEXENC `module-attribute` ¶

LATEXENC = UnicodeToLatexEncoder(
    conversion_rules=[
        UnicodeToLatexConversionRule(
            RULE_DICT, LATEX_CUSTOM_OVERRIDES
        ),
        "defaults",
    ],
    replacement_latex_protection="braces-all",
    unknown_char_policy="keep",
    unknown_char_warning=False,
)

A UnicodeToLatexEncoder instance intended for BibTeX generation.

Note

latex_encode() below does not actually call this encoder. Its conversion rules are dict-only (no regexes), with unknown_char_policy="keep" and replacement_latex_protection="braces-all"; given that, its output for any string is fully determined by a single codepoint->replacement mapping (unmapped characters pass through unchanged). _build_fast_latex_table() derives that mapping so latex_encode() can apply it via str.translate() -- a single C-level pass -- instead of pylatexenc's per-character, per-rule dispatch loop, which profiling showed to dominate BibTeX generation time. If LATEXENC's configuration above ever changes, update _build_fast_latex_table() accordingly; tests/utils/latex_test.py cross-checks the two against every string in data/xml/*.xml and will fail if they diverge.

LATEX_CITE_MACROS `module-attribute` ¶

LATEX_CITE_MACROS = {
    "cite",
    "citep",
    "citet",
    "newcite",
    "citeauthor",
    "citeyear",
}

A set of LaTeX macros that will be treated as citation macros.

LATEX_CUSTOM_OVERRIDES `module-attribute` ¶

LATEX_CUSTOM_OVERRIDES = {
    ord("‘"): "`",
    ord("’"): "'",
    ord("“"): "``",
    ord("”"): "''",
    ord("–"): "--",
    ord("—"): "---",
    ord("í"): "\\'i",
    ord("ì"): "\\`i",
    ord("î"): "\\^i",
    ord("ï"): '\\"i',
}

Unicode-to-LaTeX overrides for LATEXENC, taking priority over its defaults.

LATEX_LINE_BREAK_RE `module-attribute` ¶

LATEX_LINE_BREAK_RE = re.compile(
    "[^\\S\\r\\n]*(?:(?:\\r\\n?|\\n)[^\\S\\r\\n]*)+"
)

Consume horizontal whitespace around CRLF, CR, or LF source line endings. Two or more consecutive line endings denote a blank line between paragraphs.

LATEX_MACRO_TO_XMLTAG `module-attribute` ¶

LATEX_MACRO_TO_XMLTAG = {
    "emph": "i",
    "em": "i",
    "textit": "i",
    "it": "i",
    "textsl": "i",
    "sl": "i",
    "textbf": "b",
    "bf": "b",
    "underline": "u",
    "uline": "u",
    "textsc": "sc",
    "texttt": "tt",
    "url": "url",
}

A mapping of LaTeX macros to Anthology XML tags.

SerializableAsBibTeX `module-attribute` ¶

SerializableAsBibTeX = (
    None | str | MarkupText | tuple[NameSpecification, ...]
)

Any type that can be supplied to make_bibtex_entry.

bibtex_convert_month ¶

bibtex_convert_month(spec)

Converts a month string to BibTeX macros.

Parameters:

Name	Type	Description	Default
`spec`	`str`	A month specification, as stored in the metadata.	required

Returns:

Type	Description
`str`	A BibTeX macro corresponding to the month specification, if possible. If the string contains digits or is otherwise not parseable, it is returned unchanged with quotes around it.

has_unbalanced_braces ¶

has_unbalanced_braces(string)

Checks if a string has unbalanced curly braces.

latex_convert_quotes ¶

latex_convert_quotes(text)

Parameters:

Name	Type	Description	Default
`text`	`str`	An arbitrary string.	required

Returns:

Type	Description
`str`	The input string with LaTeX quotes converted into proper opening and closing quotes, removing braces around them, if necessary.

Note

This is called during the conversion from our XML markup to LaTeX. Straight quotation marks (") will have been converted to double apostrophes, usually in braces ({''}), by pylatexenc; this function applies regexes to turn them into appropriate opening/closing quotes with the braces removed.

Examples:

>>> latex_convert_quotes("This {''}great{''} example")
"This ``great'' example"

latex_encode `cached` ¶

latex_encode(text)

Parameters:

Name	Type	Description	Default
`text`	`Optional[str]`	A string that does not contain any LaTeX commands.	required

Returns:

Type	Description
`str`	The input string encoded for use in LaTeX/BibTeX.

make_bibtex_entry ¶

make_bibtex_entry(bibtype, bibkey, fields)

Turn a list of field/value pairs into a BibTeX entry.

Values will be LaTeX-formatted if necessary, and can also be empty, in which case they are automatically omitted.

Parameters:

Name	Type	Description	Default
`bibtype`	`str`	The BibTeX type for the entry.	required
`bibkey`	`str`	The BibTeX key for the entry.	required
`fields`	`list[tuple[str, SerializableAsBibTeX]]`	A list of tuples of the form (key, value) specifying the fields to include in the entry.	required

Returns:

Type	Description
`str`	A fully formatted BibTeX entry.

namespecs_to_bibtex ¶

namespecs_to_bibtex(namespecs)

Convert a list of NameSpecifications to a BibTeX-formatted entry.

Parameters:

Name	Type	Description	Default
`namespecs`	`Iterable[NameSpecification]`	A list of names to be included in the BibTeX entry.	required

Returns:

Type	Description
`str`	A BibTeX-formatted string representing the given names.

parse_latex_to_xml ¶

parse_latex_to_xml(
    latex_input, use_fixed_case=True, use_heuristics=False
)

Convert a string with LaTeX markup into the Anthology XML format.

Parameters:

Name	Type	Description	Default
`latex_input`	`str`	A string potentially including LaTeX markup.	required
`use_fixed_case`	`bool`	Flag indicating whether protection should be applied.	`True`
`use_heuristics`	`bool`	If True, will apply some heuristics to determine if certain symbols should be interpreted as plain text rather than LaTeX; e.g., it will prevent percentage signs from being interpreted as LaTeX comments. Set this to True when dealing with inputs that could either be plain text or LaTeX.	`False`

Returns:

Type	Description
`_Element`	An XML element representing the given LaTeX input in the Anthology XML format for markup strings.

Note

This is a potentially lossy conversion, as the Anthology XML format only represents a small subset of LaTeX commands. Unhandled commands will be dropped, but emit a warning in the logger.

utils.latex¶

BIBTEX_FIELD_NEEDS_ENCODING module-attribute ¶

BIBTEX_MONTHS module-attribute ¶

FAST_LATEX_TABLE module-attribute ¶

LATEXENC module-attribute ¶

LATEX_CITE_MACROS module-attribute ¶

LATEX_CUSTOM_OVERRIDES module-attribute ¶

LATEX_LINE_BREAK_RE module-attribute ¶

LATEX_MACRO_TO_XMLTAG module-attribute ¶

SerializableAsBibTeX module-attribute ¶

bibtex_convert_month ¶

has_unbalanced_braces ¶

latex_convert_quotes ¶

latex_encode cached ¶

make_bibtex_entry ¶

namespecs_to_bibtex ¶

parse_latex_to_xml ¶

BIBTEX_FIELD_NEEDS_ENCODING `module-attribute` ¶

BIBTEX_MONTHS `module-attribute` ¶

FAST_LATEX_TABLE `module-attribute` ¶

LATEXENC `module-attribute` ¶

LATEX_CITE_MACROS `module-attribute` ¶

LATEX_CUSTOM_OVERRIDES `module-attribute` ¶

LATEX_LINE_BREAK_RE `module-attribute` ¶

LATEX_MACRO_TO_XMLTAG `module-attribute` ¶

SerializableAsBibTeX `module-attribute` ¶

latex_encode `cached` ¶