Use Mypy annotation for arguments and return type documentation

[rht]

With Mypy, the types can be checked explicitly. While I think in Sphinx, the types are just strings? (E.g. https://quanteconpy.readthedocs.io/en/latest/game_theory/repeated_game.html#quantecon.game_theory.repeated_game.RepeatedGame)

Sphinx can be configured to accept Mypy annotation: https://github.com/agronholm/sphinx-autodoc-typehints.

With Mypy, the type annotation would be:

class RepeatedGame:
    def __init__(self, stage_game: NormalFormGame, delta: float):
        ...
    def equilibrium_payoffs(
        self,
        method: Optional[str]=None,
        options: Optional[Dict[str, Any]]=None) -> None:
        ...

More example of Mypy annotations: https://github.com/projectmesa/mesa/blob/d376920146ca0ec422286cb8434d86b74e64b2fa/mesa/space.py. In particular https://github.com/projectmesa/mesa/blob/d376920146ca0ec422286cb8434d86b74e64b2fa/mesa/space.py#L191-L197.

[rht]

This is the classic blog post on Mypy (as the url says, 2016): https://blog.zulip.com/2016/10/13/static-types-in-python-oh-mypy/

Static type annotations improve readability. Improved readability is probably the most important benefit of statically typed Python. With static types, every function clearly documents the types of its arguments and return value, which saves a ton of time reading the codebase to figure out the precise types a function expects so that you can call it. ...

[mmcky]

thanks @rht I like this idea.

PR's are welcome.

[rht]

Also wanted to point out that with type annotations, it'd be more equivalent to the Julia version of this repo.

[jstac]

I fully agree, for all the reasons mentioned by @rht . The only thing is that it would have to be quite consistent across the lectures, and that's a large task requiring some coordination.

Unfortunately I don't have the bandwidth to implement this myself but further discussion leading to PRs is very welcome.

[rht]

I tried to annotate normal_form_game.py in #576.
An issue worth discussing is on how to make ndarray annotation to be type-specific. Currently, Numpy can't do this yet (see numpy/numpy#7370).

Current 3rd party alternative solutions: numpy/numpy#7370 (comment).
There is also https://github.com/ramonhagenaars/nptyping which is mentioned several times in the thread.