Mailman 3 June 2013 - docs

[issue13368] Possible problem in documentation of module subprocess, method send_signal
by Eli Bendersky 24 Feb '21

24 Feb '21

New submission from Eli Bendersky <eliben(a)gmail.com>: docs@ list report by Daniel Dieterle: in the documentation (http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal) is a bug. CTRL_C_EVENT can not be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP. Why can be read in the msdn documentation http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%… . A workaround using CTRL_C_EVENT nevertheless is described here: http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-o… -- I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was introduced. But it is useless for terminating a process with os.kill() in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT. A CTRL-C-EVENT is only forwarded to the process if the process group is zero. Therefore the Note in the documentation on Popen.send_signal() is wrong. ---------- assignee: docs@python components: Documentation messages: 147272 nosy: docs@python, eli.bendersky priority: normal severity: normal status: open title: Possible problem in documentation of module subprocess, method send_signal versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13368> _______________________________________

4 6

[issue16954] Add docstrings for ElementTree module
by Serhiy Storchaka 21 Feb '21

21 Feb '21

New submission from Serhiy Storchaka: Perhaps almost all Doxygen comments in ElementTree module should be converted to docstrings. ---------- assignee: docs@python components: Documentation, XML messages: 179881 nosy: docs@python, eli.bendersky, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Add docstrings for ElementTree module type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________

8 23

[issue13433] String format documentation contains error regarding %g
by Christian Iversen 18 Feb '21

18 Feb '21

New submission from Christian Iversen <ci(a)sikkerhed.org>: The documentation for string format options state that both %f, %g and %e default to 6 digits after the decimal point. In fact, %g always seems to use 5 digits by default: >>> "%g" % 2.1234567 '2.12346' >>> "%f" % 2.1234567 '2.123457' >>> "%e" % 2.1234567 '2.123457e+00' But something much more insidious is wrong, because even when explicitly told how many digits to have, %g is one off: >>> "%.6g" % 2.1234567 '2.12346' >>> "%.6f" % 2.1234567 '2.123457' >>> "%.6e" % 2.1234567 '2.123457e+00' This can't be right? ---------- assignee: docs@python components: Documentation messages: 147940 nosy: Christian.Iversen, docs@python priority: normal severity: normal status: open title: String format documentation contains error regarding %g type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13433> _______________________________________

6 11

[issue8595] Unexpected default timeout in http-client-related libraries
by Julian 29 Dec '20

29 Dec '20

New submission from Julian <python_org(a)somethinkodd.com>: Since Python 2.6, httplib has offered a timeout parameter for fetches. As the documentation explains, if this parameter is not provided, it uses the global default. What the document doesn't explain is httplib builds on top of the socket library. The socket library has a default timeout of None (i.e. forever). This may be an appropriate default for general sockets, but it is a poor default for httplib; typical http clients would use a timeout in the 2-10 second range. This problem is propagated up to urllib2, which sits on httplib, and further obscures that the default might be unsuitable. >From an inspection of the manuals, Python 3.0.1 suffers from the same problem except, the names have changed. urllib.response sits on http.client. I, for one, made a brutal mistake of assuming that the "global default" would be some reasonable default for fetching web pages; I didn't have any specific timeout in mind, and was happy for the library to take care of it. Several million successful http downloads later, my server application thread froze waiting forever when talking to a recalcitrant web-server. I imagine others have fallen for the same trap. While an ideal solution would be for httplib and http.client to use a more generally acceptable default, I can see it might be far too late to make such a change without breaking existing applications. Failing that, I would recommend that the documentation for httplib, urllib, urllib2, http.client and urllib.request (+ any other similar libraries sitting on socket? FTP, SMTP?) be changed to highlight that the default global timeout, sans deliberate override, is to wait a surprisingly long time. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 104763 nosy: docs@python, oddthinking priority: normal severity: normal status: open title: Unexpected default timeout in http-client-related libraries type: behavior versions: Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8595> _______________________________________

5 8

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
by anatoly techtonik 29 Dec '20

29 Dec '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: 'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation. ---------- assignee: docs@python components: Documentation messages: 106524 nosy: docs@python, techtonik priority: normal severity: normal status: open title: datetime naive and aware types should have a well-defined definition that can be cross-referenced _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8822> _______________________________________

6 15

[issue14586] TypeError: truncate() takes no keyword arguments
by Guy Taylor 15 Dec '20

15 Dec '20

New submission from Guy Taylor <thebigguy.co.uk(a)gmail.com>: The Python docs suggest that io.IOBase.truncate' should take a keyword argument of 'size'. However this causes a 'TypeError': TypeError: truncate() takes no keyword arguments Suggest that the docs are changed to 'truncate(size)' or CPython is changed to allow the keyword. http://docs.python.org/py3k/library/io.html?highlight=truncate#io.IOBase.tr… http://docs.python.org/library/io.html?highlight=truncate#io.IOBase.truncate ---------- assignee: docs@python components: Documentation, Interpreter Core files: test.py messages: 158308 nosy: TheBiggerGuy, docs@python priority: normal severity: normal status: open title: TypeError: truncate() takes no keyword arguments type: behavior versions: Python 2.7, Python 3.2 Added file: http://bugs.python.org/file25219/test.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14586> _______________________________________

6 15

[issue15104] abusive language in __name__ description
by anatoly techtonik 01 Dec '20

01 Dec '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/__main__.html "It is this environment in which the idiomatic “conditional script” stanza causes a script to run" ?!? ---------- assignee: docs@python components: Documentation messages: 163140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: abusive language in __name__ description _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15104> _______________________________________

12 28

[issue13341] Incorrect documentation for "u" PyArg_Parse format unit
by Ilya Novoselov 30 Nov '20

30 Nov '20

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

7 9

[issue17576] PyNumber_Index() is not int-subclass friendly
by Barry A. Warsaw 23 Nov '20

23 Nov '20

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

14 63

[issue17854] symmetric difference operation applicable to more than two sets
by Amit Saha 18 Nov '20

18 Nov '20

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

6 8