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:

fromcollectionsimportUserDictfromcollections.abcimportSequencefrompygmt.aliasimportAliasclassAliasSystem(UserDict):
def__init__(self, **kwargs):
self.aliasdict=kwargskwdict= {}
foroption, aliasesinkwargs.items():
ifisinstance(aliases, Sequence):
values= [alias._valueforaliasinaliasesifalias._valueisnotNone]
ifvalues:
kwdict[option] ="".join(values)
elifaliases._valueisnotNone:
kwdict[option] =aliases._valuesuper().__init__(kwdict)
defupdate(self, kwargs):
print("Updating dict")
# Add more checks later.forshort_param, valueinkwargs.items():
self[short_param] =valuereturnselfaliasdict=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.

fromcollectionsimportUserDictalias=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!