build_arg_string: Accept a dict containing configurable GMT parameters

[seisman]

Description of proposed changes

Fixes #2299

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 wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[willschlitzer]

Should there be a check on keys passed to confdict to make sure that they are correct configuration names? Something like:

pygmt_configs = ["COLOR_BACKGROUND", "COLOR_FOREGROUND",  "COLOR_CPT", "COLOR_NAN", "COLOR_MODEL"...]
for key in confdict:
    if key not in pygmt_configs:
        raise GMTInvalidInput(f"{key} not a valid PyGMT configuration key.")

[seisman]

Should there be a check on keys passed to confdict to make sure that they are correct configuration names? Something like:

pygmt_configs = ["COLOR_BACKGROUND", "COLOR_FOREGROUND",  "COLOR_CPT", "COLOR_NAN", "COLOR_MODEL"...]
for key in confdict:
    if key not in pygmt_configs:
        raise GMTInvalidInput(f"{key} not a valid PyGMT configuration key.")

I don't think it's necessary, because confdict is only used internally by developers (#2299 (comment)), and developers should be responsible for passing the correct configuration names.

[willschlitzer]

Should there be a check on keys passed to confdict to make sure that they are correct configuration names? Something like:

pygmt_configs = ["COLOR_BACKGROUND", "COLOR_FOREGROUND",  "COLOR_CPT", "COLOR_NAN", "COLOR_MODEL"...]
for key in confdict:
    if key not in pygmt_configs:
        raise GMTInvalidInput(f"{key} not a valid PyGMT configuration key.")

I don't think it's necessary, because confdict is only used internally by developers (#2299 (comment)), and developers should be responsible for passing the correct configuration names.

I don't think I understand; isn't the use of confdict to allow users to set GMT parameters more easily?

[seisman]

I don't think I understand; isn't the use of confdict to allow users to set GMT parameters more easily?

No, users should always use pygmt.config to set GMT parameters.

When I try to implement the Figure.timestamp() method (#2208), I need to pass some GMT parameters to the GMT C API, like:

    with Session() as lib:
        lib.call_module(
            module="plot",
            args=build_arg_string(kwdict)
            + f' --FONT_LOGO="{font}" --FORMAT_TIME_STAMP="{timefmt}"',
        )

I realize that using build_arg_string(kwdict) + f' --FONT_LOGO="{font}" --FORMAT_TIME_STAMP="{timefmt}"' is not convenient, so I propose to allow build_arg_string to accept configuration dicts. After this PR, the above code should be simplified to:

    with Session() as lib:
        lib.call_module(
            module="plot",
            args=build_arg_string(
                     kwdict, 
                     confdict={"FONT_LOGO": f"{font}", "FORMAT_TIME_STAMP": f"{timefmt}"},
            )
        )

[willschlitzer]

Okay, that makes sense.