Question

I see it’s not considered pythonic to use isinstance(), and people suggest e.g. to use hasattr().

I wonder what the best way is to document the proper use of a function that uses hasattr().

Example:
I get stock data from different websites (e.g. Yahoo Finance, Google Finance), and there are classes GoogleFinanceData and YahooFinanceData which both have a method get_stock(date).
There is also a function which compares the value of two stocks:

def compare_stocks(stock1,stock2,date):
    if hasattr(stock1,'get_stock') and hasattr(stock2,'get_stock'):
        if stock1.get_stock(date) < stock2.get_stock(date):
            print "stock1 < stock2"
        else:
            print "stock1 > stock2"

The function is used like this:

compare_stocks(GoogleFinanceData('Microsoft'),YahooFinanceData('Apple'),'2012-03-14')

It is NOT used like this:

compare_stocks('Tree',123,'bla')

The question is: How do I let people know which classes they can use for stock1 and stock2? Am I supposed to write a docstring like "stock1 and stock2 ought to have a method get_stock" and people have to look through the source themselves? Or do I put all right classes into one module and reference that file in the docstring?

Answer 1

I don’t see whats unpythonic about the use of isinstance(), I would create a base class and refer to the base class’ documentation.

def compare_stocks(stock1, stock2, date):
    """ Compares stock data of two FinanceData objects at a certain time. """
    if isinstance(stock1, FinanceData) and isinstance(stock2, FinanceData):
        return 'comparison'

class FinanceData(object):
    def get_stock(self, date):
        """ Returns stock data in format XX, expects parameter date in format YY """
        raise NotImplementedError

class GoogleFinanceData(FinanceData):
    def get_stock(self, date):
        """ Implements FinanceData.get_stock() """
        return 'important data'

As you see I don’t use duck-typing here, but since you’ve asked this question in regards to documentation, I think this is the cleaner approach for readability. Whenever another developer sees the compare_stocks function or a get_stock method he knows exactly where he has to look for further information regarding functionality, data structure or implementation details.