Com relação à type-hints, eu também sou bastante fã.
Type hints, quando rodados junto com um type checker como o mypy, trazem muitas vantagens:
- Documentação.
Com certeza não substitui a documentação escrita, mas colocar type hints realmente facilita, pois além de não depender das docstrings, ainda temos a ferramenta checando para você, evitando que ela fica desetualizada.
Eu já vi muitas e muitas vezes (e escrevi também) documentação que até estava correta inicialmente, mas depois de um tempo ficou desatualizada. Por exemplo, dizer que um método retorna um dict de str -> int, mas devido à algum refactoring ele às vezes retornava um valor str (ao invés de int), quebrando o cliente. Aqui o type checker vai detectar o problema imediatamente.