bibdeskparser 0.2.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.

Making the bibliographic database accessible to AI coding agents is an explicit goal of the project: the bibdeskparser command-line tool mirrors the public Python API, so any agent that can run shell commands can inspect and edit a BibDesk library, with no dedicated integration and no server to keep running. See How to give an AI coding agent access to your library.

Installation

To install the latest released version of BibDeskParser:

pip install bibdeskparser

If you use uv, add BibDeskParser as a dependency of your project with

uv add bibdeskparser

or install the bibdeskparser command-line tool on your PATH, independently of any project, with

uv tool install 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.

To put the bibdeskparser command-line tool on your PATH as an editable install that links back to your working copy — so changes to the source take effect without reinstalling — run

make install

Use make uninstall to remove it again.