[New-bugs-announce] [issue8030] documentation bugs and improvements

Christopher the Magnificent report at bugs.python.org
Sun Feb 28 18:59:30 CET 2010


New submission from Christopher the Magnificent <ultimate.mac.fanatic at gmail.com>:

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!!

----------
assignee: georg.brandl
components: Documentation
messages: 100212
nosy: christopherthemagnificent, georg.brandl
severity: normal
status: open
title: documentation bugs and improvements
versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8030>
_______________________________________


More information about the New-bugs-announce mailing list