Pybtex: BibTeX-compatible bibliography processor

Warnings

• gotcha Pybtex uses two distinct 'engines' for bibliography formatting: a BibTeX engine (for `.bst` styles) and a Python engine (for Pythonic styles). The BibTeX engine can only output LaTeX, while the Python engine supports LaTeX, HTML, Markdown, and plain text. When using Pythonic styles, remember to specify `--style-language python` and `--output-backend <format>` via the command line or explicitly use the Python API for desired output formats.
  Fix: For `.bst` styles, expect LaTeX output. For HTML/Markdown/plain text output, use Pythonic styles and configure the output backend explicitly (e.g., `pybtex --style-language python --output-backend html` or use `pybtex.database.output.html.Writer` in API).
• gotcha When working with `BibliographyData` `Entry` objects in the Python API, access person-related fields (authors, editors, etc.) through the `entry.persons` dictionary, not `entry.fields`. `entry.fields` contains general string fields, while `entry.persons` holds a list of `Person` objects for each role. Additionally, `Entry` objects are not directly indexable.
  Fix: Use `entry.persons['author']` for authors and `entry.fields['title']` for titles. Avoid `entry[0]` as `Entry` objects do not support indexing.
• gotcha Pybtex's strict mode behavior differs between command-line usage and library usage. By default, command-line execution prints warnings to stderr for compatibility with BibTeX, whereas programmatic use as a library will raise exceptions on all errors. This can lead to unexpected crashes if not handled.
  Fix: When using Pybtex programmatically, anticipate and handle `PybtexError` exceptions. For command-line use, the `--strict` option can be used to make warnings into errors.
• deprecated The API for reading and writing bibliography data has evolved. Earlier methods like `Entry.get_field()` were deprecated. New API for rich text and general data handling was introduced around versions 0.19 and 0.22.
  Fix: Consult the latest Pybtex documentation for the recommended API when reading/writing data and creating custom styles, especially for `pybtex.richtext` objects.

Install

• pip install pybtex Install Pybtex

Imports

• BibliographyData

  from pybtex.database import BibliographyData

  Main object for holding parsed bibliography data.
• Parser

  from pybtex.database.input.bibtex import Parser

  For parsing BibTeX (.bib) files.
• Writer

  from pybtex.database.output.html import Writer

  For writing bibliography data to various output formats (e.g., HTML, LaTeX, text).
• BaseStyle

  from pybtex.style.formatting import BaseStyle

  Base class for defining custom bibliography formatting styles in Python.
• Text

  from pybtex.richtext import Text

  Used within Pythonic styles for rich text manipulation.

Quickstart

This quickstart demonstrates how to parse a BibTeX file, apply a predefined formatting style (or a custom one), and output the result to an HTML file using Pybtex's Python API. It creates a dummy `.bib` file, processes it, and then cleans up the generated files. For more complex use cases, especially with `.aux` files, the command-line interface or the `pybtex.Engine` might be more suitable.

from pybtex.database.input import bibtex
from pybtex.database.output import html
from pybtex.style.formatting import plain
from pybtex.style.template import field, sentence, tag
import os

# Create a dummy .bib file for demonstration
bib_content = """
@article{einstein1905relativity,
  title={Zur Elektrodynamik bewegter K\"orper},
  author={Einstein, Albert},
  journal={Annalen der Physik},
  volume={322},
  number={10},
  pages={891-921},
  year={1905},
  doi={10.1002/andp.19053221006}
}
"""
with open('references.bib', 'w') as f:
    f.write(bib_content)

# 1. Parse the bibliography data
parser = bibtex.Parser()
bib_data = parser.parse_file('references.bib')

# 2. Select a formatting style (e.g., 'plain' or a custom one)
# For a custom style, you would inherit from BaseStyle
style = plain.Style()

# 3. Format the bibliography
# The 'citations' argument specifies which entries to include. 
# If not provided, all entries in bib_data will be formatted.
formatted_bibliography = style.format_bibliography(bib_data, citations=['einstein1905relativity'])

# 4. Write the formatted bibliography to an output file (e.g., HTML)
writer = html.Writer()
with open('output.html', 'w') as f:
    writer.write_file(formatted_bibliography, f)

print("Bibliography processed and saved to output.html")

# Clean up dummy file
os.remove('references.bib')
os.remove('output.html')