How to document a duck type?

Question

I'm having documentation bloat on me, as anytime I encounter a complex duck-type, I need some way to say "this duck type" but instead get caught in an endless cycle of "your function requires this of this input, but doesn't document it", and then documenting it. This results in bloated, repetitive documentation, such as the following:

def Foo(arg):
    """
    Args:
      arg: An object that supports X functionality, and Y functionality,
        and can be passed to Z other functionality.
    """
    # Insert code here.

def Bar(arg):
    """
    Args:
      arg: An object that supports X functionality, and Y functionality,
        and can be passed to Z other functionality.
    """
    # Insert code here.

And so on, and so on, for Baz, Qux, and other functions. I need some shorter way of writing "arg is a (type of object)".

For some duck types, it's as easy as "A dict-like object": we know what we expect of a dict, and so, we know what to pass. A dict, or something that can mimic it.

I feel C++ has this same problem with templated types. Haskell would have it, but one can use a type class's definition to document it. (Note: Haskell classes != classes in Java/C++/Python/etc.) (Note: I don't really program in Haskell, so forgive me if it is a crappy example.)

Should I go the traditional OO route, and just write a base class, and say, "anything like this base class" in the docs? The code wouldn't enforce deriving from the base class (as there is no requirement for the object to be derived from it), and the base class adds no value except to document the properties of the interface, essentially.

On the other hand, I'm programming Python, and I try to program within the idioms of a language. (As doing otherwise usually hurts.) Base classes are good for inheriting functionality, but when your base class is completely abstract, it doesn't seem to add value in a duck-typed language.

EDIT: To the answers: I know what duck typing is (that should be evident from the post). Where do I document it is the question, esp. when no class exists to attach documentation to.

I like the term "acts like" and keep the documented requirements general unless there is a specific reason to expose more details. For instance, if only an indexer and count are needed, I would still say "acts like a list". For other types, it's the same: "x acts like an Animal", where presumably the idea that a "Dog is an Animal" is documented/ensured elsewhere. — , Nov 09 '11 at 02:20
@pst: Yes, but what is an Animal, and what do we expect of the Animal, and where do we document it? — Thanatos, Nov 09 '11 at 02:22
`class Animal` and `class Dog` somewhere, with their own documentation :) Python is very rooted in the class-instance model. — , Nov 09 '11 at 02:23

score 8 · Accepted Answer · edited Jun 09 '20 at 06:20

The idea behind duck typing is that you document that you are expecting a duck, and it is up to other objects to fake being a duck.

Nowhere in the docs does any API specify that it accepts a StringIO object; however, we can use them in most places that expect a "file-like object".

Also, for the most part, the standard library tries to avoid naming the specific methods demanded of a duck type. That leaves the implementation open to change. The random.sample API, for example, could have been defined in terms of iterables or in terms of sequences.

If you want to be more specific than this, you could use abstract base classes. Several are already included in the collections module (such as Iterable, Hashable, and Sized) or numbers module (Rational, Integral, etc). It is not hard to model after those to write your own. Then, the documentation simply mentions which ABCs are required (e.g. x is a Sized Iterable and y is an Integral).

Went with the last paragraph: my ducks types are new types, so going with writing abstract base classes. — Thanatos, Nov 10 '11 at 21:51

score 2 · Answer 2 · answered Nov 09 '11 at 03:01

The point of duck typing is that the notion of "type" becomes an abstract intuitive idea, rather than something that is formally part of the language. This makes typing much more fluid and flexible than in languages where type checking is part of the language.

What is required when using duck typing is not that the program knows what "type" you're using, but that other programmers do. So if you have a whole family of classes/functions/etc that operate on objects of a particular "type", and that type is not able to be described in a few words, just add a section in comments or a docstring (or even an external .txt file) describing your type and naming it. Then you can just refer to that name everywhere.

score 1 · Answer 3 · answered Nov 09 '11 at 03:05

More strictly typed languages, like Java, have the concept of "interfaces": collections of methods that any class implementing the interface is supposed to provide.

I suppose you could borrow the concept without necessarily bringing along the baggage of strict typing: just define and document an abstract class Foo, and then say that your method expects "a Foo or a Foo-like object". You don't even have to make any other class actually inherit from Foo if you don't want to; people reading the documentation will still know where to go to find out what is expected of a Foo-like object.

How to document a duck type?

3 Answers3

Linked