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
