Full API

bibtexparser — High-Level Entrypoints

bibtexparser.parse_file(path: str, parse_stack: Iterable[Middleware] | None = None, append_middleware: Iterable[Middleware] | None = None, encoding: str = 'UTF-8') Library[source]

Parse a BibTeX file

Args:

path (str): Path to BibTeX file parse_stack (Optional[Iterable[Middleware]], optional): List of middleware to apply to the database after splitting. If None (default), a default stack will be used providing simple standard functionality will be used. append_middleware (Optional[Iterable[Middleware]], optional): List of middleware to append to the default stack (ignored if a not-None parse_stack is passed). encoding: Encoding of the .bib file. Default encoding is “UTF-8”.

Returns:

Library: Parsed BibTeX library

bibtexparser.parse_string(bibtex_str: str, parse_stack: Iterable[Middleware] | None = None, append_middleware: Iterable[Middleware] | None = None, library: Library | None = None)[source]

Parse a BibTeX string.

Args:

bibtex_str (str): BibTeX string to parse parse_stack (Optional[Iterable[Middleware]], optional): List of middleware to apply to the database after splitting. If None (default), a default stack will be used providing simple standard functionality will be used. append_middleware (Optional[Iterable[Middleware]], optional): List of middleware to append to the default stack (ignored if a not-None parse_stack is passed). library (Optional[Library], optional): Library to add entries to. If None (default), a new library will be created.

Returns:

Library: Parsed BibTeX database

bibtexparser.write_file(file: str | TextIO, library: Library, parse_stack: Iterable[Middleware] | None = None, append_middleware: Iterable[Middleware] | None = None, bibtex_format: BibtexFormat | None = None) None[source]

Write a BibTeX database to a file.

Parameters:
  • file – File to write to. Can be a file name or a file object.

  • library – BibTeX database to serialize.

  • parse_stack – List of middleware to apply to the database before writing. If None, a default stack will be used.

  • append_middleware – List of middleware to append to the default stack. Only applicable if parse_stack is None.

  • bibtex_format – Customized BibTeX format to use (optional).

bibtexparser.write_string(library: Library, unparse_stack: Iterable[Middleware] | None = None, prepend_middleware: Iterable[Middleware] | None = None, bibtex_format: BibtexFormat | None = None) str[source]

Serialize a BibTeX database to a string.

Parameters:
  • library – BibTeX database to serialize.

  • unparse_stack – List of middleware to apply to the database before writing. If None, a default stack will be used.

  • prepend_middleware – List of middleware to prepend to the default stack. Only applicable if parse_stack is None.

  • bibtex_format – Customized BibTeX format to use (optional).

bibtexparser.Library — The class containing the parsed library

class bibtexparser.Library(blocks: List[Block] | None = None)[source]

A collection of parsed bibtex blocks.

property blocks: List[Block]

All blocks in the library, preserving order of insertion.

property comments: List[ExplicitComment | ImplicitComment]

All comment blocks in the library, preserving order of insertion.

property entries: List[Entry]

All entry (@article, …) blocks in the library, preserving order of insertion.

property entries_dict: Dict[str, Entry]

Dict representation of all entry blocks in the library.

property preambles: List[Preamble]

All @preamble blocks in the library, preserving order of insertion.

property strings: List[String]

All @string blocks in the library, preserving order of insertion.

bibtexparser.model — The classes used in the library

class bibtexparser.model.Block(start_line: int | None = None, raw: str | None = None, parser_metadata: Dict[str, Any] | None = None)[source]

A abstract superclass of all top-level building blocks of a bibtex file.

E.g. a @string block, a @preamble block, an @entry block, a comment, etc.

get_parser_metadata(key: str) Any | None[source]

EXPERIMENTAL: get auxiliary information stored in parser_metadata.

See attribute parser_metadata for more information.

property parser_metadata: Dict[str, Any]

EXPERIMENTAL: field for middleware to store auxiliary information.

As an end-user, as long as you are not writing middleware, you probably do not need to use this field.

** Warning (experimental) ** The content of this field is undefined and may change at any time.

This field is intended for middleware to store auxiliary information. It is a key-value store, where the key is a string and the value is any python object. This allows for example to pass information between different middleware.

property raw: str | None

The raw, unmodified string (bibtex) representation of this block.

Note: Middleware does not update this field, hence, after applying middleware to a library, this field may be outdated.

set_parser_metadata(key: str, value: Any)[source]

EXPERIMENTAL: set auxiliary information stored in parser_metadata.

See attribute parser_metadata for more information.

property start_line: int | None

The line number of the first line of this block in the parsed string.

class bibtexparser.model.Entry(entry_type: str, key: str, fields: List[Field], start_line: int | None = None, raw: str | None = None)[source]

Bibtex Blocks of the @entry type, e.g. @article{Cesar2013, …}.

property entry_type

The type of the entry, e.g. article in @article{Cesar2013, …}.

property fields: List[Field]

The key-value attributes of an entry, as Field instances.

property fields_dict: Dict[str, Field]

A dict of fields, with field keys as keys.

Note that with duplicate field keys, the behavior is undefined.

items()[source]

Dict-mimicking, for partial v1.x backwards compatibility.

For newly written code, it’s recommended to use entry.entry_type, entry.key and entry.fields instead.

property key

The key of the entry, e.g. Cesar2013 in @article{Cesar2013, …}.

set_field(field: Field)[source]

Adds a new field, or replaces existing with same key.

class bibtexparser.model.ExplicitComment(comment: str, start_line: int | None = None, raw: str | None = None)[source]

Bibtex Blocks of the @comment type, e.g. @comment{This is a comment}.

property comment: str

The value of the comment, e.g. blabla in @comment{blabla}.

class bibtexparser.model.Field(key: str, value: Any, start_line: int | None = None)[source]

A field of a Bibtex entry, e.g. author = {John Doe}.

property key: str

The key of the field, e.g. author in author = {John Doe}.

property start_line: int

The line number of the first line of this field in the originally parsed string.

property value: Any

The value of the field, e.g. {John Doe} in author = {John Doe}.

class bibtexparser.model.ImplicitComment(comment: str, start_line: int | None = None, raw: str | None = None)[source]

Bibtex outside of an @{…} block, which is treated as a comment.

property comment: str

The (possibly multi-line) comment.

class bibtexparser.model.Preamble(value: str, start_line: int | None = None, raw: str | None = None)[source]

Bibtex Blocks of the @preamble type, e.g. @preamble{This is a preamble}.

property value: str

The value of the preamble, e.g. blabla in @preamble{blabla}.

class bibtexparser.model.String(key: str, value: str, start_line: int | None = None, raw: str | None = None)[source]

Bibtex Blocks of the @string type, e.g. @string{me = “My Name”}.

property key: str

The key of the string, e.g. me in @string{me = “My Name”}.

property value: str

The value of the string, e.g. “My Name” in @string{me = “My Name”}.

bibtexparser.middlewares — Customizers to transform parsed library

bibtexparser.BibtexFormat — Formatting options for writer

class bibtexparser.BibtexFormat[source]

Definition of formatting (alignment, …) when writing a BibTeX file.

Hint: For more manual, GUI-based formatting, see the bibtex-tidy tool:

https://flamingtempura.github.io/bibtex-tidy/

property block_separator: str

Character(s) for separating BibTeX entries.

Default: Two lines breaks, i.e., two blank lines.

property indent: str

Character(s) for indenting BibTeX field-value pairs. Default: single space.

property parsing_failed_comment: str

Comment to use for blocks that could not be parsed.

property trailing_comma: bool

Use the trailing comma syntax for BibTeX entries. Default: False

BibTeX syntax allows an optional comma at the end of the last field in an entry.

property value_column: int | str

Controls the alignment of field- and string-values. Default: no alignment.

This impacts String and Entry blocks.

An integer value x specifies that spaces should be added before the “ = “, such that, if possible, the value is written at column len(self.indent) + x. Note that for long keys, the value may be written at a later column.

Thus, a value of 0 means that the value is written directly after the “ = “.

The special value “auto” specifies that the bibtex field value should be aligned based on the longest key in the library.