Configuration

bibdeskparser can be configured with a TOML file named bibdeskparser.toml. The file replicates some of the preferences that the BibDesk application itself offers – most importantly, which entry types and fields are considered valid (see Bib Entry Types).

Where the file is found

When bibdeskparser is imported, and again whenever a Library is constructed, it searches for a bibdeskparser.toml in the following locations, in order of precedence. The first file found wins; the others are ignored.

  1. The path assigned to Library.config.config_file (see Library and below), if any. An explicit config_file that does not exist raises a FileNotFoundError.

  2. The directory containing the .bib file that is being loaded (or the current working directory, for a library not loaded from a file – and at import time).

  3. The file named by the $BIBDESKPARSER_CONFIG environment variable, if the variable is set. A file that does not exist raises a FileNotFoundError. Setting the variable to an empty value disables the user-level configuration (this step and the next) entirely.

  4. The XDG configuration directory: $XDG_CONFIG_HOME/bibdeskparser/bibdeskparser.toml, falling back to ~/.config/bibdeskparser/bibdeskparser.toml when $XDG_CONFIG_HOME is unset. This location is only considered when $BIBDESKPARSER_CONFIG is unset.

The configuration is applied process-wide: it affects every Entry, whether or not it belongs to a library.

The default_bib_file option

A string option, unset by default, naming the .bib file that the command-line interface operates on when no BIBFILE argument is given:

default_bib_file = "$HOME/Documents/library.bib"

Environment variables ($VAR) and a leading ~ in the value are expanded. The option has no effect on the Python API.

Setting default_bib_file is the recommended setup for command-line use: all examples in the CLI --help output (and most in this documentation) assume it, so that commands can be spelled without naming the .bib file each time.

The verify_types and verify_fields flags

Two boolean options, both defaulting to true, control validation:

verify_types = true
verify_fields = true

  • verify_types: when true (the default), constructing an entry with an unrecognized type, or assigning such a type, raises a ValueError. Set it to false to accept any entry type (still lowercased).

  • verify_fields: when true (the default), assigning a field that is not appropriate for an entry’s type emits a UserWarning (the value is stored regardless). Set it to false to suppress those warnings entirely.

The active configuration is exposed as the config class attribute of Library (equally readable from any library instance, as bib.config), so every setting can also be changed from Python, without a configuration file:

>>> from bibdeskparser import Library
>>> Library.config.verify_types
True
>>> Library.config.verify_types = False   # accept any entry type
>>> Library.config.verify_types = True    # restore the default
>>> Library.config.verify_types
True

Assigning to a Library.config attribute overrides the value for the current process only; it never writes back to the bibdeskparser.toml file. Note that constructing a Library re-applies whichever configuration file is discovered, which replaces such overrides; set the attributes after constructing a library, or point Library.config.config_file (default None) at a file to force that file to be used, ahead of directory-based discovery.

The [auto_key] table: autogenerated citation keys

The [auto_key] table configures the automatic generation of citation keys by single-argument rekey() (and the rekey CLI command without a NEW_KEY):

[auto_key]
format_spec = "%a1%c{journal}0%Y%u0"
lowercase = false   # lowercase the whole generated key
clean = "tex"       # TeX cleanup: "none", "braces", or "tex"

  • format_spec (required within the table): the key format, in BibDesk’s format-specifier language. Each format is validated when the configuration is loaded. Without an [auto_key] table, generating a key requires an explicit format_spec pattern. It may also be a per-type mapping.

  • lowercase (default false): lowercase the entire generated key, like BibDesk’s Generate lowercase option.

  • clean (default "tex"): how much TeX markup to strip from field values, like BibDesk’s Remove TeX options: "tex" removes TeX commands and braces, "braces" only braces, "none" neither.

The table is exposed as Library.config.auto_key (see Library), with format_spec, lowercase, and clean attributes; assigning format_spec validates every format string in it.

Per-type formats

The venue of a publication lives in a different field per entry type — journal for an @article, booktitle for an @inproceedings, series for a @book — so a single format is rarely right for a mixed library. Instead of a plain string, format_spec may be a table mapping each entry type to its own format. The empty-string key "" is the fallback for types not listed:

[auto_key.format_spec]
"" = "%a1%Y%u0"                        # fallback for any other type
article = "%a1%c{journal}0%Y%u0"
inproceedings = "%a1%c{booktitle}0%Y%u0"
incollection = "%a1%c{booktitle}0%Y%u0"
book = "%a1%c{series}0%Y%u0"

The entry’s own type selects the format; generating a key for a type that is neither listed nor covered by a "" fallback is an error. (lowercase and clean still apply uniformly to every type.)

The [auto_file] table: autogenerated attachment file names

The [auto_file] table configures the automatic filing of attached files (BibDesk’s AutoFile feature): moving them into a designated location and renaming them according to a file-name format. It is used by rename_file() without a new_filename, by add_file() when auto-filing, and by the corresponding CLI commands (see the how-to guide):

[auto_file]
format_spec = "%f{Cite Key}%u0%e"
location = "."             # directory files are moved into
lowercase = false          # lowercase the whole generated name
clean = "tex"              # TeX cleanup: "none", "braces", or "tex"
file_automatically = false # auto-file on add_file by default

  • format_spec (required within the table): the file-name format, in the file-name dialect of BibDesk’s format-specifier language; it must contain a unique specifier (%u/%U/%n). Each format is validated when the configuration is loaded. Without an [auto_file] table, generating a file name requires an explicit format_spec pattern. Like the [auto_key] format, it may be a per-type mapping. The recommended format is %f{Cite Key}%u0%e, which names each attachment after its entry’s citation key while preserving the file’s real extension.

  • location (default "."): the directory that auto-filed attachments are moved into – BibDesk’s Papers Folder. A relative path is interpreted against the directory containing the .bib file (so the default files attachments next to the library, like BibDesk with an empty Papers Folder preference); an absolute path names a fixed folder. Environment variables ($VAR) and a leading ~ are expanded. Missing directories are created as needed.

  • lowercase (default false): lowercase the entire generated file name.

  • clean (default "tex"): how much TeX markup to strip from field values: "tex" removes TeX commands and braces, "braces" only braces, "none" neither.

  • file_automatically (default false): when true, add_file() auto-files every newly attached file by default, the equivalent of BibDesk’s File papers into the papers folder automatically preference. Regardless of this setting, on-demand filing – rename_file without a new name, add_file with an explicit format_spec/auto_file_location, and previews via eval_format_spec – is available whenever the table is present.

The table is exposed as Library.config.auto_file (see Library), with format_spec, location, lowercase, clean, and file_automatically attributes; assigning format_spec or location validates the value.

The [add], [add_abstract], and [add_preprint] tables: fetching defaults

These three tables configure the default behavior of the fetching methods add(), add_abstract(), and add_preprint() (and the like-named CLI commands). Each key is the default for the like-named keyword argument (or command-line option); passing an explicit value – e.g. --no-add-abstract to override a configured add_abstract = true – always wins:

[add]                     # defaults for `add`
fix_uppercase = false     # repair all-uppercase publisher metadata
add_abstract = false      # store the abstract the source returns
add_preprint = false      # search arXiv for a matching preprint

[add_abstract]            # defaults for `add_abstract`
min_confidence = "high"   # lowest confidence stored: "high", "medium", "low"
mark_empty = false        # store an empty abstract when none is found

[add_preprint]            # defaults for `add_preprint`
mark_empty = false        # store an empty eprint when no preprint is found

The mark_empty keys control whether a clean “searched, found nothing” outcome is recorded in the entry as an empty field – the audited marker that keys --empty <field> matches, as opposed to keys --missing <field> (see the how-to guide). The tables are exposed as Library.config.add, Library.config.add_abstract, and Library.config.add_preprint (see Library).

The [initials] table: acronym exceptions

The [initials] table defines, per field, exceptions to the acronym that the %c format specifier builds from a field value (see Venue initials). Keys are full field values or @string macro names:

[initials.journal]
"npj Quantum Inf" = "NPJQI"
"SIAM Rev." = "SR"

[initials.booktitle]           # for %c{booktitle} on conference papers
"Proc. SPIE 11700, Optical and Quantum Sensing" = "SPIE"

With per-type formats, supply an [initials.<field>] table for each venue field your formats reference ([initials.booktitle], [initials.series], …) alongside [initials.journal].

The [initials.journal] exceptions are also used by import_bibtex() (and add()) when they have to invent an @string macro for a journal that is neither in the library nor in the [journal_macros] table: the new macro is named by the journal’s lowercased initials.

The [journal_macros] table: journal-name-to-macro mappings

When entries are imported (import_bibtex(), add(), and the corresponding CLI commands), every journal name is replaced by an @string macro reference. A journal that does not match the value of a macro already in the library is looked up in the [journal_macros] table, which maps a macro name to the journal name it stands for:

[journal_macros]
prl = "Phys. Rev. Lett."
jpb = ["J. Phys. B", "J. Phys. B: At. Mol. Opt. Phys."]

A list value declares aliases: the first name is the canonical value of the macro (what the @string will define), and any of the names resolves to the macro on import – use this to canonicalize the various spellings publishers use for the same journal. When an imported journal matches a [journal_macros] entry whose macro is not yet defined in the library, the @string definition is added automatically.

A journal found in neither the library nor the table gets a newly created macro (named by its lowercased initials, honoring [initials.journal]), with a warning – so a curated [journal_macros] table keeps macro names and journal abbreviations consistent across libraries. The table is exposed as Library.config.journal_macros, a dict mapping each macro name to a tuple of journal names.

The protected_words list

Words (or phrases) that import_bibtex() (and add()) always wraps in braces inside an imported title, protecting their capitalization from being lowercased by bibliography styles:

protected_words = ["Schrödinger", "Rydberg", "Bose", "Einstein", "NMR"]

Independent of this list, import brace-protects every capitalized word of a title that looks like it is in sentence case (a heuristic for proper nouns); protected_words guarantees protection for the listed words even in title-case titles, where the heuristic does not apply. Words that are already braced are left alone. The list is exposed as Library.config.protected_words.

Custom and extended entry types

A [types.NAME] table defines the mandatory (required) and optional (optional) fields of an entry type, exactly like BibDesk’s per-type field templates. This both makes NAME a recognized entry type and, when verify_fields is on, determines which fields are considered appropriate for it.

For an entry type that is not already built in, the table simply defines it:

[types.dataset]
required = ["author", "title", "year"]
optional = ["note", "url"]

For a type that is built in, the fields you list are added to the built-in template by default:

[types.article]
optional = ["eprint"]   # article keeps its built-in fields, plus eprint

To discard the built-in template and define the type from scratch, set replace = true:

[types.report]
replace = true
required = ["author", "title", "year"]
optional = ["note"]

Custom fields

A [fields] table adds recognized field names without tying them to a particular type:

[fields]
# accepted on every entry type, like keywords or note
universal = ["mycustomtag"]
# recognized, but not treated as universal
known = ["someotherfield"]

A universal field never triggers the inappropriate-field warning, whatever the entry type. A known field is recognized for entry types that have no field template of their own, but is not automatically appropriate for a templated type.

A complete example

# bibdeskparser.toml
default_bib_file = "~/Documents/Refs/refs.bib"   # what the CLI operates on

verify_types = true
verify_fields = true

protected_words = [          # words import always brace-protects in titles
    "Schrödinger", "Rydberg", "Krotov", "Bose", "Einstein", "Dirac",
    "NMR", "GRAPE", "CRAB",
]

[auto_key.format_spec]       # autogenerated citation keys, per type
"" = "%a1%Y%u0"              # fallback for any other type
article = "%a1%c{journal}0%Y%u0"
inproceedings = "%a1%c{booktitle}0%Y%u0"
incollection = "%a1%c{booktitle}0%Y%u0"
book = "%a1%c{series}0%Y%u0"

[auto_file]                  # autogenerated attachment file names
format_spec = "%f{Cite Key}%u0%e"
location = "~/Documents/Papers"  # directory files are moved into
lowercase = false          # lowercase the whole generated name
clean = "tex"              # TeX cleanup: "none", "braces", or "tex"
file_automatically = true  # auto-file on add_file by default

[add]                        # defaults for the `add` command
add_abstract = true          # store the abstract the source returns
add_preprint = true          # search arXiv for a matching preprint

[add_preprint]               # defaults for the `add_preprint` command
mark_empty = true            # record "searched, no preprint" markers

[initials.journal]                   # acronym exceptions for %c{journal}
"AIP Advances" = "AIPA"
"AVS Quantum Sci." = "AVSQS"
"BIT" = "BIT"
"Commun. ACM" = "CACM"
"EPJ Quantum Technol." = "EPJQT"
"IEEE J. Quantum Electron." = "IEEEJQE"
"IEEE Trans. on Appl. Superc." = "ITAS"  # would keep "on" → "ITOAS"
"IET Control Theory Appl." = "IETCTA"
"IMA J. Appl. Math." = "IMAJAM"
"npj Quantum Inf" = "NPJQI"          # would otherwise acronym to "NQI"
"Proc. IRE" = "PIRE"
"Proc. Natl. Acad. Sci. U.S.A" = "PNAS"
"PRX Quantum" = "PRXQ"
"SciPost Phys." = "SPP"
"WIREs Data Mining Knowl Discov." = "WIDM"

[initials.booktitle]         # exceptions for conference proceedings
"Proc. SPIE 11700, Optical and Quantum Sensing and Precision Metrology" = "SPIE"

[types.dataset]              # a new entry type
required = ["author", "title", "year"]
optional = ["note", "url"]

[types.article]              # extend a built-in type
optional = ["eprint", "eprinttype"]

[fields]
universal = ["mytag"]

[journal_macros]             # journal spellings not matching the library
jcp = ["J. Chem. Phys.", "The Journal of Chemical Physics"]
jpb = ["J. Phys. B", "J. Phys. B: At. Mol. Opt. Phys."]

[add_abstract]               # defaults for the add_abstract command
min_confidence = "high"
mark_empty = false

With this configuration, the command-line tool operates on ~/Documents/Refs/refs.bib unless another .bib file is named explicitly, and an @article in Phys. Rev. A is keyed Goerz2014 → GoerzPRA2014. The PRA comes straight from %c{journal}0, which acronyms every word of the venue, so no [initials.journal] entry is needed for it (the recommended pattern; see venue initials). By contrast, an @inproceedings in the SPIE proceedings above becomes GoerzSPIE2021: that long booktitle acronyms to an unhelpful jumble of letters and volume digits, so [initials.booktitle] pins it to SPIE. A @misc entry, matching no listed type, falls back to %a1%Y%u0. Attached files can be filed on demand into ~/Documents/Papers, named after their entry’s citation key (e.g. GoerzPRA2014.pdf); with file_automatically = true in [auto_file], every newly attached file would be filed that way immediately.

The import_bibtex() and add() methods first resolve a journal name against the @string macros already defined in the library itself (matched by value). Only publisher spelling variants that differ from a macro’s value in the library require a [journal_macros] entry: each list’s first name is the macro’s canonical value (matching the library), and the further names are alternative spellings that canonicalize to the same macro on import. The [initials.journal] entries pin the citation-key initials for the venues whose macro/abbreviation does not follow the first-letter acronym rule, and protected_words keeps the listed proper nouns and acronyms brace-protected in every imported title.