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.

LATEXENC module-attribute

LATEXENC = UnicodeToLatexEncoder(
    conversion_rules=[
        UnicodeToLatexConversionRule(
            RULE_DICT,
            {
                ord("‘"): "`",
                ord("’"): "'",
                ord("“"): "``",
                ord("”"): "''",
                ord("–"): "--",
                ord("—"): "---",
                ord("í"): "\\'i",
                ord("ì"): "\\`i",
                ord("î"): "\\^i",
                ord("ï"): '\\"i',
            },
        ),
        "defaults",
    ],
    replacement_latex_protection="braces-all",
    unknown_char_policy="keep",
    unknown_char_warning=False,
)

A UnicodeToLatexEncoder instance intended for BibTeX generation.

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_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",
    "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.