astropy / astropy/astroquery

API discussion: keeping duplicated methods `xyz`/`xyz_async` vs having an async kwarg?

Open
#2,598 8 comments 0 reactions 0 assignees View on GitHub
needs-discussion
Dominant language
Python
Stars
791
Forks
451
Avg merge
1d 3h
Merged PRs (30d)
4

Description

While I was reviewing https://github.com/astropy/astroquery/pull/2597, I run into this quasi-dilemma, but I raise it as a separate question for @keflavich and @andamian, as well as @ceb8.

We have a lot of historical baggage around our API, and I would like to revisit some of it to see whether they still make sense, or we should slowly deprecate them out. At some point we need to switch versioning anyway, so one big breath and breaking API doesn't feel off the table.

So, the question for async and sync jobs: we traditionally have `method_async` and `method`, auto-generated with `async_to_sync`. But some modules don't follow this, and some modules manually have duplicated methods. So I wonder, now as we move on towards using proper VO tools, and pyvo, whether we want to revisit our API preferences, and would rather go with this kwarg-driven approach? Or the method duplication is better? (And frankly, it's baked into the API too much already that if it's the same, we could just stick with it).

I very much interested in the take from Adrian, whether it made any sense to you while redoing e.g. `alma`, or it was something to go along with?

Contributor guide

Open the contributing guide

Research direction

Start by reviewing PR #2597 and the existing `async_to_sync` pattern, then compare the `alma` example with modules that manually duplicate methods. Done requires a maintainer decision on duplicated `method`/`method_async` methods versus an async keyword, including how historical API compatibility and deprecation should be handled.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.