LaTeX Codec

Warnings

• breaking Versions prior to 3.0.1 are incompatible with Python 3.13+ due to the removal of `pkg_resources.open_text`. Users on Python 3.13 and newer must upgrade to `latexcodec` 3.0.1 or later.
  Fix: Upgrade to `latexcodec>=3.0.1`.
• deprecated The maintainer strongly encourages users to consider `pylatexenc` as a superior alternative to `latexcodec` for LaTeX code processing.
  Fix: Evaluate migrating to `pylatexenc` for new projects or existing ones that require more robust LaTeX handling. (https://github.com/phfaist/pylatexenc)
• gotcha This library is primarily designed for processing short fragments of LaTeX text (e.g., paragraphs, BibTeX entries) and is not intended to function as a full LaTeX compiler or for comprehensive document processing.
  Fix: Ensure use cases align with the library's scope. For full document parsing or compilation, consider dedicated LaTeX parsers or compilers.
• gotcha When decoding LaTeX, commands that do not directly represent characters (e.g., macros, formatting commands like `\textbf`) or are unrecognized by the codec are passed through unchanged. This can result in a 'hybrid' Unicode string containing unexpanded LaTeX commands.
  Fix: Be aware of this behavior and implement post-processing if fully flattened Unicode is required. Unrecognized commands may require custom translation tables.
• gotcha Encoding Unicode characters to LaTeX can fail if the characters cannot be represented by the default (ASCII) LaTeX encoding. For more robust encoding, use the `ulatex+utf8` codec or specify the `'keep'` error handler with `ulatex` to retain unencodable characters.
  Fix: Use `codecs.encode(unicode_str, 'ulatex+utf8')` or `codecs.encode(unicode_str, 'ulatex', 'keep')`.
• gotcha The decoding process canonicalizes certain LaTeX elements: comments are dropped, paragraphs are converted to double newlines, and spacing after LaTeX commands is standardized. This can lead to subtle differences in the decoded text's structure compared to the original LaTeX source.
  Fix: Account for these canonicalizations when comparing decoded output to original source or when expecting specific formatting.

Install

• pip install latexcodec Install stable version

Imports

• latexcodec

  import latexcodec
  import codecs
  # Use codecs.decode() and codecs.encode()

  Importing `latexcodec` automatically registers the 'latex' and 'ulatex' codecs with Python's standard `codecs` module. Direct functions are not typically exposed for end-user encoding/decoding.

Quickstart

This quickstart demonstrates how to decode LaTeX strings to Unicode and encode Unicode strings to LaTeX using the `latex` and `ulatex` codecs registered by importing `latexcodec`. It also shows how to specify additional encodings and handle unrepresentable characters during encoding.

import codecs
import latexcodec # This registers the 'latex' and 'ulatex' codecs

# Decode LaTeX to Unicode
latex_text = r"I like b\"all{\oe}ns and M\"uller."
unicode_output = codecs.decode(latex_text, "ulatex")
print(f"Decoded LaTeX: {unicode_output}")

# Encode Unicode to LaTeX
unicode_input = "élève"
latex_output = codecs.encode(unicode_input, "ulatex")
print(f"Encoded Unicode: {latex_output}")

# Example with specific encoding (e.g., Latin-1)
latin1_latex_bytes = b"\xfe" # Represents 'þ' in Latin-1
decoded_latin1 = latin1_latex_bytes.decode("latex+latin1")
print(f"Decoded Latin1 LaTeX: {decoded_latin1}")

# Example with error handling during encoding for unrepresentable characters
unicode_with_unrepresentable = "A keyboard: ⌨"
# Using 'keep' error handler with 'ulatex' codec
encoded_kept = codecs.encode(unicode_with_unrepresentable, "ulatex", "keep")
print(f"Encoded with 'keep' error (ulatex): {encoded_kept}")

# Using 'ulatex+utf8' for robust encoding of all Unicode characters
encoded_utf8 = codecs.encode(unicode_with_unrepresentable, "ulatex+utf8")
print(f"Encoded with ulatex+utf8: {encoded_utf8}")