3

According to the convention in guide to numpy/scipy documentation function parameters should be documented in the following way:

def foo(x):
    """" This function does nothing

    Parameters
    ----------
    x : type
       Description of parameter `x`.
    """"
    pass

This is straightforward if type is a distinct type such as int or str.

Now I want the parameter to be an instance of BaseClass or any object that exposes the same interface (such as a class derived from BaseClass). Is there a convention how to concisely document that parameter x should expose a certain interface (by derivation or duck-typing)?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
MB-F
  • 22,770
  • 4
  • 61
  • 116
  • 1
    Maybe "BaseClass-like object", in analogy with "file-like object"? NumPy uses "array-like" a lot for arrays or objects convertible to array, but that's slightly different; lists of lists don't expose the interface of an array. – user2357112 Jan 23 '14 at 18:40
  • 1
    That's how I currently do it. However, I am not entirely happy with that approach because Class-like feels rather vague. – MB-F Jan 23 '14 at 19:07

1 Answers1

0

The approach you described is pretty much the standard one.

Another approach is to use abstract base classes to define the specific methods that must be implemented and then specify that as the type as suggested on an answer to a related question.

markw
  • 620
  • 3
  • 14