bibrecord.bibtex module

Facilities for reading BibTeX bibliographies.

The BibTeX bibliography file format is not too explicitly specified, but there is a bunch of information available, both from the original author of BibTeX (Oren Patashnik) and from the documentation of tools working with BibTeX bibliographies and entries.

For the time being, this module implements parsing facilities for BibTeX databases using a best effort approach and requiring well-formatted BibTeX entries.

Generally, individual entries of a bibliography are represented by an object of the Entry class. This class does not provide extended logic for dealing with the particular types of bibliographic records, as this is part of the bibrecord.record module.

Entire BibTeX bibliographies (as typically residing in *.bib files) can be read and converted into Entry objects using the Bibliography class.

Classes

The two important classes for representing BibTeX bibliographies are:

Entry

Representation of a BibTeX entry.
Bibliography

Representation of a BibTeX bibliography, e.g. as read from a file.

Limitations

There are many limitations for the time being, as this module does not intend to be a full BibTeX parser.

BibTeX records are expected to be well-formatted.
String replacement (e.g., for Journal names) is currently not supported.

Module documentation

class bibrecord.bibtex.Entry

Bases: object

Representation of a BibTeX entry.

Regardless of the type of BibTeX entry, this class will contain all relevant information, such as type, key, and fields. This information can be used by objects of type bibrecord.record.Record to read their contents from a BibTeX entry. The idea is to provide means by which the bibliographic records contained in a BibTeX file can be read and converted into bibrecord.record.Record objects of appropriate type.

type

Type of the BibTeX entry, such as “article” or “book”

Note that regardless of the original way the BibTeX entry was written, type will always be all lowercase.

Type:: str

key

BibTeX key used to refer to the record

Type:: str

fields

Key-value store of all the fields of a BibTeX entry

Type:: dict

record

Multiline string containing the original BibTeX entry

Type:: str

Examples

Assume a BibTeX entry to exist in a multiline string bibtex_record. Converting this multiline string into a Entry object with all the information accessible for later conversion into a bibrecord.record.Record object would look as follows:

entry = Entry()
entry.from_bib(bibtex_record)

For further details, see the documentation for from_bib().

New in version 0.2.

from_bib(bibtex_record=None)

Read BibTeX entry from string and parse the contents.

Currently, the format of the BibTeX records is quite restricted. They need to be a multiline string, with the type and key on the first line and all fields on separate lines. A typical BibTeX record looks similar to:

@Article{doe-foo-1-1,
    author = {John Doe},
    title = {Lorem ipsum},
    journal = {Foo},
    pages = {1--2},
    year = {2024}
}

More generally, a bibtex record could be understood as following this overall scheme:

@TYPE{KEY,
    FIELD = VALUE,
    FIELD = VALUE
}

Upon parsing such an entry, the attributes of the class Entry with the corresponding names will be set, i.e. Entry.type will be set to the lower-case version of “TYPE”, Entry.key to KEY, et cetera.

All fields will be parsed and the Entry.fields dict populated accordingly. Here, it does not matter whether values are surrounded by { or " and whether they have a trailing comma.

Authors and editors are split at the (case-insensitive) “AND” and stored as a list of strings.

Parameters:: bibtex_record (str) – Multiline string containing a BibTeX record

class bibrecord.bibtex.Bibliography

Bases: object

Representation of a BibTeX bibliography, e.g. as read from a file.

A BibTeX bibliography is a series of individual bibliographic records that can be of different types. For more information on the overall format of BibTeX bibliographies, have a look at the available online resources.

Here, the bibliography represents the individual bibliographic records contained in a BibTeX bibliography as objects of class Entry.

entries

Entries of the bibliography

Each entry is an object of type Entry.

Type:: list

Examples

Assume a BibTeX entry to exist in a multiline string bibtex_db. Converting this multiline string into a Bibliography object with all the individual entries contained in Bibliography.entries as Entry objects would look as follows:

bibliography = Bibliography()
bibliography.from_bib(bibtex_db)

The individual entries in turn make the information contained accessible for later conversion into a bibrecord.record.Record object.

For further details, see the documentation for from_bib().

New in version 0.2.

from_bib(bibliography='')

Read BibTeX bibliography and convert it into individual entries.

Each entry is of type Entry.

The bibliography is split on \n@, i.e. a @ sign following a linebreak.

Parameters:: bibliography (str) – BibTeX bibliography, e.g. read from a file
Raises:: ValueError – Raised if no bibliography is provided

from_file(filename='')

Read BibTeX bibliography and convert it into individual entries.

For details of how the file contents are parsed, see from_bib().

Parameters:: filename (str) – Name of the BibTeX file to read bibliography from