New submission from Christopher the Magnificent <ultimate.mac.fana...@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 <rep...@bugs.python.org> <http://bugs.python.org/issue8030> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com