clib.Session: Refactor the __getitem__ special method to avoid calling API function GMT_Get_Enum repeatedly

[seisman]

The __getitem__ method is a magic method that makes the Session class behave like a dictionary so that we can access the value of GMT constants like self["GMT_IS_DATASET"]. self["GMT_IS_DATSET"] is translated to the statement self.__get_item__("GMT_IS_DATASET"), which then calls the GMT C API function GMT_Get_Enum.

Currently, the __getitem__ method calls the GMT_Get_Enum function everytime a constant is accessed, so it's not efficient. To check how many times constants are accessed, I've added a print statement in the __getitem__ method.

In [1]: import pygmt
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL

In [2]: fig = pygmt.Figure()
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL

In [3]: fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL

In [4]: fig.show()
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL
__getitem__ GMT_PAD_DEFAULT
__getitem__ GMT_SESSION_EXTERNAL

As you can see, even in the simplest script, GMT_PAD_DEFAULT and GMT_SESSION_EXTERNAL are called 7 times each.

This PR refactors the __getitem__ method by storing the values of GMT constants in the GMT_CONSTANTS dictionary. When a constant is accessed for the first time, GMT_Get_Enum is called to the get its value and the value is stored in GMT_CONSTANTS. When the constant is accessed later, it will get the value from the GMT_CONSTANTS dictionary directly.

Below is a simple benchmark showing the performance improvement.

Main branch:

In [1]: from pygmt.clib import Session

In [2]: with Session() as lib:
   ...:     %timeit lib["GMT_IS_FILE"]
   ...:
848 ns ± 2.14 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

This branch:

In [1]: from pygmt.clib import Session

In [2]: with Session() as lib:
   ...:     %timeit lib["GMT_IS_FILE"]
   ...:
66 ns ± 0.0665 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)

From the benchmark result, we can conclude that:

• Accessing a constant for the first time takes about 850 ns
• Accessing the same constant from the GMT_CONSTANTS dictionary takes about 66 ns, which is 10x faster

This PR doesn't affect our "Benchmarks" workflow, because in our tests, __get_item__ is usually called a few times (like 10), so the execution time may decrease by only 10 ms, which has minor effects on the "Benchmarks" results.