astropy / astropy/astroquery

async_to_sync should find and replace sections anywhere in the docstring

Open
#2,664 0 comments 0 reactions 0 assignees View on GitHub
Documentation infrastructure
Dominant language
Python
Stars
791
Forks
451
Avg merge
1d 3h
Merged PRs (30d)
4

Description

While working on #2663, I discovered that `async_to_sync` and related decorators appear to assume that the `Returns` section is the last section in the docstring. However, if there are more sections than just `Parameters` and `Returns`, and one is following the [numpydoc standard](https://numpydoc.readthedocs.io/en/latest/format.html), then there is a good chance that `Returns` is *not* the last section.

#2598 suggests eliminating separate sync and async functions entirely, and that would certainly solve this issue too.

However if #2598 is not adopted, or if adoption takes a long time, then `async_to_sync` should be made more robust and be able to find the `Returns` section anywhere in the docstring.

Contributor guide

Open the contributing guide

Research direction

Locate the implementation of async_to_sync and its related decorators, then inspect how they identify the Returns section in a numpydoc-style docstring. Verify the behavior with a docstring containing sections after Returns; done means Returns is found and replaced wherever it appears without disrupting later sections.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.