This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author christopherthemagnificent
Recipients christopherthemagnificent, georg.brandl
Date 2010-02-28.17:59:28
SpamBayes Score 6.259049e-12
Marked as misclassified No
Message-id <1267379970.2.0.344347508517.issue8030@psf.upfronthosting.co.za>
In-reply-to
Content
Help for list looks like this:

    >>> help(list)
    class list(object)
     |  list() -> new list
     |  list(sequence) -> new list initialized from sequence's items
     |  
     ....

Help for dict looks like this:

    >>> help(dict)
    class dict(object)
     |  dict() -> new empty dictionary.
     |  dict(mapping) -> new dictionary initialized from a mapping object's
     |      (key, value) pairs.
     |  dict(seq) -> new dictionary initialized as if via:
     |      d = {}
     |      for k, v in seq:
     |          d[k] = v
     |  dict(**kwargs) -> new dictionary initialized with the name=value pairs
     |      in the keyword argument list.  For example:  dict(one=1, two=2)
     |  
     ....

As suggested by the documentation above -- and proven by verification:

    >>> a = [1, 2, 3]        # a new list
    >>> b = list(a)
    >>> a is a
    True
    >>> a == b
    True
    >>> a is b
    False
    >>> a is list(a)
    False
    
    >>> a = {'do': 1, 'rey': 2, 'mi': 3}    # a new dict
    >>> b = dict(a)
    >>> a is a
    True
    >>> a == b
    True
    >>> a is b
    False
    >>> a is dict(a)
    False

-- we can clearly see that list(x) and dict(x) ALWAYS return a new, unique object.


What about set?  
    
    >>> help(set)
    class set(object)
     |  set(iterable) --> set object
     |  
     |  Build an unordered collection of unique elements.
     |  
     ....


help(set) simply reports that set(x) returns a set object.  For all we know, this could mean creating a new object only if coercion is necessary; that sounds plausible enough, and people could easily write code dependent on that assumption that would introduce VERY subtle bugs!

Experimentation shows however that, like list and dict, set always returns a new, unique object:

    >>> a = {1, 2, 3}
    >>> b = set(a)
    >>> a is a
    True
    >>> a == b
    True
    >>> a is b
    False
    >>> a is set(a)
    False

Yipes!  CONFUSION!!!  


How about we fix the documentation for set so that it matches that of list and dict, including disclosure of its always-create-new-object behavior?  We can also make the "returns" arrow have one hyphen instead of two for consistency with most other Python documentation.

Let's replace this line:
X   set(iterable) --> set object

with this line:
√   set(iterable) -> new set object
   
so that our help(set) documentation ends up looking like this:

    class set(object)
     |  set(iterable) -> new set object
     |  
     |  Build an unordered collection of unique elements.
     |  
     ....


While we're at it, I'd recommend changing the help for list and dict so that instead of saying "list(sequence)", "dict(seq)", and "for k, v in seq:" -- which, besides being inconsistent in use of abbreviation, also use the older paradigm of sequences instead of iterables -- we instead say "list(iterable)", "dict(iterable)", and "for k, v in iterable:", giving us (X's by altered lines):

    >>> help(list)
    class list(object)
     |  list() -> new list
X    |  list(iterable) -> new list initialized from sequence's items
     |  
     ....

    >>> help(dict)
    class dict(object)
     |  dict() -> new empty dictionary.
     |  dict(mapping) -> new dictionary initialized from a mapping object's
     |      (key, value) pairs.
X    |  dict(iterable) -> new dictionary initialized as if via:
     |      d = {}
X    |      for k, v in iterable:
     |          d[k] = v
     |  dict(**kwargs) -> new dictionary initialized with the name=value pairs
     |      in the keyword argument list.  For example:  dict(one=1, two=2)
     |  
     ....

Making these changes from "seq"/"sequence" to "iterable" will serve to eliminate confusion as to whether set objects are usable in list and dict constructors -- for example, like this:

    >>> x = {('spam', 'icky'), 
    ...      ('balony', 'stomachable'), 
    ...      ('beef', 'palatable'),
    ...      ('turkey', 'yummy')}
    >>> dict(x)
    {'turkey': 'yummy', 'balony': 'stomachable', 'beef': 'palatable', 'spam': 'icky'}

Python's clear and helpful online documentation is one of my most favorite features of the language, and I'm  not alone in feeling this way, so we should make it the very best resource that we can!  Python rules!!
History
Date User Action Args
2010-02-28 17:59:30christopherthemagnificentsetrecipients: + christopherthemagnificent, georg.brandl
2010-02-28 17:59:30christopherthemagnificentsetmessageid: <1267379970.2.0.344347508517.issue8030@psf.upfronthosting.co.za>
2010-02-28 17:59:29christopherthemagnificentlinkissue8030 messages
2010-02-28 17:59:28christopherthemagnificentcreate