[Doc-SIG] Re: [Types-sig] Re: documenting Python constraints on types

[Frederic Giacometti]

Tim Peters wrote:

> > I guess some further definition and formalizing work is required
> > for the basic Python types / protocol.
>
> Have you looked at Paul Prescod's recent work here?  Unfortunately, the
> Types-SIG home page doesn't seem to have a reference to it.  Paul?

No, I'm not aware of it.
Could Tim could give a reference to it ?


>
> > Here is a step forward:
> > In the same spirit as in the read-only / writable Mapping, you may
> > define:
> >
> > - "Tuple" (as a non-mutable read-only sequence
>
> Is that enough?  Sometimes the distinction of interest is that it's-- unlike
> all tuples --immutable "all the way down".

It is consistent with Python; and defining 'immutability all the way down' is a
Grail guest; you'll never be able  to contain all possible side effects with
Python, and then you'll have missed some.
Besides, personnally, I see minor practical need for it, too.

In any way, Tuple type need to be specified, since Tuple is a major Python type,
and you can't get around without it.

> This is akin to the distinction
> the hash() builtin makes:  not all tuples are hashable.  This is a "shallow
> vs deep" thing, e.g. (1, 2, 3) vs (1, [2], 3).  We *call* both of those
> "immutable" today, but the value of the latter (as seen by "==") may
> actually change over time.

Doing hashing with tuple as key is something fairly rare (for instance, you
might want to count these situations in Python standard lib...).
The case would have to be documented as an extra in the function/method
definition.

[[ Actually, in all practical cases of hashable tuples I know of, the type of
each Tuple item is specified, so the problem does not occur there...
Ex: (String, Int, Int) is a hashable tuple; no problem. ]]

But let me remind the spirit of the thing: Make it fit the most common cases,
the few other cases will require additional documentation. That makes sense to
me :))
I'd rather have something that works in 80% of the cases, than nothing at all as
it is presently the case. I'm not looking for any Grail; I'm just being
practical :))

>
> > - "Vector" (items can be changed, but the sequence size is
> > frozen, just like in a vector objec

> What's "a vector object" <wink -- but Python doesn't have such a thing>?

What does PyNumerical works with, for instance?
It says it: <<the lengh is fixed>>; just like a C array....
A 3D vector of Floats can be specified as Vector( 3)[ Float],
or as [Float, Float, Float].
Anybody normally connected understands such a notation (I hope :)).

> > - List (anything can be done on it; modifying items, adding/removing
> >   items; just like a plain list).
>
> Including, e.g., list.sort()?  You have to be very specific -- I'm afraid
> "just like" is never adequate, as different people read different things
> into any gap in precision.

Well, we have to start from something, don't we? :)) We're no God who can create
from nothing :))
Again, I'd rather start from a loose definition and narrow it down, that not do
anything by fear of not getting it right the first time :))) (that's RAD,
incremental quality improvement, small steps, U-name-it).

Given that I know that I will never be 'perfectly specific', I'll be looking
forward to being 'more and more specific'...

Personally, I'd keep the sort() method outside (not required), and explicitely
document it whenever it is required.
Again, this is used in only a very small minority of functions.

FG