Question

What is the best way to document the type of parameters that a function expects to receive?

Sometimes a function uses only one or two fields of an object. Sometimes this fields have common names (get(), set(), reset(), etc.). In this situation we must leave a comments:

    ... 
    @staticmethod
    def get( postId, obj ):
        """obj is instance of class Type1, not Type2"""
        inner = obj.get()   

Is there a more explicit way to make it obvious? Maybe an object name should contain expecting typename?

Answer 1

Given python’s ‘duck-typing’ (late bound) behaviour, it would be a mistake to require a particular type.

If you know which types your function must not take, you can raise an exception after detecting those; otherwise, simply raise an exception if the object passed does not support the appropriate protocol.

As to documentation, just put the required protocol in the docstring.