DOCSEARCHbyAlgolia
Submit Docs

bibtexparser

repository·main·Indexed 20 days ago

https://github.com/sciunto-org/python-bibtexparser

A high-performance, extensible BibTeX parser for Python 3. Version 2 (v2) features a middleware-based architecture for customizable parsing and writing, improved fault tolerance via a Splitter that handles malformed blocks, and a Library class for managing BibTeX entries, strings, preambles, and comments. It provides primary entry points such as parse_string, parse_file, write_string, and write_file to convert between BibTeX data and Library objects.

Tokens
13K
Snippets
48
Records
67
Agent score
67%

What's inside bibtexparser

  2. How bibtexparser v2 architecture works

    main

    The v2 architecture is composed of four main components:

    1. Library: A representation of the parsed BibTeX content, including entries, strings, preambles, comments, and metadata (like order).
    2. Splitter: Breaks the raw BibTeX string into basic blocks (e.g., Entry, String, Preamble). It is fault-tolerant; if a block is malformed, it creates a ParsingFailedBlock rather than crashing.
    3. Middleware: Layers that transform the library or its blocks (e.g., decoding LaTeX characters, resolving cross-references). By default, middleware returns a modified copy rather than mutating the input.
    4. Writer: Converts the library back into a .bib file or string, with support for optional formatting parameters.

  3. How middleware layers work in BibtexParser v2

    main

    BibtexParser v2 uses a middleware-based architecture for advanced transformations. The core parser only handles splitting input into blocks (entries, strings, etc.) and fields. For operations like sorting, encoding, or name splitting, you use middleware layers.

    Middleware layers are helper classes that take a library object and return a new, transformed version of it. You can add these layers to your parse or write stack to customize how Bibtex data is processed.

    There are two main types of middleware:

    1. BlockMiddleware: Operates on individual entries/blocks (e.g., transforming a specific field value).
    2. LibraryMiddleware: Operates on the entire library (e.g., sorting all entries).

    To use middleware, you pass them to bibtexparser.parse(), bibtexparser.parse_file(), bibtexparser.write(), or bibtexparser.write_file() using specific arguments to control whether they are added to or replace the default stack.

    import bibtexparser.middlewares as m

# Adding layers to the parse stack
layers = [
    m.MonthIntMiddleware(),
    m.SeparateCoAuthors(),
    m.SplitNameParts()
]
library = bibtexparser.parse_file('bibtex.bib', append_middleware=layers)

  4. Understand BibTeX blocks and the library object

    main

    A BibTeX file is a collection of blocks. The library object returned by the parser provides access to these blocks categorized by type:

    • entries: Citable items like @article{...} or @book{...}.
    • comments: Explicit comments written as @comment{...}.
    • strings: BibTeX strings defined as @string{...}.
    • preambles: Preamble blocks defined as @preamble{...}.
    • implicit comments: Any text not within an @...@ block.

    You can access these via library.entries, library.comments, library.strings, and library.preambles, or iterate over all blocks using library.blocks.

  5. Support for Biblatex and Biber files

    main

    Because BibTeX, Biblatex, and Biber share a similar general syntax, python-bibtexparser can be used to parse Biblatex and Biber files.

    Note that the library does not explicitly validate against every specific feature of Biber or Biblatex. If you encounter unsupported features or parsing errors with these formats, please report them via an issue or a pull request.

  6. Configure formatting options for writing BibTeX

    main

    Basic formatting options like indentation and line breaks do not affect the bibtexparser.bparser.Library representation and cannot be set via middleware. Instead, these options are passed to the bibtexparser.write (or bibtexparser.write_string) function using a bibtexparser.BibtexFormat object via the bibtex_format argument.

    Commonly configurable attributes on BibtexFormat include:

    • indent: The string used for indentation (e.g., ' ').
    • block_separator: The string used to separate BibTeX blocks (e.g., '\n\n').

    Note that sorting of blocks and fields is handled by middleware layers, not by the formatter.

    bibtex_format = bibtexparser.BibtexFormat()
bibtex_format.indent = '    '
bibtex_format.block_separator = '\n\n'
bib_str = bibtexparser.write_string(library, bibtex_format=bibtex_format)

  10. Parse and write BibTeX strings with bibtexparser v2

    main

    In v2, you can quickly convert BibTeX strings into a library object and back again using parse_string and write_string.

    # Parsing a bibtex string with default values
bib_database = bibtexparser.parse_string(bibtex_string)

# Converting it back to a bibtex string, again with default values
new_bibtex_string = bibtexparser.write_string(bib_database)

  11. Change the entrypoint for loading BibTeX files

    main

    In v1, the primary entrypoint was bibtexparser.load(). In v2, this has been replaced by bibtexparser.parse_file() to prevent accidental migration.

    To migrate a file loading task, replace bibtexparser.load(file_handle) with bibtexparser.parse_file(file_handle).

    # v1
import bibtexparser
with open('bibtex.bib') as bibtex_file:
    bib_database = bibtexparser.load(bibtex_file)

# v2
import bibtexparser
library = bibtexparser.parse_file(bibtex_file)

  12. Install bibtexparser v2

    main

    To use the latest version (v2), which is currently in beta, install it using pip with the --pre flag. You can also install the latest development version directly from the main branch.

    Note: v2 is faster and more customizable than v1, but it is still in beta and may not contain all features available in v1.

    # Install v2 (beta)
pip install bibtexparser --pre

# Or install latest development version from main branch
pip install --no-cache-dir --force-reinstall git+https://github.com/sciunto-org/python-bibtexparser@main