Skip to main content

Add articles from the new NASA/SAO ADS to your BibDeskbibliography (based on ads_bibdesk from J. Sick et al.).

Project description

ADS to BibDesk API edition (ads2bibdesk)

ads2bibdesk helps you add astrophysics articles listed on NASA/ADS to your BibDesk database using the new ADS Developer API.

The program is loosely based on the original ads_bibdesk from J. Sick et al. However, the query is handled with a python client for the ADS API (ads, maintained by A. Casey). Obsolete codes are replaced in favor of newer built-in Python modules with a simplified code structure. The MacOS workflow building process have been updated. The project packaging now follows the new PyPA guideline.

Due to the API usage, ads2bibdesk requires the user to specify a personal API key, per the new NASA/ADS policy. The instruction on how to obtain a key can be found on this official github repo: adsabs-dev-api. In short, to obtain access to the ADS Developer API, one must do two things:

The API key can be written into your ads2bibdesk preference file ~/.ads/ads2bibdesk.cfg (see the template). Following the Python/ads package’s instruction, one can also save the key to ~/.ads/dev_key or as an environment variable named ADS_DEV_KEY.



The command line script can be installed via:

python install --user     # from a local copy
pip install --user ads2bibdesk     # or, from PyPI
pip install --user -e .            # or, "Editable" install

To have the MacOS service (workflow) installed at the same time, run one of the following options instead:

python install --user --service                       # from a local copy
pip install --user --install-option="--service" ads2bibdesk    # from PyPI

The option “–service” will copy the optional MacOS workflow file Add to BibDesk.workflow to ~/Library/Services/, with an updated command-line script path specific for your installation.

Note: Only Python >=3.7 is supported (see below). If installing using the option “–user”, you must add the user-level bin directory (e.g., ~/Library/Python/3.X/bin) to your PATH environment variable in order to launch ads2bibdesk.


Add or update a new article from ADS:

ads2bibdesk "1807.04291"
ads2bibdesk "2018ApJ...864L..11X"
ads2bibdesk "2013ARA&A..51..105C"
ads2bibdesk "10.3847/2041-8213/aaf872"

ads2bibdesk accepts three kinds of article identifier at this moment

  • ADS bibcode (e.g. 1998ApJ...500..525S, 2019arXiv190404507R)
  • arXiv id (e.g. 0911.4956).
  • doi (e.g. 10.3847/1538-4357/aafd37)

A full summary of ads2bibdesk commands is available via:

ads2bibdesk --help

Compatibility and Dependency

I’ve only tested the program on the following MacOS setup:

  • MacOS (>=10.14)
  • Python (>=3.7.3)
  • BibDesk (>=1.7.1)

While the program likely works on slightly older software versions, I don’t focus on the backward compatibility. Considering that Python 2.7 will be deprecated at the end of 2019 and Python will not even be shipped with MacOS 10.15 (Catalina) by Apple (so the users can do whatever you want), the decision looks appropriate and will reduce the required maintenance/development efforts in longer-term. On my working machine (Mojave), I have Python 3.7 from MacPorts as default:

sudo port install python37 py37-pip py37-ipython
sudo port select python python37
sudo port select ipython py37-ipython
sudo port select pip pip37


The following functions have already been implemented in the package:

  • query the article metadata (title, abstract, BibTeX, etc.) with the new API by article identifiers (no more in-house ADS/arxiv HTML parsing functions)
  • download article PDFs using the ADS gateway links
  • use an authorized on-campus ssh proxy machine (with your public key) to download PDFs behind the journal paywall
  • add/update the BibDesk database and attach downloaded PDFs (largely borrowing the AppleScript method from the original ads_bibdesk)

Other changes from the original ads_bibdesk include:

  • clean up the dependency requirements (let do the check)
  • replace obsolete Python syntax/functions/modules with newer ones, e.g. optparser->argparser, f-string formatting, and use configparser()
  • The MacOS Automator workflow is running the installed console script rather than an embedded Python program

Some less-used features from the original ads_bibdesk are gone: notably, the “ingest” and “preprint-update” modes. But I plan to at least add back the “preprint-update” option, by scanning/updating article_bibcode associated with arXiv). My improvement proposal can be found here.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for ads2bibdesk, version 0.1.dev6
Filename, size File type Python version Upload date Hashes
Filename, size ads2bibdesk-0.1.dev6-py3-none-any.whl (23.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size ads2bibdesk-0.1.dev6.tar.gz (26.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page