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