Add pygmt.config() to change gmt defaults locally and globally

[seisman]

Description of proposed changes

Support changing gmt defaults globally and locally.

Usage:

pygmt.config(PARAMETER=value) # Global
# Locally set a value that will revert back to the default
with pygmt.config(PROJ_ELLIPSOID=value):
...
pygmt.whatever(...)

Fixes#288.

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

[leouieda]

@seisman Looking at the linter output, I hadn't remembered that set is a builtin class in Python. Redefining it can have consequences for the other functions in the module and elsewhere. We might have to change this name to avoid unintended behavior. I'm not sure what to do because we also don't want to completely change names used in GMT. Here are a few options:

1. Set (since it's a class, but it looks strange)
2. configure
3. set_parameter

I'm sure what the best option would be. I'm inclined toward pygmt.configure. Either way, we should tell pylint to stop complaining about lower case class names.

[seisman]

@leouieda What about pygmt.conf() or pygmt.config()? These two are also commonly used and are much shorter than pygmt.configure().

[leouieda]

Sure, pygmt.config is explicit enough 👍

[codecov]

Codecov Report

Merging #293 into master will increase coverage by 0.06%.
The diff coverage is 100%.

@@ Coverage Diff @@## master #293 +/- ##
=========================================
+ Coverage 96.74% 96.8% +0.06% 
=========================================
Files 18 18 Lines 768 783 +15 =========================================
+ Hits 743 758 +15 
Misses 25 25

Impacted Files	Coverage Δ
pygmt/modules.py	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5b8c659...24d4d90. Read the comment docs.

[weiji14]

Just following up on this from a recent gitter comment by @EqualMa. I've updated the branch to catch up with master, and have just looked into 2 of the errors:

1. It seems that the global config doesn't turn off after we run the test, so we'll probably need a way to reset configurations back to their default. (e.g. use gmtdefaults -D or gmtget)
2. I like the lowercase config name, but pylint doesn't like lowercase names for Python classes.

I've found Chainer's configuration settings to be a good reference. They avoid Capitalization of the name by creating a using_config function, and have that function return the Config class.

[tjcrone]

I've been testing pygmt.config() out locally and it appears to work. Does anyone know the status of this merge and what is left to do here? I would be happy to make a PR if there are specific issues that need to be addressed.

Without this merge, I was using gmt.conf for various settings, which does work, but as far as I can tell there is no way to get pygmt to reload gmt.conf without restarting the kernel and importing pygmt. Is there a way to get pygmt to reload the gmt.conf file without restarting the kernel? Thanks!

[weiji14]

Hi @tjcrone, functionality wise, this PR is basically done. We probably just need a minor fix that renames the class config to Config to satisfy the linter (and also change the tests to use capitalized Config). It would be nice to use lower case like in chainer here but I guess we could always wrap around that main class in a separate PR. Edit: I'll just ask pylint to ignore that one lowercase name 😄

Other than that, it would be nice to have some sort of gallery example or tutorial to highlight the use of pygmt.config. Would you like to contribute an example since you have more of a grasp on this?

[tjcrone]

@weiji14, I would be happy to add an example, which might go best in the user guide. It would be nice to see the docs rendered after this is merged so I can see what is needed. If this is merged will the docs render?

[weiji14]

@tjcrone, you can preview the docs by clicking on the "View deployment" button in any of our PRs (see #344 (comment)). Instructions for making a tutorial are at https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#tutorials, and you follow the instructions at https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md#documentation to build the documentation locally before you push up to Github. I'll merge this in first so that pip install https://github.com/GenericMappingTools/pygmt/archive/master.zip will include pygmt.config and you can create a new branch to work on the tutorial.