Improve decorators @use_alias/@fmt_docstrings to list non-aliased aliases

[seisman]

This is another approach to addressing the 2nd issue raised in #3881.

This PR improves the @use_alias decorator to support non-aliased aliases. Here, non-aliased aliases are marked by a trailing dash, e.g., D="resolution" vs D="resolution-".

Non-aliased aliases mean that the alias will be shown in the alias list, but the long-form parameters won't be converted to short-form flags, so that we can still use resolution rather than kwargs["D"] in the codes.

Please note that this is just a temporary fix, and we need to find a different way to list aliases when we start to remove @use_alias.

Supersedes #3945.

Preview: https://pygmt-dev--3965.org.readthedocs.build/en/3965/api/generated/pygmt.grdfill.html

[Copilot]

Pull Request Overview

This PR improves the @use_alias and @fmt_docstring decorators to support non-aliased aliases by marking them with a trailing dash. Key changes include:

• Adding non-aliased alias support across several modules (wiggle, ternary, solar, etc.).
• Updating the alias processing logic in the decorators to strip trailing dashes.
• Enhancing error handling and warnings when both short-form and long-form parameters are provided.

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pygmt/src/wiggle.py	Updated alias for parameter G to include non-aliased alias support with a trailing dash.
pygmt/src/ternary.py	Added a new non-aliased alias for parameter L.
pygmt/src/solar.py	Introduced a non-aliased alias for parameter T.
pygmt/src/select.py	Updated the alias for parameter D to be non-aliased.
pygmt/src/grdlandmask.py	Changed alias for parameter D to non-aliased format.
pygmt/src/grdfill.py	Added compound aliases for parameter A and introduced a non-aliased alias for L.
pygmt/src/grdclip.py	Refactored aliases to use non-aliased markers for several parameters.
pygmt/src/coast.py	Updated alias for parameter D to be non-aliased.
pygmt/helpers/decorators.py	Modified alias processing to strip trailing dashes when listing non-aliased aliases and skip them for alias replacement.

Comments suppressed due to low confidence (2)

pygmt/helpers/decorators.py:453

• [nitpick] Consider clarifying in the comment how compound alias strings (e.g., those containing '/') are handled when only part of the alias includes a trailing dash, ensuring that users understand the intended behavior.

# Trailing dash means it's not aliased but should be listed.

pygmt/src/grdfill.py:113

• [nitpick] It would be helpful to document the intended behavior for this compound alias, explaining how each part of the alias is interpreted, particularly how the trailing dash affects only certain parts of the alias.

A="constantfill/gridfill/neighborfill/splinefill/mode-",

[weiji14]

Should there be some extra logic in case someone uses a short alias with a long alias that has '-' at the end? E.g. this doesn't error:

from pygmt import Figure

fig = Figure()
fig.coast(
    region=[-180, 180, -80, 80],
    projection="M15c",
    frame="af",
    land="#aaaaaa",
    resolution="crude",
    D="high",  # duplicate resolution/D
    water="white",
)

In this case, resolution="crude" will be used instead of D="high", but maybe best if an error is raised instead of passing silently.

[seisman]

In a4f8779 I have added codes to raise an erorr if a short-form parameter is used, but it also means single-letter alias is no longer supported for these parameters.

In [1]: from pygmt import Figure
   ...: 
   ...: fig = Figure()
   ...: fig.coast(
   ...:     region=[-180, 180, -80, 80],
   ...:     projection="M15c",
   ...:     frame="af",
   ...:     land="#aaaaaa",
   ...:     resolution="crude",
   ...:     D="high",  # duplicate resolution/D
   ...:     water="white",
   ...: )
---------------------------------------------------------------------------
GMTInvalidInput                           Traceback (most recent call last)
Cell In[1], line 4
      1 from pygmt import Figure
      3 fig = Figure()
----> 4 fig.coast(
      5     region=[-180, 180, -80, 80],
      6     projection="M15c",
      7     frame="af",
      8     land="#aaaaaa",
      9     resolution="crude",
     10     D="high",  # duplicate resolution/D
     11     water="white",
     12 )

File ~/OSS/gmt/pygmt/pygmt/helpers/decorators.py:564, in use_alias.<locals>.alias_decorator.<locals>.new_module(*args, **kwargs)
    558     if short_param in kwargs:
    559         msg = (
    560             f"Short-form parameter ({short_param}) is not recognized. "
    561             f"Use long-form parameter(s) '{long_alias.strip('-')}' "
    562             "instead."
    563         )
--> 564         raise GMTInvalidInput(msg)
    565     continue
    567 if long_alias in kwargs and short_param in kwargs:

GMTInvalidInput: Short-form parameter (D) is not recognized. Use long-form parameter(s) 'resolution' instead.

In [2]: from pygmt import Figure
   ...: 
   ...: fig = Figure()
   ...: fig.coast(
   ...:     region=[-180, 180, -80, 80],
   ...:     projection="M15c",
   ...:     frame="af",
   ...:     land="#aaaaaa",
   ...:     #resolution="crude",
   ...:     D="high",  # duplicate resolution/D
   ...:     water="white",
   ...: )
---------------------------------------------------------------------------
GMTInvalidInput                           Traceback (most recent call last)
Cell In[2], line 4
      1 from pygmt import Figure
      3 fig = Figure()
----> 4 fig.coast(
      5     region=[-180, 180, -80, 80],
      6     projection="M15c",
      7     frame="af",
      8     land="#aaaaaa",
      9     #resolution="crude",
     10     D="high",  # duplicate resolution/D
     11     water="white",
     12 )

File ~/OSS/gmt/pygmt/pygmt/helpers/decorators.py:564, in use_alias.<locals>.alias_decorator.<locals>.new_module(*args, **kwargs)
    558     if short_param in kwargs:
    559         msg = (
    560             f"Short-form parameter ({short_param}) is not recognized. "
    561             f"Use long-form parameter(s) '{long_alias.strip('-')}' "
    562             "instead."
    563         )
--> 564         raise GMTInvalidInput(msg)
    565     continue
    567 if long_alias in kwargs and short_param in kwargs:

GMTInvalidInput: Short-form parameter (D) is not recognized. Use long-form parameter(s) 'resolution' instead.

[weiji14]

but it also means single-letter alias is no longer supported for these parameters.

Hmm, that's not ideal. Not sure if we want to slowly implement #262, given that most of the comments seem to be on keeping the single-letter options. Is there a way to refactor the logic to still allow single-letter parameters?

[seisman]

After 4dafc57, the current behavior is:

• Raise an error if both long and short parameters are given
• Raise an error if short parameter is given but it's aliased to multiple parameter. For example, in grdfill, -A is aliased to constantfill/gridfill/neighborfill/splinefill/mode. In the current situation, kwargs["A"] is always set with

    kwargs["A"] = (
        _parse_fill_mode(constantfill, gridfill, neighborfill, splinefill)
        if mode is None
        else mode
    )

we may have a better solution after #3239.

• If short parameter is given and it's aliased to one long-form parameter, e.g., -D is aliased to resolution in coast, the value of the short parameter will be used