Hoe het functieretourtype en argumenttypes te kennen?

| | | | | | | | | | | | | | |

Hoewel ik me bewust ben van het duck-typing-concept van Python, worstel ik soms met het type argumenten van functies, of het type van de geretourneerde waarde van de functie.

Als ik nu schreef de functie zelf, ik ken de typen. Maar wat als iemand mijn functies wil gebruiken en aanroepen, hoe wordt dan verwacht dat hij/zij de typen kent? Ik plaats meestal type-informatie in de docstring van de functie (zoals: "...het id-argument moet een geheel getal zijn..." en "... de functie retourneert een ( string, [integer]) tuple.")

Maar is het opzoeken van de informatie in de docstring (en het daar plaatsen, als een codeur) echt de manier waarop het zou moeten worden gedaan?

Bewerken: hoewel de meeste antwoorden lijken te verwijzen naar "ja, document!" Ik heb het gevoel dat dit niet altijd erg gemakkelijk is voor "complexe" typen.
Bijvoorbeeld : hoe beknopt in een docstring te beschrijven dat een functie een lijst met tupels retourneert, met elke tupel van de vorm (node_id, node_name, uptime_minutes) en dat de elementen respectievelijk een string, string en integer zijn?
De docstring PEP-documentatie geeft daar geen richtlijnen voor.
Ik denk dat het tegenargument zal zijn dat in dat geval klassen moeten worden gebruikt, maar ik vind python erg flexibel omdat het deze dingen kan omzeilen met behulp van lijsten en tupels, dat wil zeggen zonder lessen.