Embora eu esteja ciente do conceito de digitação de pato do Python, às vezes tenho dificuldades com o tipo de argumentos de funções ou o tipo de valor de retorno da função.
Agora, se eu escrevi a função eu mesmo, eu conheço os tipos. Mas e se alguém quiser usar e chamar minhas funções, como se espera que ele conheça os tipos? Eu costumo colocar informações de tipo na docstring da função (como: "...o argumento id deve ser um inteiro..." e "... a função retornará um ( string, [integer]) tupla.")
Mas procurar as informações na docstring (e colocá-las lá, como um codificador) é realmente da maneira que deve ser feito?
Editar: Embora a maioria das respostas pareça direcionar para "sim, documento!", acho que isso nem sempre é muito fácil para tipos "complexos".
Por exemplo : como descrever concisamente em uma docstring que uma função retorna uma lista de tuplas, com cada tupla da forma (node_id, node_name, uptime_minutes) e que os elementos são respectivamente uma string, string e integer?
A documentação docstring PEP não fornece nenhuma orientação sobre isso.
Acho que o contra-argumento será que nesse caso as classes devem ser usadas, mas acho o python muito flexível porque permite passar essas coisas usando listas e tuplas, ou seja,