[Python-Dev] Questions/comments on documentation formatting

[Benjamin Peterson]

On Tue, Jan 20, 2009 at 8:39 AM, Paul Moore <p.f.moore at gmail.com> wrote:
> 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.

That's exactly why I don't think ABCs would do much good. There are
almost no functions which absolutely require a certain interface. So
use of annotations would be rare.

>
> 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.
>



-- 
Regards,
Benjamin