[Python-Dev] Questions/comments on documentation formatting

[Paul Moore]

2009/1/20 Benjamin Peterson <benjamin at python.org>:
> We might be opening a can of worms, though. Do we document everything
> that takes a dictionary argument with collections.Mapping or
> everything that takes a integer numbers.Rationale? What if multiple
> types are possible?

No. Only document things as taking an ABC argument if they actually
*do* only take that ABC.

    def f(dct):
        return dct['a']

does not require a collections.Mapping argument, just something that
implements indexing-by-strings. Even with ABCs available, I thought
that duck typing was still expected to be the norm.

If a function does a type-test for an ABC, it makes sense to document
it as requiring that ABC (to flag to users that they may need to
register their own types with the ABC), Otherwise, it does not.

Paul.