Tutorial¶

Step 0: Vocabulary¶

An entry designates for example @book{…}, @article{…}, etc.
A comment is written as @comment{…}.
A preamble is a @preamble{…} block.
A string is @string{…}.

In an entry, you can find

an entry type like article, book, etc.
entry keys or keys such as author, title, year…
and also records, which designates the values of those keys.

Step 1: Prepare a BibTeX file¶

First, we prepare a BibTeX sample file. This is just for the purpose of illustration:

bibtex = """@ARTICLE{Cesar2013,
  author = {Jean César},
  title = {An amazing title},
  year = {2013},
  volume = {12},
  pages = {12--23},
  journal = {Nice Journal},
  abstract = {This is an abstract. This line should be long enough to test
     multilines...},
  comments = {A comment},
  keywords = {keyword1, keyword2}
}
"""

with open('bibtex.bib', 'w') as bibfile:
    bibfile.write(bibtex)

Step 2: Parse it!¶

Simplest call¶

OK. Everything is in place. Let’s parse the BibTeX file.

import bibtexparser

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

print(bib_database.entries)

It prints a list of dictionaries for reference entries, for example books, articles:

[{'journal': 'Nice Journal',
  'comments': 'A comment',
  'pages': '12--23',
  'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
  'title': 'An amazing title',
  'year': '2013',
  'volume': '12',
  'ID': 'Cesar2013',
  'author': 'Jean César',
  'keyword': 'keyword1, keyword2',
  'ENTRYTYPE': 'article'}]

Note that, by convention, uppercase keys (ID, ENTRYTYPE) are data generated by the parser, while lowercase keys come from the original bibtex file.

You can also print comments, preambles and string:

print(bib_database.comments)
print(bib_database.preambles)
print(bib_database.strings)

Note

If your bibtex contains months defined as strings such as month = jan, you will need to parse it with the common_strings option: bib_database = bibtexparser.bparser.BibTexParser(common_strings=True).parse_file(bibtex_file). (More in Using bibtex strings.)

Parse a string¶

If for some reason, you prefer to parse a string, that’s also possible:

import bibtexparser

with open('bibtex.bib') as bibtex_file:
    bibtex_str = bibtex_file.read()

bib_database = bibtexparser.loads(bibtex_str)

Tune parser’s options¶

In the previous snippet, several default options are used. You can tweak them as you wish.

import bibtexparser
from bibtexparser.bparser import BibTexParser

parser = BibTexParser(common_strings=False)
parser.ignore_nonstandard_types = False
parser.homogenise_fields = False

bib_database = bibtexparser.loads(bibtex_str, parser)

Note

The common_strings option needs to be set when the parser object is created and has no effect if changed afterwards.

Step 3: Export¶

Once you worked on your parsed database, you may want to export the result. This library provides some functions to help on that. However, you can write your own functions if you have specific requirements.

Create a BibTeX file or string¶

The bibliographic data can be converted back into a string :

import bibtexparser

bibtex_str = bibtexparser.dumps(bib_database)

or a BibTeX file like this:

import bibtexparser

with open('bibtex.bib', 'w') as bibtex_file:
    bibtexparser.dump(bibtex_database, bibtex_file)

Call the writer¶

In the first section we prepared a BibTeX sample file, we can prepare the same file using pure python and the BibTexWriter class.

from bibtexparser.bwriter import BibTexWriter
from bibtexparser.bibdatabase import BibDatabase

db = BibDatabase()
db.entries = [
    {'journal': 'Nice Journal',
     'comments': 'A comment',
     'pages': '12--23',
     'month': 'jan',
     'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
     'title': 'An amazing title',
     'year': '2013',
     'volume': '12',
     'ID': 'Cesar2013',
     'author': 'Jean César',
     'keyword': 'keyword1, keyword2',
     'ENTRYTYPE': 'article'}]

writer = BibTexWriter()
with open('bibtex.bib', 'w') as bibfile:
    bibfile.write(writer.write(db))

This code generates the following file:

@article{Cesar2013,
 abstract = {This is an abstract. This line should be long enough to test
multilines...},
 author = {Jean César},
 comments = {A comment},
 journal = {Nice Journal},
 keyword = {keyword1, keyword2},
 month = {jan},
 pages = {12--23},
 title = {An amazing title},
 volume = {12},
 year = {2013}
}

The writer also has several flags that can be enabled to customize the output file. For example we can use indent and comma_first to customize the previous entry, first the code:

from bibtexparser.bwriter import BibTexWriter
from bibtexparser.bibdatabase import BibDatabase

db = BibDatabase()
db.entries = [
    {'journal': 'Nice Journal',
     'comments': 'A comment',
     'pages': '12--23',
     'month': 'jan',
     'abstract': 'This is an abstract. This line should be long enough to test\nmultilines...',
     'title': 'An amazing title',
     'year': '2013',
     'volume': '12',
     'ID': 'Cesar2013',
     'author': 'Jean César',
     'keyword': 'keyword1, keyword2',
     'ENTRYTYPE': 'article'}]

writer = BibTexWriter()
writer.indent = '    '     # indent entries with 4 spaces instead of one
writer.comma_first = True  # place the comma at the beginning of the line
with open('bibtex.bib', 'w') as bibfile:
    bibfile.write(writer.write(db))

This code results in the following, customized, file:

@article{Cesar2013
,    abstract = {This is an abstract. This line should be long enough to test
multilines...}
,    author = {Jean César}
,    comments = {A comment}
,    journal = {Nice Journal}
,    keyword = {keyword1, keyword2}
,    month = {jan}
,    pages = {12--23}
,    title = {An amazing title}
,    volume = {12}
,    year = {2013}
}

Flags to the writer object can modify not only how an entry is printed but how several BibTeX entries are sorted and separated. See the API for the full list of flags.

Step 4: Add salt and pepper¶

In this section, we discuss about some customizations and details.

Customizations¶

By default, the parser does not alter the content of each field and keeps it as a simple string. There are many cases where this is not desired. For example, instead of a string with a multiple of authors, it could be parsed as a list.

To modify field values during parsing, a callback function can be supplied to the parser which can be used to modify BibTeX entries. The library includes several functions which may be used. Alternatively, you can read them to create your own functions.

import bibtexparser
from bibtexparser.bparser import BibTexParser
from bibtexparser.customization import *

# Let's define a function to customize our entries.
# It takes a record and return this record.
def customizations(record):
    """Use some functions delivered by the library

    :param record: a record
    :returns: -- customized record
    """
    record = type(record)
    record = author(record)
    record = editor(record)
    record = journal(record)
    record = keyword(record)
    record = link(record)
    record = page_double_hyphen(record)
    record = doi(record)
    return record

with open('bibtex.bib') as bibtex_file:
    parser = BibTexParser()
    parser.customization = customizations
    bib_database = bibtexparser.load(bibtex_file, parser=parser)
    print(bib_database.entries)

If you think that you have a customization which could be useful to others, please share with us!

Accents and weird characters¶

Your bibtex may contain accents and specific characters. They are sometimes coded like this \'{e} but this is not the correct way, {\'e} is preferred. Moreover, you may want to manipulate é. There is different situations:

Case 1: you plan to use this library to work with latex and you assume that the original bibtex is clean. You have nothing to do.
Case 2: you plan to use this library to work with latex but your bibtex is not really clean.

import bibtexparser
from bibtexparser.bparser import BibTexParser
from bibtexparser.customization import homogenize_latex_encoding

with open('bibtex.bib') as bibtex_file:
    parser = BibTexParser()
    parser.customization = homogenize_latex_encoding
    bib_database = bibtexparser.load(bibtex_file, parser=parser)
    print(bib_database.entries)

Case 3: you plan to use this library to work with something different and your bibtex is not really clean. Then, you probably want to use unicode.

import bibtexparser
from bibtexparser.bparser import BibTexParser
from bibtexparser.customization import convert_to_unicode

with open('bibtex.bib') as bibtex_file:
    parser = BibTexParser()
    parser.customization = convert_to_unicode
    bib_database = bibtexparser.load(bibtex_file, parser=parser)
    print(bib_database.entries)

Note

If you want to mix different customization functions, you can write your own function.

Using bibtex strings¶

Warning

support for bibtex strings representation is still an experimental feature; the way strings are represented is likely to change in future releases.

Bibtex strings and string expressions are expanded by default into the value they represent. This behavior is controlled by the interpolate_string argument of the BibTexParser. It defaults to True but can be set to False, in which case bibtex strings and string expressions from input files are represented with the bibdatabase.BibDataString and bibdatabase.BibDataStringExpression from the bibdatabase module. Both classes retain the intrinsic structure of the string or expression so that they can be written to a new file, the same way. Each instance provides a get_value() method to interpolate the string or expression and the module also provide an bibdatabase.as_text() helper to expand a string or an expression when needed.

Using the code would yield the following output.

from bibtexparser.bparser import BibTexParser
from bibtexparser.bibdatabase import as_text


bibtex = """@STRING{ jean = "Jean"}

@ARTICLE{Cesar2013,
  author = jean # { César},
  title = {An amazing title},
  year = {2013},
  month = jan,
  volume = {12},
  pages = {12--23},
  journal = {Nice Journal},
}
"""

bp = BibTexParser(interpolate_strings=False)
bib_database = bp.parse(bibtex)
bib_database.entries[0]
as_text(bd.entries[0]['author'])

{'ENTRYTYPE': 'article',
 'ID': 'Cesar2013',
 'author': BibDataStringExpression([BibDataString('jean'), ' César']),
 'journal': 'Nice Journal',
 'month': BibDataStringExpression([BibDataString('jan')]),
 'pages': '12--23',
 'title': 'An amazing title',
 }
'Jean César'

Tutorial¶

Step 0: Vocabulary¶

Step 1: Prepare a BibTeX file¶

Step 2: Parse it!¶

Simplest call¶

Parse a string¶

Tune parser’s options¶

Step 3: Export¶

Create a BibTeX file or string¶

Call the writer¶

Step 4: Add salt and pepper¶

Customizations¶

Accents and weird characters¶

Using bibtex strings¶

Table of Contents

Previous topic

Next topic

This Page