New Alias System: Add the AliasSystem class

[seisman]

This PR implements the AliasSystem class for the new alias system proposed in #3239.

As mentioned in #3239, the new alias system has the following pros and cons:

pros:

• The new and old alias systems can coexist, so we don't have to migrate all wrappers in a single PR.
• Allow building a GMT option from multiple PyGMT parameters (More Pythonic)
• No abuse of kwargs anymore
• Access the original argument by parameter name, not by dict lookup like kwargs.get("S") (Maybe faster)
• Autocompletion of all function parameters after Refactor the function definitions to better support type hints and auto-completion #2896.
• Autocompletion for long-form arguments if we add type hints.
• Backward compatible with single-letter parameters Disallow single character arguments #262

Cons:

• Big refactors may introduce new bugs. [We can always fix them if any.]
• The placeholder {aliases} in docstrings is not supported in the new alias system, since we can't access the local variables in a decorator. So we need to manually edit the {aliases} in docstrings.

[seisman]

Changes in basemap.py is only meant for proof of concept. I plan to revert the changes in basemap.py and open separate PRs for it.

[Copilot]

Pull Request Overview

This PR implements the AliasSystem class to provide a new alias system that can coexist with the existing system, enabling more Pythonic parameter handling by building GMT options from multiple PyGMT parameters without abusing kwargs.

Key changes:

• Implements the AliasSystem class with validation for short/long-form parameter conflicts
• Adds comprehensive test coverage for the new alias system functionality
• Updates the basemap function to demonstrate usage of the new alias system

Reviewed Changes

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

File	Description
pygmt/alias.py	Implements the core AliasSystem class with parameter conflict detection and warnings
pygmt/tests/test_alias_system.py	Adds comprehensive tests for long-form, short-form, and conflict scenarios
pygmt/src/basemap.py	Updates basemap function to use the new alias system for region, projection, and frame parameters

[seisman]

Actually, I'm still debating if we should change these lines to:

Suggested change

	alias = AliasSystem(
	R=Alias(region, name="region", separator="/", size=[4, 6]),
	J=Alias(projection, name="projection"),
	B=Alias(frame, name="frame"),
	).update(kwargs)
	kwdict = AliasSystem(
	R=Alias(region, name="region", separator="/", size=[4, 6]),
	J=Alias(projection, name="projection"),
	B=Alias(frame, name="frame"),
	).update(kwargs).kwdict

since only alias.kwdict is used below.

[weiji14]

I did wonder if we could turn the AliasSystem class into a subclass of collections.UserDict or collections.OrderedDict (or maybe collections.ChainMap?), since it is essentially just holding a dictonary with a custom update method. But then you'll need to reconcile self.aliasdict with self.kwdict.

[seisman]

I did wonder if we could turn the AliasSystem class into a subclass of collections.UserDict or collections.OrderedDict (or maybe collections.ChainMap?), since it is essentially just holding a dictonary with a custom update method.

Then we will have codes like

alias = AliasSystem(A=Alias(...), B=Alias(...), ...)
build_arg_list(alias)

or rename alias to kwdict, but both may be confusing.

[weiji14]

or rename alias to kwdict, but both may be confusing.

how about aliasdict = AliasSystem(...)?

[seisman]

aliasdict looks good.

I just tried UserDict and it looks good. Here is a minimal example:

from collections import UserDict
from collections.abc import Sequence
from pygmt.alias import Alias

class AliasSystem(UserDict):

    def __init__(self, **kwargs):
        self.aliasdict = kwargs

        kwdict = {}
        for option, aliases in kwargs.items():
            if isinstance(aliases, Sequence):
                values = [alias._value for alias in aliases if alias._value is not None]
                if values:
                    kwdict[option] = "".join(values)
            elif aliases._value is not None:
                kwdict[option] = aliases._value
        super().__init__(kwdict)

    def update(self, kwargs):
        print("Updating dict")
        # Add more checks later.
        for short_param, value in kwargs.items():
            self[short_param] = value
        return self

aliasdict = AliasSystem(
    A=Alias("label"),
    B=Alias((0, 10), separator="/"),
    C=[Alias("text"), Alias("TL", prefix="+j")]
).update({"C": "abc"})
print(aliasdict)

The script output is:

Updating dict
Updating dict
{'A': 'label', 'B': '0/10', 'C': 'abc'}

As you can see, it prints Updating dict twice. One is by the super().__init__ call, another by the AliasSystem().update call. Since update is a built-in method of dict/UserDict, overriding it is not a good idea. I guess we need to change the method name from update() to something like merge()/check()?

[seisman]

I've updated the AliasSystem class using UserDict in 99845c2.

[weiji14]

Should't this be overriding the UserDict's data attribute? https://docs.python.org/3/library/collections.html#collections.UserDict.data

Suggested change

	self.aliasdict = kwargs
	self.data = kwargs

Then I suppose you can use update as method name? Unless it's still not advised to override that.

[seisman]

data is the real dictionary that stores the contents of the UserDict class, so changing the UserDict object also affects data.

from collections import UserDict

alias = UserDict(A="label", B="text")
print(alias.data)
print(alias)

alias.data = {"C": True}
print(alias.data)
print(alias)

alias.update({"D": "good"})
print(alias.data)
print(alias)

The output is:

{'A': 'label', 'B': 'text'}
{'A': 'label', 'B': 'text'}
{'C': True}
{'C': True}
{'C': True, 'D': 'good'}
{'C': True, 'D': 'good'}

[weiji14]

Don't want to hold this up since I'll be busy over the next few weeks (conference + workshops), so I think ok to merge this so the work on the new Alias system can advance. Thanks again @seisman!