[Python-3000] iostack and Oh Oh

[Paul Moore]

On 12/4/06, Jim Jewett <jimjjewett at gmail.com> wrote:
> On 12/3/06, Bill Janssen <janssen at parc.com> wrote:

[Skillped Jim's point that I'm 100% in agreement with, about what
people will end up doing in practice...]

> > What I'd like to see as documentation is more along the lines of
>
> >   foo (types.Mapping m, (types.SeekableStream, types.BinaryOutputStream) f) => types.Integer
>
> That starts to get long enough that people skip it as boilerplate.
>
> > and *no* human-readable text giving an inaccurate and incomplete
> > description of the parameters.
>
> But will they really use the minimally correct interface, or will they round up?

A convention I have seen used successfully in C++ templates (where
duck typing is used) is to use human-readable text which is *not*
"accurate and incomplete", by saying things like:

    foo(m, f)

   Here, the following operations on m are required:

      ret = m[k] for any hashable k
      m[k] = val for any hashable k
      m.keys() returnung a list

    For f, required operations are...

This is relatively easy to document, just by looking at the code, as
well as being 100% precise. It omits certain "obvious" constraint
requirements such as k in m.keys() implies m[k] won't fail, but we're
supposed to all be adults here, and not be *trying* to break each
other's code :-)

Paul.