'mapping' in weakrefs unneeded?

[Andrew Dalke]

(Repost from a mail I sent to python-dev
http://mail.python.org/pipermail/python-dev/2001-March/01
which garnered no reponse.  Anyone here want to ignore it :)

Hello all,

  I'm starting to learn how to use weakrefs.  I'm curious
about the function named 'mapping'.  It is implemented as:

> def mapping(dict=None,weakkeys=0):
>     if weakkeys:
>         return WeakKeyDictionary(dict)
>     else:
>         return WeakValueDictionary(dict)

Why is this a useful function?  Shouldn't people just call
WeakKeyDictionary and WeakValueDictionary directly instead
of calling mapping with a parameter to specify which class
to construct?

If anything, this function is very confusing.  Take the
associated documentation as a case in point:

> mapping([dict[, weakkeys=0]])
> Return a weak dictionary. If dict is given and not None,
> the new dictionary will contain the items contained in dict.
> The values from dict must be weakly referencable; if any
> values which would be inserted into the new mapping are not
> weakly referencable, TypeError will be raised and the new
> mapping will be empty.
>
> If the weakkeys argument is not given or zero, the values in
> the dictionary are weak. That means the entries in the
> dictionary will be discarded when no strong reference to the
> value exists anymore.
>
> If the weakkeys argument is nonzero, the keys in the
> dictionary are weak, i.e. the entry in the dictionary is
> discarded when the last strong reference to the key is
> discarded.

As far as I can tell, this documentation is wrong, or at
the very least confusing.  For example, it says:
> The values from dict must be weakly referencable

but when the weakkeys argument is nonzero,
> the keys in the dictionary are weak

So must both keys and values be weak?  Or only the keys?
I hope the latter since there are cases I can think of
where I want the keys to be weak and the values be types,
hence non-weakreferencable.

Wouldn't it be better to remove the 'mapping' function and
only have the WeakKeyDictionary and WeakValueDictionary.
In which case the documentation becomes:

> WeakValueDictionary([dict])
> Return a weak dictionary. If dict is given and not None,
> the new dictionary will contain the items contained in dict.
> The values from dict must be weakly referencable; if any
> values which would be inserted into the new mapping are not
> weakly referencable, TypeError will be raised and the new
> mapping will be empty.
>
> The values in
> the dictionary are weak. That means the entries in the
> dictionary will be discarded when no strong reference to the
> value exists anymore.

> WeakKeyDictionary([dict])
> Return a weak dictionary. If dict is given and not None,
> the new dictionary will contain the items contained in dict.
> The keys from dict must be weakly referencable; if any
> keys which would be inserted into the new mapping are not
> weakly referencable, TypeError will be raised and the new
> mapping will be empty.
>
> The keys in
> the dictionary are weak. That means the entries in the
> dictionary will be discarded when no strong reference to the
> key exists anymore.

Easier to read and to see the parallels between the two
styles, IMHO of course.

[...python-dev specific paragraph omitted...]

Sincerely,

                    Andrew
                    dalke at acm.org