andycasey
New release
This hasn't been broadly advertised, but nearly five years ago I started writing an updated version of this package that has a very different user-facing API. It's remained in the v1 branch of this repository and has mostly complete documentation here: https://ads.readthedocs.io/en/v1/index.html#
There are major technical changes with how this new version works. In short, it uses an Object Relational Mapper (peewee) to build queries. There are data models that can be used to remotely query documents, libraries, and local data models that can be seamlessly joined so that you can query on affiliation, country, and other things. That lets you build very complicated queries with ease, but would be impractical for anyone to write themselves.
peewee is usually used for mapping to relational databases (hence the ORM acronym), but NASA/ADS uses Solr, which is actually a non-relational database. That means there is some effort to abstract the peewee-style queries and translate them into Solr, and for managing the remote-to-local type joins between remote data models (Document, Library) and local ones (Journal, Affiliation). Most of that has worked for years, but I have dithered for a long time about whether this was a good idea in practice.
As it turns out, I haven't used the original ADS Python interface since creating this ORM-style version. The new style is cleaner, faster, easier to work with, allows for clever asynchronous queries, and it has way more functionality. It also allows me to include some data-type checking to enforce that the results you get back from ADS have a consistent data type and meaning. For example, None, '-', and ['-'] and '' might all be valid responses from ADS for a missing text field. And that's OK, real data are messy! But doing a little bit of middle-layer work to ensure consistent data types for each field is probably something that users would love once they know they don't have to do their own kind of data-type checking.
I thought I'd post this issue just to signpost to anyone who follows this repository, that there is a different version coming that will have a new API, and there is already extensive documentation already at https://ads.readthedocs.io/en/v1/index.html, so feel free to check it out and announce your thoughts! Things are not complete, and there will be bugs, but I will be assigning time to work on this during 2025.
And to allay any concerns: the existing interface will continue to work just fine. I am too afraid of removing that interface just because it'd make so many astronomers angry!
