Great work! For me, it works well in IPython console, Jupyter notebook, but not in VSCode.

I learned that parameter order matters for tab completion when trying this out. For example, I can tab complete each parameter in this use of basemap:

import pygmt
fig = pygmt.Figure()
fig.basemap(region=[-180,180,-80,80],projection="M6i",frame=True)

but cannot tab complete region if I select the projection parameter first:

import pygmt
fig = pygmt.Figure()
fig.basemap(projection="M6i",region=[-180,180,-80,80],frame=True)

It seems like this is the same for other libraries in Jupyter notebooks (e.g., numpy), so I am not sure if there is a way around this but will look into it more. If not, it motivates ordering the aliases in some way that reflects a likely usage order as much as possible.

I learned that parameter order matters for tab completion when trying this out. For example, I can tab complete each parameter in this use of basemap:

import pygmt
fig = pygmt.Figure()
fig.basemap(region=[-180,180,-80,80],projection="M6i",frame=True)

but cannot tab complete region if I select the projection parameter first:

import pygmt
fig = pygmt.Figure()
fig.basemap(projection="M6i",region=[-180,180,-80,80],frame=True)

It seems like this is the same for other libraries in Jupyter notebooks (e.g., numpy), so I am not sure if there is a way around this but will look into it more. If not, it motivates ordering the aliases in some way that reflects a likely usage order as much as possible.

Is it related to the Parameter.POSITIONAL_OR_KEYWORD setting?

Is it related to the Parameter.POSITIONAL_OR_KEYWORD setting?

Yes, thanks. I went with the default setting of POSITIONAL_OR_KEYWORD, but we could support position independent tab completion by using KEYWORD_ONLY.

Actually, it might be worth considering setting other parameters to KEYWORD_ONLY. For example, I think all the parameters in pygmt.Figure.text are the default of POSITIONAL_OR_KEYWORD:

def text_(
    self,
    textfiles=None,
    x=None,
    y=None,
    position=None,
    text=None,
    angle=None,
    font=None,
    justify=None,
    **kwargs,
):

But KEYWORD_ONLY would be more appropriate for most because textfiles cannot be provided along with x and y so we do not really support positional arguments here:

def text_(
self,
textfiles=None,
*,
x=None,
y=None,
position=None,
text=None,
angle=None,
font=None,
justify=None,
**kwargs,
):

Or similarly only supporting keyword arguments for data onward for plot since x,y, anddata are not supported together:
def plot(self, x=None, y=None, *, data=None, size=None, direction=None, **kwargs):
Tab completion does seem to work for plot independent of parameter order, so I guess the only real benefit here is being more explicit about what is expected.

One weakness to the current implementation is that all parameters defined by use_alias that are not already in the method signature are given a default value of None, but I think that required parameters (e.g, blockmean spacing and grdfill mode) should not have a default value.

One weakness to the current implementation is that all parameters defined by use_alias that are not already in the method signature are given a default value of None, but I think that required parameters (e.g, blockmean spacing and grdfill mode) should not have a default value.

But any parameter with a value of None will disappear after being parsed by build_arg_str right? See also #639. So it should technically be ok to have a default None value?

One weakness to the current implementation is that all parameters defined by use_alias that are not already in the method signature are given a default value of None, but I think that required parameters (e.g, blockmean spacing and grdfill mode) should not have a default value.

But any parameter with a value of None will disappear after being parsed by build_arg_str right? See also #639. So it should technically be ok to have a default None value?

You are correct. I had thought that required arguments should not have a default None value from a readability standpoint, in that parameter=None implies an optional argument. But I cannot find a source for that opinion.

Made a small change to the title to clarify that tab completion only works on Jupyter (and IPython too, but that's implied). Feel free to squash and merge this in whenever @meghanrjones.