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 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.
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_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, …}.
- 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:
- 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.