Add type annotations everywhere

[Kwpolska]

It turns out dynamic typing is a bad idea for writing serious software, as it’s trivial to introduce bugs that would make code simply fail to compile in statically typed languages (e.g. #3737). The JS community has TypeScript, and Python has mypy and the typing library in the stdlib. Nikola was started before mypy and attrs/dataclasses became a thing. The coding style is more laissez-faire, with ad-hoc tuples and other things that aren’t neatly structured. There are a few places that are newer that use typing or dataclasses.

What should be done?

• Add type annotations to all functions, methods, and class attributes; variable annotations may be added where useful
• Leverage the typing library — say what a structure is (typing.List[str] instead of list), remembering we need to support Python 3.8 or newer (which means some typing features are not available, and which means we can’t use the newer list[str] syntax)
• Consider getting rid of untyped, ad-hoc structures:
  • replace large or highly-used tuples with dataclasses
  • replace dictionaries that have a constant set of attributes and are passed around with dataclasses
  • replace namedtuples with dataclasses
  • where dictionaries make sense, consider TypedDict
• Consider converting some data-heavy classes to @dataclasses.dataclass
• Consider getting rid of dynamicness/magic where it makes things harder to reason about without any clear benefits

This is a good first issue for people who never touched Nikola, including people who aren’t its users (yet). It is also a great opportunity to learn typing in Python. We’re not expecting one person or one PR to handle everything :)

[felixfontein]

It would be nice to eventually get rid of Python 3.8 support: both for being able to write list[str], and for having from __future__ import annotations to be able to use even newer typing features without breaking support for older Python versions.

[Kwpolska]

If we go by the usual informal policy (which I want to make formal in PR #3740), we’re stuck with Python 3.8 until Ubuntu 20.04 goes out of support in mid-2025.

[MuditJ]

I am new to nikola and still exploring the codebase but would like to give this a try. Any suggestions on where I can start adding type annotations? @Kwpolska

[Kwpolska]

@MuditJ Most things don’t have type annotations. A good place to start might be the root directory of the package.