-
Notifications
You must be signed in to change notification settings - Fork 232
Description
Literal Types indicate a variable has a specific and concrete value. It was introduced in PEP 586 and is available since Python 3.8.
I'll take the pygmt.datasets.load_earth_relief
function as an example. Currently, the function definition is:
def load_earth_relief(
resolution="01d",
region=None,
registration=None,
data_source="igpp",
use_srtm=False,
)
in which, registration
can be gridline
, pixel
or None, and data_source
can be igpp
, gebco
, gebcosi
, synbath
.
To add Literal type hints for these two parameters, we need to change the function definition to:
from typing import Literal
def load_earth_relief(
resolution="01d",
region=None,
registration: Literal["gridline", "pixel", None] = None,
data_source: Literal["igpp", "gebco", "gebcosi", "synbath"] = "igpp",
use_srtm=False,
)
We also need to remove the "type" from the docstrings (e.g., changing registration : str
to registration
(see https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html).
After adding Literal type hints, most text editors and IDEs can provide better autocompletion for the valid values. For example (please ignore the incorrect registration="registration"
code in the demo below. It's caused by a typo):
autocompletion-valid-values.mov
TODO
Some notes:
- For each PR, we should work on a single parameter used by multiple functions (e.g., updating
registration
in allload_earth_xxx
functions), rather than working on multiple parameters in a single function (e.g., updatingregistration
anddata_source
in theload_earth_relief
function). I think it will make the review much easier. - Focus on parameters listed in function definitions (e.g.,
registration
inload_earth_relief
) rather than GMT's aliased parameters (e.g.,registration
inpygmt.xyz2grd
, which is aliased to the-r
option). Type hints for these aliased parameters need more discussions. - Some parameters may have a long list of valid values (e.g.,
load_earth_relief
'sresolution
parameter can have 15 valid values). Need to discuss if we should add such a long list Literal values.
Here is an incomplete list of parameters that we should add Literal type hints. **Please add your name to the end of the entry if you wan to work on it (in case you can edit this post) or just leave a comment so that we know you're working on it).
-
registration
in allload_earth_xxx
functions inpygmt/datasets/load_*.py
TYP: Add type hints for the 'registration' parameter in pygmt.datasets.load_* functions #2867 -
data_source
inload_earth_relief
andload_earth_magnetic_anomaly
TYP: Add type hints for 'data_source' in load_earth_relief and load_earth_magnetic_anomaly functions #2849 -
resolution
in allload_earth_xxx
functions (? The list of available resolutions is very long). -
load_sample_data
'sname
parameter (? More maintenance burden ) TYP: Add type hints support for pygmt.datasets.load_sample_data #2859 -
output_type
(valid values arefile
,numpy
andpandas
) in modules likegrdtrack
,grd2xyz
-
Figure.solar
'sterminator
parameter Figure.solar: Add type hints to the 'terminator' parameter and simplify codes #2881 - more to be added...