Capturing typehinting guidance

[cspotcode]

This issue serves as a living document describing how we use typehints.

Note: at the time of writing, some of the following is forward-thinking. It describes things that will be true in the near future.

Summary

We typecheck arcade's own codebase with pyright, not mypy. However, we support consumers of arcade who might use mypy on their projects.

Guidelines

Consult pyright's guidance

There are a ton of goodies in this doc.

https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md

Annotate with type hints, do not put type information into docstrings

The Sphinx documentation generator can be configured to parse typehints so that the type information does not need to be repeated within docstrings.

Annotate __init__ with -> None

https://stackoverflow.com/questions/46779046/correct-type-annotation-for-init

Errors where something is typed Optional but can't be None in a given code path

Our pyright configuration suppresses a bunch of Optional errors, but not all of them. If the typechecker complains that something might be None:

A) it really might be None

Do a runtime check and raise a descriptive exception.

if thing_that_cannot_be_none is None:
    raise Exception("Description here")

B) it's guaranteed never to be None, but the typechecker doesn't understand

if TYPE_CHECKING:
    assert thing_that_cannot_be_none

[gran4]

Should there be a line after a class decleration(no docstrings) or not? I see both in the arcade code.

[pushfoo]

Should there be a line after a class decleration(no docstrings) or not? I see both in the arcade code.

For arcade, I've steered toward putting the summary line on a new line, like this:

def func_name(value: int):
    """
    An example summary line on its own line.

    Additional function details.

    :param value: some value the function will use
    """
    print(value)

[einarf]

Linked in CONTRIBUTING.md