Full API

bibtexparser — High-Level Entrypoints

bibtexparser.Library — The class containing the parsed library

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)

An 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

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)

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.DuplicateBlockKeyBlock(key: str, previous_block: Block, duplicate_block: Block, start_line: int | None = None, raw: str | None = None)

An error-indicating block created for blocks with keys present in the library already.

To get the block that caused this error, call block.ignore_error_block.

property key: str

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

property previous_block: Block

A reference to a previous block with the same key.

class bibtexparser.model.DuplicateFieldKeyBlock(duplicate_keys: set[str], entry: Entry)

An error-indicating block indicating a duplicate field key in an entry.

The entry containing the duplicate field keys is available as block.ignore_error_block, the duplicate keys as block.duplicate_keys.

property duplicate_keys: set[str]

The field-keys that occurred more than once in the entry.

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

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

property entry_type: str

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.

get(key: str, default=None) → Field | None

Returns the field with the given key, or the default value if it does not exist.

Parameters:

• key – The key of the field.

• default – The value to return if the field does not exist.

items() → list[tuple[str, Any]]

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: str

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

pop(key: str, default=None) → Field | None

Removes and returns the field with the given key.

Parameters:

• key – The key of the field to remove.

• default – The value to return if the field does not exist.

set_field(field: Field)

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)

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, enclosing: str | None = None)

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

property enclosing: str | None

The enclosing demanded when writing this field, e.g. '{'.

Allowed values are '{', '"' and 'no-enclosing'. None (the default) leaves the choice to the writing middleware (see AddEnclosingMiddleware), which is the right choice for most use-cases.

A demand of 'no-enclosing' is used for values that must be written verbatim, such as bibtex string references (month = jan) or concatenation expressions (pages = intro # outro), where adding an enclosing would change the semantics of the value.

Note: Assigning a new value to the field resets this attribute to None.

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)

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

property comment: str

The (possibly multi-line) comment.

class bibtexparser.model.MiddlewareErrorBlock(block: Block, error: Exception)

A block that could not be parsed due to a middleware error.

To get the block that caused this error, call block.ignore_error_block (which is the block with the middleware not or only partially applied).

class bibtexparser.model.ParsingFailedBlock(error: Exception, start_line: int | None = None, raw: str | None = None, ignore_error_block: Block | None = None)

A block that could not be parsed due to some raised exception.

property error: Exception

The exception that was raised during parsing.

property ignore_error_block: Block | None

The possibly faulty block when ignoring the error.

This may be None, as it may not always be possible to ignore the error. For errors caused by middleware, this is typically the block without the middleware applied.

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

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, enclosing: str | None = None)

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

property enclosing: str | None

The enclosing demanded when writing this string, e.g. '{'.

Allowed values are '{', '"' and 'no-enclosing'. None (the default) leaves the choice to the writing middleware (see AddEnclosingMiddleware), which is the right choice for most use-cases.

Note: Assigning a new value to the string resets this attribute to None.

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