[Python-Dev] 'mapping' in weakrefs unneeded?

[Andrew Dalke]

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.

I am not on this list though I will try to read the
archives online for the next couple of days.  Please
CC me about any resolution to this topic.

Sincerely,

                    Andrew
                    dalke@acm.org