How to specify that a parameter is a list of specific objects in Python docstrings
Question: I really like using docstrings in Python to specify type parameters when
projects get beyond a certain size.

I'm having trouble finding a standard to use to specify that a parameter is a
list of specific objects, e.g. in Haskell types I'd use [String] or [A].

Current standard (recognisable by PyCharm editor):

    
    
    def stringify(listOfObjects):
        """
        :type listOfObjects: list
        """
        return ", ".join(map(str, listOfObjects))
    

What I'd prefer:

**OPTION 1**

    
    
    def stringify(listOfObjects):
        """
        :type listOfObjects: list<Object>  
        """
        return ", ".join(map(str, listOfObjects))
    

**OPTION 2**

    
    
    def stringify(listOfObjects):
        """
        :type listOfObjects: [Object]
        """
        return ", ".join(map(str, listOfObjects))
    

I suppose that wasn't a great example - the more relevant use case would be
one where the objects in the list must be of a specific type.

**BETTER EXAMPLE**

    
    
    class Food(Object):
        def __init__(self, calories):
            self.calories = calories
    
    class Apple(Food):
        def __init__(self):
            super(self, 200)
    
    class Person(Object):
        energy = 0
        def eat(foods):
            """
            :type foods: [Food]  # is NOT recognised by editor
            """
            for food in foods:
                energy += food.calories
    

So, other than the fact that I'm getting hungry, this example illustrates that
if called with a list of the wrong kind of object, the code would break. Hence
the importance of documenting not only that it needs a list, but that it needs
a list of Food.

**RELATED QUESTION** [How can I tell PyCharm what type a parameter is expected
to be?](http://stackoverflow.com/questions/6318814/how-can-i-tell-pycharm-
what-type-a-parameter-is-expected-to-be) Please note that I'm looking for a
more specific answer than the one above.


Answer: In comments section of [PyCharm's
manual](http://www.jetbrains.com/pycharm/webhelp/type-hinting-in-pycharm.html)
there's a nice hint from developer:

    
    
    #: :type: dict of (str, C)
    #: :type: list of str
    

It works for me pretty well. Now it makes me wonder what's the best way to
document parametrized classes in Python :).

