Type Hints and MyPy

[sanders41]

Would there be any interest in adding type hints to this project and also mypy for static type checking? I find it nice both as a developer and as an end user to work with packages that have type hints because code editors such as VS Code and PyCharm understand them and will show the expected types. In addition it allows static type checking with mypy to catch errors/potential errors before they happen at runtime.

As an example of where this would help is mypy would have pointed out the issue I mentioned in #263 where the variables set to None where not handled and would raise exceptions.

Another area I know mypy will point out is in the Client and Index values received from HttpRequests are a always returned as if the expected type is received back, but the expected return types from HttpRequests can be a dictionary, a list of dictionaries, or a requests.Response object. As an example search in the Index expects the value it receives from HttpRequests to always be a dictionary and returns this making the assumption it can never be anything else. In these cases mypy would make you be explicit with what you want to do if the expected type won't be returned (i.e. you could raise an exception).

The type hint/mypy combo is also useful for documentation. Currently the types for the parameters and return type are documented in the doc strings. It is easy to forget to update these when changes are made so the wrong types are listed. The method/function signatures self document the types when type hints are used and mypy tests that they are correct so they are no longer needed in the doc strings, and are always tested to be correct.

If you all don't think this would be helpful no problem at all for me, just a suggestion.

[bidoubiwa]

I'm all for types. They are really great for both what you said, type hinting in IDE's and preventing problems before they happen. Except adding types directly into the code like this:

def greeting(name: str) -> str:
    return 'Hello ' + name

Is there something else we have to do?

[sanders41]

There are a few extra steps. You need to add py.typed file, it's just an empty file, and include that in the setup.py. This file lets editors and other packages know that types are available.

The other thing would be adding mypy as a dev dependency. Then mypy can be run both locally and in CI for static type checking. After adding mypy there would be some refactoring needed because I know there are areas in the code that it is going to have errors on. It's places where we as developers have made assumptions about what types we are going to receive and return, but mypy won't allow the assumptions.

[bidoubiwa]

Very interesting. It would be a great addition!