Modify displayed call signature for astropy.coordinates frame classes?
- Dominant language
- Python
- Stars
- 5.3k
- Forks
- 2.2k
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 74
Description
### Description
*Note: This is a question meant to raise discussion, not really a feature request. I am also not strongly advocating for this, but interested to hear thoughts!*
The frame classes in `astropy.coordinates` accept a flexible set of input arguments, and the argument names depend on arguments that can be passed in (e.g., `representation_type` determines the coordinate component names that are allowed). The call signatures (both as displayed by `help()` and as implemented in code) therefore rely heavily on `*args` and `**kwargs`. For example, calling `help(coord.ICRS)` (or `coord.ICRS(`+TAB to pull up a docstring in IPython) outputs:
```ICRS(*args, copy=True, representation_type=None, differential_type=None, **kwargs)```
Since `__init_subclass__` was added in Python 3.6, we now have had the option of modifying the call signatures automatically for each class based on the default component names and frame attributes (which are defined at the class level for each of the frame classes). So, for example, the *code* could stay exactly as it is, but we could override the *displayed* call signature in `BaseCoordinateFrame.__init_subclass__` to reflect the default set of arguments that are accepted. So, for example, instead of the above for ICRS, it could *show* something like
```
ICRS(
ra,
dec,
distance=None,
pm_ra_cosdec=None,
pm_dec=None,
radial_velocity=None,
representation_type=None,
differential_type=None,
copy=True,
**kwargs,
)
```
The advantage here is that right now, users have to scroll down to the "Parameters" block to know what input is accepted - this would give them a quicker idea of the allowed arguments. The disadvantage would be, as I noted above, the input is actually quite a bit more flexible and the component names *depend on* other keyword arguments. So: Would this be a good idea? I am *slightly* in favor, because I do think it's better to show the default argument names instead of just *args, but not strongly in favor...
(This was on my mind because I just added something similar to my affiliated package Gala, e.g.,
https://github.com/adrn/gala/blob/main/gala/potential/common.py#L45)
cc @mhvk @eteq @astrojuanlu @StuartLittlefair
Contributor guide
Research direction
Start with BaseCoordinateFrame.__init_subclass__ and the frame classes in astropy.coordinates, then inspect how help(coord.ICRS) derives its signature. Compare the proposed displayed signature with the existing flexible *args and **kwargs behavior and the Gala example linked in the issue. Done would require an agreed design for whether and how signatures should be displayed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100