Disallow single character arguments

[leouieda]

Description of the desired feature

A major usability problem for GMT are the complex and cryptic single character arguments and modifiers. This is why we implemented the entire alias system in GMT/Python (which is making its way back into GMT 6). Our docs all encourage using the long form names and this is not strange in the Python ecosystem. Since we're actively discouraging the use of B and the like, why are we maintaining the capability of doing so? Hardcore GMT users who value brevity are not our target audience. And if you're using Jupyter or any modern text editor, tab completion eliminates the hassle of longer names (which we currently can't use because of the alias system).

I propose getting rid of the single letter arguments all together.

Doing this will allow us to:

• Define functions arguments normally in the Python functions instead of relying on **kwargs.
• Get rid of the use_alias decorator and replace it with a translator function that's called inside the function body. This functions would be a lot easier than the decorator to maintain (which is an ugly function inside a function inside a function).
• Use tab completion for the long argument names
• Simplify the testing a lot but not needing to test the aliases

The one downside I see that we will have to fully implement all arguments in order for them to be used (like X and Y, etc). But we were gonna have to do this eventually any way.

I'd love to get some feedback on this.

[leouieda]

Pinging @GenericMappingTools/gmt-python @liamtoney @weiji14 @akshmakov @mjziebarth

[seisman]

GMT is trying to implement long-form options, see GenericMappingTools/gmt#230.

If it's merged, we no longer need use_alias anymore.

[leouieda]

Yep. We'll still need to parse and do some conversion on the arguments, though.

[liamtoney]

What would be the Pythonic implementation of the numerous modifiers that follow option arguments, i.e. the Python version of

--longoption[=[<directive>:]<arg>][+<mod1[=<arg1>]][+<mod2[=<arg2>]]...

as given in GenericMappingTools/gmt#230?

The more complex cases could be tricky — and they do come up. For example, I recently wrote something like the following to produce a frame overlay with map scale:

fig.basemap(frame='af', L='g{0}/{1}+w100k+c{0}/{1}+l'.format(*SCALE_LOC))

I guess when I think of an optimal solution as an end user, dictionaries of modifiers come to mind (see the docs for the option):

fig.basemap(frame='af', scale=dict(
  				   location_type='g',
                                   location=SCALE_LOC,
                                   length=100,
                                   unit='k',
                                   reference_coordinates=SCALE_LOC,
                                   label=True
                                   )

Wrapping would take some time, though...

[leouieda]

@liamtoney that's a good point but it's probably better discussed in a separate issue. We don't have a good answer for that yet. In Julia, @joa-quim is doing something similar to what you suggest. The only problem with that implementation on the Python side is that editors won't be able to tab complete the arguments. This is a bit of a deal breaker for me since it becomes really annoying to type out long names.

A lot of these problems arise from a single argument/module trying to do many different jobs at once. Ideally, we should try to split these up into separate arguments or functions. But it's not trivial where the line needs to be drawn.

I don't think we'll be able to think of every single possibility. The best option is probably to implement the basics with the top-level arguments first. I find that a lot of these usability problems will come up as we write the documentation and often times a better solution presents itself. I'm working on expanding the docs with some tutorials and examples for this reason.

[mjziebarth]

Good idea!

@liamtoney @leouieda Regarding the dict of keywords a small issue highjacking: If classes are autocomplete friendly (I must admit I work using simple text editors), one could also do something like

fig.basemap(frame='af', scale=Scale(location_type='g', location=SCALE_LOC, ...))

That would surely take a lot of work setting up but may be helpful.

[leouieda]

@mjziebarth that was my initial idea but I'd be more prone to using a function instead of a class. The only thing needed is to convert the arguments into a GMT-compatible string, so a class wouldn't really do much besides store the values and define a __str__ method that does the conversion. The benefit of the class is that the documentation might be more straight-forward (the required value of scale would be either a string or a Scale instance). Another advantage is that we can add them as needed and still allow the normal string input. The only problem with this is that it's kind of unnatural to require these objects. But I don't see a good way around it without completely changing the GMT way of doing things.