Update guide to include how to use type hints

[hCraker]

GeoCAT-comp has begun to use type hints for function arguments and return values. Since Python is not a strongly typed language, type hints ensure that a user passes in an argument of the correct type to a function. If a mistake is made, a clear error message is provided at runtime explaining what type was passed in and what type was expected. This can reduce time spent debugging for users.

Currently, the contributor's guide doesn't mention type hints, and purpose of this issue is to address that. Type hint usage and conventions can be added under section 5.3.3 Python Coding Conventions and Formatting of the contributor's guide.

[hCraker]

I now realize that I misunderstood how Python uses type hints. They do not impact anything at runtime like I once thought, but they are used by IDE's to help the developer. For instance, when a function is created with type hints and it is used elsewhere in the same file, PyCharm creates this handy popup for each argument with its associated type. I'm unsure how other IDEs and linters utilize type hints, but this can still be useful to have.

Example:

For more info on typing in Python https://docs.python.org/3/library/typing.html#

[erogluorhan]

This is a good catch! At this point, I'd suggest making a research to see if there is any practical ways of actually conducting runtime checks for argument types. If there is not, then forcing type hints may be discussed again, taking its limited help into account. Also, I think @anissa111 had some thoughts about type hints would change with a future Python version?

[hCraker]

This is a good catch! At this point, I'd suggest making a research to see if there is any practical ways of actually conducting runtime checks for argument types.

I have spent some time looking into this, and the Python developers have made it clear that they don't ever want to enforce typing. Doing so would remove the benefits of Python being dynamically typed (i.e. the flexibility of duck-typing).

I think the easiest way to enforce specific types for our functions would be to check the argument types at the start of the function and return reasonable error messages. This would be a courtesy to our users, and by no means is it currently required. However, it isn't a bad idea to do. My motivation for looking in to type hints was to avoid cryptic error messages when a function fails, and this alternative would accomplish that with a bit more code. I'm open to discussion about it.

Also, I think @anissa111 had some thoughts about type hints would change with a future Python version?

@anissa111 pointed out to me that there are some changes to how type hints are formatted in Python 10, but it appears to be backwards compatible syntax changes. See PEP 604 for more details.

[hCraker]

In our team meeting yesterday, we decided to not require type hints, and our stance on them is neutral. Because types are already listed in the required doc strings for each function, the addition of type hints would not add any information to our software. In addition, type hints do not have any influence at runtime and cannot throw errors when incorrect types are passed in. However, we recognize that they can be useful for developers using certain IDE's and type checkers. It is up to individual contributor's discretion whether or not to include type hints.