astropy / astroquery

Functions and classes to access online data resources. Maintainers: @keflavich and @bsipocz and @ceb8
http://astroquery.readthedocs.org/en/latest/
BSD 3-Clause "New" or "Revised" License
702 stars 396 forks source link

DOC: make signatures more explicit in MAST docstrings #2665

Open bsipocz opened 1 year ago

bsipocz commented 1 year ago

I think we can do better that *args and **kwargs for the Mast methods. E.g.

In [14]: MastMissions.query_region?
Signature: MastMissions.query_region(self, *args, **kwargs)
Docstring:
Queries the service and returns a table object.

Given a sky position and radius, returns a list of matching dataset IDs.

Parameters
----------
coordinates : str or `~astropy.coordinates` object
    The target around which to search. It may be specified as a
    string or as the appropriate `~astropy.coordinates` object.
radius : str or `~astropy.units.Quantity` object, optional
    Default 3 degrees.
    The string must be parsable by `~astropy.coordinates.Angle`. The
    appropriate `~astropy.units.Quantity` object from
    `~astropy.units` may also be used. Defaults to 3 arcminutes.
limit : int
    Optional and default is 5000.
    the maximun number of dataset IDs in the results.
offset : int
    Optional and default is 0
    the number of records you wish to skip before selecting records.
**kwargs
    Other mission-specific keyword args.
    Any invalid keys are ignored by the API.
    All valid key names can be found using `~astroquery.mast.missions.MastMissionsClass.get_column_list`
    function.
    For example one can specify the output columns(select_cols) or use other filters(conditions)

Returns
-------
table : A `~astropy.table.Table` object.

cc @jaymedina

nkphysics commented 1 year ago

Signatures for async functions seems to be a broader issue.

>>> from astroquery.vizier import Vizier
>>> import inspect
>>> print(inspect.signature(Vizier.query_constraints))
(self, *args, **kwargs)
>>> print(inspect.signature(Vizier.find_catalogs))
(keywords, *, include_obsolete=False, verbose=False, max_catalogs=None, return_type='votable')
>>> print(inspect.signature(Vizier.query_object))
(self, *args, **kwargs)
>>> print(inspect.signature(Vizier.query_region))
(self, *args, **kwargs)
bsipocz commented 1 year ago

Signatures for async functions seems to be a broader issue.

async functions are big issues on their own right 😅 , and should probably go for good for most of the classes. Some discussions are here: https://github.com/astropy/astroquery/issues/2598