bibdeskparser 0.1.0

Parser for Bibdesk database files

BibDeskParser

BibDeskParser reads and writes BibDesk .bib files exactly as BibDesk itself produces them: the header comment, linked files and URLs, @string macros, and static groups all round-trip byte-for-byte. The API centers on two classes: Library, a dict-like mapping of citation key to Entry, and Entry, a single bibliography record.

Development of BibDeskParser happens on Github.

You can read the full documentation online. See the page on BibDesk's .bib format for details on how BibDesk's special .bib features are handled, and the how-to guides for short recipes covering specific tasks.

Introduction

BibDesk is a bibliography manager for macOS that stores its database library as a standard BibTeX .bib file, but adds its own conventions on top of plain BibTeX -- tracking linked file attachments (macOS-specific), recording user-defined groups, custom support for @string macros and keyword fields, and more.

These extended features are stored in custom fields of individual entries, and in comments in the .bib file. A generic BibTeX library like BibtexParser is not aware of these BibDesk-specific features and thus provides no direct access to the stored data, and may even corrupt it on a round trip. BibDeskParser exists so you can read, script, and edit your BibDesk library directly in Python -- for batch edits, automation, or integration with other tools. It provides a simplified API on top of the BibtexParser library.

Installation

To install the latest released version of BibDeskParser:

pip install bibdeskparser

or, if you use uv:

uv add bibdeskparser

To install the latest development version from Github:

pip install git+https://github.com/goerz/bibdeskparser.git@master#egg=bibdeskparser

Usage

>>> import tempfile
>>> from pathlib import Path
>>> from bibdeskparser import Entry, Library
>>> tmpdir = tempfile.TemporaryDirectory()
>>> bib_path = Path(tmpdir.name) / "references.bib"
>>> bib = Library()
>>> bib["Smith2020"] = Entry(
...     "article",
...     "Smith2020",
...     fields={
...         "title": "A Title",
...         "author": "Smith, John and Doe, Jane",
...         "journal": "J. Test",
...         "year": "2020",
...     },
... )
>>> bib.save(bib_path)

>>> bib = Library(bib_path)
>>> entry = bib["Smith2020"]
>>> print(entry["title"])
A Title
>>> print(entry.author[0].last[0])  # 'Smith'
Smith

>>> entry["title"] = "A Better Title"
>>> bib.groups["Favorites"] = ("Smith2020",)  # BibDesk static group
>>> entry.groups
('Favorites',)
>>> bib.save()
>>> tmpdir.cleanup()

Development

The project uses uv to manage the development environment and make as a task runner. After cloning the repository, run

make develop

to create a virtual environment with all development dependencies. Run make help for an overview of available targets, and see CONTRIBUTING.md for full contributing guidelines.