New submission from Eric O. LEBIGOT:
The documentation for a None (empty) format for floats indicates that it is equivalent to the g format. This does not appear to be correct (http://stackoverflow.com/questions/16525924/precise-definition-of-float-str…).
The Python 3.4 documentation (https://docs.python.org/3.4/library/string.html#format-specification-mini-l…) seems to be much closer to what Python 2.7 does.
It would be useful to have a more correct documentation for the effect of a None format for floats in Python 2.7 (maybe by copying the Python 3.4 documentation if it applies).
----------
assignee: docs@python
components: Documentation
messages: 215871
nosy: docs@python, lebigot
priority: normal
severity: normal
status: open
title: None float format: incomplete documentation
type: enhancement
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue21195>
_______________________________________
New submission from Ilya Novoselov <ilya.novoselov(a)gmail.com>:
Documentation states that u format unit returns "buffer of 16-bit Unicode (UTF-16) data" while it returns pointer to internal buffer of unicode data, which is either UCS-16 or UCS-32
http://docs.python.org/c-api/arg.html
----------
assignee: docs@python
components: Documentation, Unicode
messages: 147002
nosy: Ilya.Novoselov, docs@python, ezio.melotti
priority: normal
severity: normal
status: open
title: Incorrect documentation for "u" PyArg_Parse format unit
type: behavior
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13341>
_______________________________________
New submission from Barry A. Warsaw:
operator.index() is just a thin wrapper around PyNumber_Index(). The documentation for operator.index() claims that it is equivalent to calling obj.__index__() but for subclasses of int, this is not true. In fact, PyNumber_Index() first does (e.g. in Python 3.3) a PyLong_Check() and if that succeeds, the original object is returned *without* doing the moral equivalent in C of calling obj.__index__(). An example:
class myint(int):
def __index__(self):
return int(self) + 1
>>> x = myint(7)
>>> x.__index__()
8
>>> from operator import index
>>> index(x)
7
The C API documents PyNumber_Index() as: "Returns the o converted to a Python int on success or NULL with a TypeError exception raised on failure."
Because this has been the behavior of PyNumber_Index() since at least 2.7 (I didn't check farther back), this probably cannot be classified as a bug deserving to be fixed in the code for older Pythons. It might be worth fixing for Python 3.4, i.e. by moving the index check before the type check. In the meantime, this is probably a documentation bug.
The C API implies, but should be clearer that if o is an int subtype (int and long in Python 2), it is returned unchanged. The operator.index() documentation should be amended to describe this behavior for int/long subclasses.
A different alternative would be to leave PyNumber_Index() unchanged, but with the doco fix, and to augment operator.index() to do the PyIndex_Check() first, before calling PyNumber_Index(). That's a little more redundant, but would provide the documented behavior without changing the C API.
----------
assignee: docs@python
components: Documentation
messages: 185522
nosy: barry, docs@python
priority: normal
severity: normal
status: open
title: PyNumber_Index() is not int-subclass friendly
type: behavior
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17576>
_______________________________________
New submission from Roy Smith:
http://docs.python.org/2/library/socket.html
The description for getnameinfo() says, "... Depending on the settings of flags, the result can contain a fully-qualified domain name or numeric address representation in host.", but does not say what to pass for flags to get those behaviors.
----------
assignee: docs@python
components: Documentation
messages: 210838
nosy: docs@python, roysmith
priority: normal
severity: normal
status: open
title: socket.getnameinfo() does not document flags
versions: Python 2.7
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue20582>
_______________________________________
New submission from Amit Saha:
The description of the symmetric difference operation implies that it cannot be applied to more than two sets (http://docs.python.org/3/library/stdtypes.html#set.symmetric_difference).
However, this is certainly possible:
>>> s={1,2}
>>> t={2,3}
>>> u={3,4}
>>> s^t^u
{1, 4}
>>> s.symmetric_difference(t).symmetric_difference(u)
{1, 4}
I am not sure how much of a "semantic" sense that makes, given that symmetric difference is by definition for two sets. (http://en.wikipedia.org/wiki/Symmetric_difference).
So, either the operator should be fixed to allow only two sets or the description be updated.
----------
assignee: docs@python
components: Documentation
messages: 187899
nosy: Amit.Saha, docs@python
priority: normal
severity: normal
status: open
title: symmetric difference operation applicable to more than two sets
type: behavior
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17854>
_______________________________________
New submission from anatoly techtonik:
Docs lack a good summary page comparing three concepts. The main question is how do I tell if something is a sequence, generator, iterator or iterable? I found myself puzzled that range() is neither generator or iterator.
----------
assignee: docs@python
components: Documentation
messages: 188203
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: docs: summary page - generator vs iterator vs iterable
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17887>
_______________________________________
New submission from anatoly techtonik <techtonik(a)gmail.com>:
http://docs.python.org/library/cmd.html#
Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing?
So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info.
At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/
----------
assignee: docs@python
components: Documentation
messages: 152010
nosy: docs@python, techtonik
priority: normal
severity: normal
status: open
title: cmd: no user documentation
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13875>
_______________________________________
New submission from Stefan Chrobot:
http://docs.python.org/3/reference/simple_stmts.html#assignment-statements
The docs says:
"If the target is a slicing: The primary expression in the reference is evaluated. It should yield a mutable sequence object (such as a list). The assigned object should be a sequence object of the same type."
This seems wrong, because the assigned object can be any iterable:
a = [4, 5, 6]
a[0:0] = range(1, 4)
# a is now [1, 2, 3, 4, 5, 6]
----------
assignee: docs@python
components: Documentation
messages: 188738
nosy: docs@python, stefanchrobot
priority: normal
severity: normal
status: open
title: Misleading information about slice assignment in docs
type: enhancement
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue17939>
_______________________________________
New submission from Terry J. Reedy <tjreedy(a)udel.edu>:
In 3.3. Special method names, 'object' is used as a pseudo class name to prefix all the special method entries. This conflicts with the usual two Python meanings.
1. 'object' is the name of a specific class. So the entry for object.__getattribute__(self, name) says to avoid circularity by calling
object.__getattribute__(self, name), which looks circular and requires a bit a mental work by the reader to properly understand. Ditto for
object.__setattr__(self, name, value) calling
object.__setattr__(self, name, value)
2. Non-specifically, 'object' is usually understood to mean any Python object, not just a class. But the signatures as written require that 'object' specifically be a class and 'object' does not convey that.
So for both reasons, I propose that the pseudoname 'object' be replaces with 'class' or 'someclass'
----------
assignee: docs@python
components: Documentation
messages: 113194
nosy: docs@python, georg.brandl, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Replace confusing pseudoname 'object' in special methods section.
versions: Python 3.2
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue9538>
_______________________________________
New submission from Michael Foord <michael(a)voidspace.org.uk>:
Where os.listdir encounters undecodable bytes from the filesystem it uses the surrogateescape handler. As the resulting strings are invalid they can't be encoded without an errorhandler, and so can't be printed (for example).
This should be documented.
----------
assignee: docs@python
components: Documentation
messages: 149070
nosy: docs@python, michael.foord
priority: normal
severity: normal
stage: needs patch
status: open
title: os.listdir documentation should mention surrogateescape
versions: Python 3.3
_______________________________________
Python tracker <report(a)bugs.python.org>
<http://bugs.python.org/issue13561>
_______________________________________