Support Type Hints

[seisman]

This issue is still in draft mode. Type hints are something new to me, so I need to learn more and will keep improving the issue description.

What's Python's Type Hints

• A short introduction: https://vegibit.com/introduction-to-python-type-hints/

Why we should support type hints

Copied from https://vegibit.com/introduction-to-python-type-hints/.

• Improved code readability: Type hints make it easier for other developers to understand your code. By clearly specifying the types of arguments and return values, you can help others quickly grasp the intent of your code.
• Improved development speed: With type hints, you can catch potential bugs and errors early in the development process. This can save you time in the long run, as you can fix errors before they cause problems in your code.
• Improved tooling support: Many tools, such as static analyzers and IDEs, use type hints to provide better support for your code. For example, they can use type hints to catch potential errors, suggest code improvements, or provide better autocompletion.
• Better auto-completion for parameter values: See #2793 for how Type Hints can affect the way we use PyGMT.

Tasks

• [x] Use Mypy for static type checking #2808
• [x] #2812
• [ ] Enable ruff's ANN rules to make sure all parameters are annotated? [Maybe it's unnecessary, because mypy has a strict mode]

References:

• https://docs.python.org/3/library/typing.html [TL;DR]
• https://typing.readthedocs.io/en/latest/source/libraries.html
• https://typing.readthedocs.io/en/latest/source/best_practices.html
• https://www.pythonlikeyoumeanit.com/Module5_OddsAndEnds/Writing_Good_Code.html#Type-Hinting

Related PEPs

• PEP 563: https://peps.python.org/pep-0563/
• PEP 484: https://peps.python.org/pep-0484/
• PEP 585: https://peps.python.org/pep-0585/
• PEP 604: https://peps.python.org/pep-0604/

[weiji14]

Personally I do use type hints (and tried to add it to pygmt.grdtrack in 2019 apparently - https://github.com/GenericMappingTools/pygmt/pull/308#discussion_r287089810), but it can be a lot of work to add them across the whole project (and a bit tough for new contributors to learn).

Maybe we can start small with just typing.Literal since that's a practical one for when there's a choice of str type arguments, e.g. load_earth_relief(..., data_source: Literal["igpp", "gebco", "gebcosi", "synbath"], ...) in #2793? Other types like bool/int/float don't offer any autocomplete so may be less useful for now.

[seisman]

Yes, it's definitely a lot of work and a long-term goal. We need to split it into multiple smaller jobs so that people can help.

[willschlitzer]

Maybe we can start small with just typing.Literal since that's a practical one for when there's a choice of str type arguments, e.g. load_earth_relief(..., data_source: Literal["igpp", "gebco", "gebcosi", "synbath"], ...) in #2793? Other types like bool/int/float don't offer any autocomplete so may be less useful for now.

I think specifying literal argument options is a good start.