pythonarcade
Capturing typehinting guidance
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
Should there be a line after a class decleration(no docstrings) or not? I see both in the arcade code.
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)
