[Python-3000] iostack and Oh Oh
p.f.moore at gmail.com
Mon Dec 4 10:10:44 CET 2006
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:
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 :-)
More information about the Python-3000