API discussion: keeping duplicated methods `xyz`/`xyz_async` vs having an async kwarg?
- 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
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