Tutorial¶
Preparing a BibTeX file¶
Prepare a BibTeX sample file for illustration purpose:
bibtex = """@ARTICLE{Cesar2013,
author = {Jean César},
title = {An amazing title},
year = {2013},
month = jan,
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)
Parsing the file into a bibliographic database object¶
OK. Everything is in place. Let’s parse the BibTeX file.
import bibtexparser
with open('bibtex.bib') as bibtex_file:
bibtex_str = bibtex_file.read()
bib_database = bibtexparser.loads(bibtex_str)
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',
'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'}]
Note that, by convention, uppercase keys are auto-generated data, while lowercase keys come from the original bibtex file.
Alternatively, you can parse a file-like object directly like this:
import bibtexparser
with open('bibtex.bib') as bibtex_file:
bib_database = bibtexparser.load(bibtex_file)
Creating a BibTeX file or string¶
The bibliographic data can be converted back into a BibTeX file like this:
import bibtexparser
bibtex_str = bibtexparser.dumps(bib_database)
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 content accents and specific characters.
They are sometimes coded like this \'{e}
but this is not the correct way, {\'e}
is prefered. 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 homogeneize_latex_encoding
with open('bibtex.bib') as bibtex_file:
parser = BibTexParser()
parser.customization = homogeneize_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 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',
'type': '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',
'type': '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 bibtexparser: API for the full list of flags.