GenericMappingTools / GenericMappingTools/pygmt

Let PyGMT functions support tab autocompletion

Open
#1,203 11 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
874
Forks
255
Avg merge
1d 21h
Merged PRs (30d)
40

Description

Jupyter and most modern text editors support tab autocompletion, which is useful for typing long function and parameter names. However, currently, most PyGMT functions don't support tab autocompletion, since we use the alias system (`use_alias`), `*args`, and `**kwargs`. The only way I know to enable tab autocompletion is using normal Python parameters instead of relying on the `**kwargs` and `use_alias` decorator (see #262 for the original issue).

The solution seems straightforward. For example, for the [`pygmt.info()`](https://github.com/GenericMappingTools/pygmt/blob/master/pygmt/src/info.py) function, the current function is defined as:
```python
@fmt_docstring
@use_alias(
C="per_column",
I="spacing",
T="nearest_multiple",
V="verbose",
a="aspatial",
f="coltypes",
r="registration",
)
@kwargs_to_strings(I="sequence")
def info(table, **kwargs):
```

To make it support tab autocompletion, we just need to change the `def info()` part:
```python
@fmt_docstring
@use_alias(
C="per_column",
I="spacing",
T="nearest_multiple",
V="verbose",
a="aspatial",
f="coltypes",
r="registration",
)
@kwargs_to_strings(I="sequence")
def info(
table,
per_column=False,
spacing=None,
nearest_multiple=None,
verbose=None,
aspatial=None,
coltypes=None,
registration=None,
**kwargs
):
```
Since all parameters are defined as normal Python parameters, tab autocompletion should work. The new function definition still keeps the `**kwargs` parameter, so that single-letter options are still supported (but we are likely to disallow single-letter options in future releases, see #262). Thus, this would be **backward compatible**, and is the first step to address #262.

The screenshots below show how the autocompletion work after applying the changes in PR #1202:

| Current `pygmt.info()` | Updated `pygmt.info()` |
|---|---|
| ![image](https://user-images.githubusercontent.com/3974108/114293337-454c4c00-9a63-11eb-840d-104fbfd3ef4d.png) | ![image](https://user-images.githubusercontent.com/3974108/114293309-0c13dc00-9a63-11eb-8633-aa18165f3747.png) |
| ![image](https://user-images.githubusercontent.com/3974108/114293345-4da48700-9a63-11eb-9123-b6c16cf1a1a6.png) | ![image](https://user-images.githubusercontent.com/3974108/114293317-1504ad80-9a63-11eb-94b4-4879ca6ebb9e.png) |

Please give #1202 a try and leave your thoughts.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.