Mailman 3 September 2018 - docs

[issue24256] threading.Timer is not a class
by John Runyon 31 May '20

31 May '20

New submission from John Runyon: the documentation (https://docs.python.org/2/library/threading.html#threading.Timer) lists "threading.Timer" as a class. It is not, which means that (for example) you can not use it in isinstance(). "threading._Timer" is a class. "threading.Timer(...).__class__" is a class. "threading.Timer" is a function. >>> import threading >>> threading.Timer <function Timer at 0x7f99cae23848> ---------- assignee: docs@python components: Documentation messages: 243735 nosy: docs@python, jrunyon priority: normal severity: normal status: open title: threading.Timer is not a class versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24256> _______________________________________

5 6

[issue25511] multiprocessing pool blocks SIGTERM from being handled
by David Jones 31 May '20

31 May '20

New submission from David Jones: This is probably related to #21913, but more specifically concerns the documentation. I have a sub process of a larger program that handles a SIGTERM sent by the main process for a clean shutdown. However, if I launch a parallel task in the sub process, via multiprocessing.Pool.imap_unordered, all signals are blocked until pool finishes running the task. If this isn't going to be fixed, then it ought to at least be clearly documented. It took a very long time to diagnose this problem. It requires a programmer to understand the underlying implementation of a high-level construct, thus defeating the purpose of using a high level construct. Also, is there a way to work around this? ---------- assignee: docs@python components: Documentation messages: 253678 nosy: djones, docs@python priority: normal severity: normal status: open title: multiprocessing pool blocks SIGTERM from being handled type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25511> _______________________________________

2 1

[issue22052] Comparison operators called in reverse order for subclasses with no override.
by Mark Dickinson 31 May '20

31 May '20

New submission from Mark Dickinson: As reported in a StackOverflow question [1]: the order in which the special comparison methods are called seems to be contradictory to the docs [2]. In the following snippet, __eq__ is called with reversed operands first: >>> class A: ... def __eq__(self, other): ... print(type(self), type(other)) ... return True ... >>> class B(A): ... pass ... >>> A() == B() <class '__main__.B'> <class '__main__.A'> True However, the docs note that: """If the right operand’s type is a subclass of the left operand’s type and that subclass provides the reflected method for the operation, this method will be called before the left operand’s non-reflected method. This behavior allows subclasses to override their ancestors’ operations.""" ... which suggests that this reversal should only happen when the subclass B *overrides* A's definition of __eq__ (and indeed that's the usual behaviour for arithmetic operations like __add__). Looking more closely, that statement in the docs is in the 'numeric-types' section, so it's not clear that its rules should apply to the comparison operators. But either way, some doc clarification could be useful. [1] http://stackoverflow.com/q/24919375/270986 [2] https://docs.python.org/3.5/reference/datamodel.html#emulating-numeric-types ---------- assignee: docs@python components: Documentation messages: 223778 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: Comparison operators called in reverse order for subclasses with no override. versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22052> _______________________________________

4 9

[issue23514] multiprocessing documentation - little more examples for parallel computing
by Cezary Wagner 31 May '20

31 May '20

New submission from Cezary Wagner: I am little confused with multiprocessing documentation since it does not contain enough examples. Parallel computing is not simple by design so documentation can be little improved to make it simpler. No pattern to use pool with classes. No pattern to exchange objects between processes. Understanding usage of Queue and SimpleQueue or JoinableQueue is not very clear. Current documentation in majority is good reference with very rare examples / patterns. ---------- assignee: docs@python components: Documentation messages: 236519 nosy: Cezary.Wagner, docs@python priority: normal severity: normal status: open title: multiprocessing documentation - little more examples for parallel computing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23514> _______________________________________

3 4

[issue20296] PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc.
by Rob Browning 31 May '20

31 May '20

New submission from Rob Browning: Here (http://docs.python.org/2/c-api/arg.html), the documentation for "t#" says: t# (read-only character buffer) [char *, int]... while the documentation for "w#" says: w# (read-write character buffer) [char *, Py_ssize_t]... However, from getargs.c, it looks like they're handled the same with respect to the size type. At a minimum, it seems like it might make sense to change these docs to match, and if "w#" and "t#" are actually handled similarly to "s#", it would be even better to just change their docs to match (or refer to) "s#"'s which are more detailed, i.e. they mention the PY_SSIZE_T_CLEAN issues, etc. Thanks ---------- assignee: docs@python components: Documentation messages: 208410 nosy: docs@python, rlb priority: normal severity: normal status: open title: PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20296> _______________________________________

3 3

[issue21547] '!s' formatting documentation bug
by Joshua Landau 31 May '20

31 May '20

New submission from Joshua Landau: In the docs for 2.x about the formatting syntax: https://docs.python.org/2/library/string.html#format-string-syntax it says "Two conversion flags are currently supported: '!s' which calls str() on the value, and '!r' which calls repr()." but for unicode formatters, '!s' calls unicode() instead. See http://stackoverflow.com/questions/23773816/why-python-str-format-doesnt-ca… for the question that found this. ---------- assignee: docs@python components: Documentation messages: 218863 nosy: Joshua.Landau, docs@python priority: normal severity: normal status: open title: '!s' formatting documentation bug versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21547> _______________________________________

5 4

[issue9196] Improve docs for string interpolation "%s" re Unicode strings
by Craig McQueen 31 May '20

31 May '20

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()". Here is what I have found (I think), and it could be worth improving the documentation of this somehow. Example 1: "%s" % test_object >From what I can tell, in this case: 1. test_object.__str__() is called. 2. If test_object.__str__() returns a string object, then that is substituted. 3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising. [Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.] Example 2: u"%s" % test_object In this case: 1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode. 2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode. Example 3: "%s %s" % (u'unicode', test_object) In this case: 1. The first substitution causes the output string to be Unicode. 2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising. ---------- assignee: docs@python components: Documentation messages: 109516 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Improve docs for string interpolation "%s" re Unicode strings versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9196> _______________________________________

5 10

[issue20686] Confusing statement
by Daniel U. Thibault 31 May '20

31 May '20

New submission from Daniel U. Thibault: Near the end of 3.1.3 http://docs.python.org/2/tutorial/introduction.html#unicode-strings you can read: "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding." This can be interpreted as stating that stating that printing a Unicode string (using the print function or the shell's default print behaviour) results in ASCII printout. It can likewise be interpreted as stating that any write of a Unicode string to a file converts the string to ASCII. Experimentation shows this is not true. Perhaps you meant something like this: "When a Unicode string is converted with str() in order to be printed or written to a file, conversion takes place using this default encoding." Grammatical comments: In the statement "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding.", the ", or" puts the three elements of the enumeration on the same level (respectively "printed", "written to a file", and "converted with str()"). The confusion seems to arise because "with str()" was meant to apply to the list as a whole, not just its last element. ---------- assignee: docs@python components: Documentation messages: 211627 nosy: Daniel.U..Thibault, docs@python priority: normal severity: normal status: open title: Confusing statement type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20686> _______________________________________

4 9

[issue17387] Error in C API documentation of PySequenceMethods
by Alex Orange 31 May '20

31 May '20

New submission from Alex Orange: The documentation at http://docs.python.org/2/c-api/typeobj.html#PySequenceMethods is missing sq_slice between sq_item and sq_ass_item. This will mess up anyone trying to use anything after sq_item (that isn't using designated initializers). ---------- assignee: docs@python components: Documentation messages: 183779 nosy: Alex.Orange, docs@python priority: normal severity: normal status: open title: Error in C API documentation of PySequenceMethods versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17387> _______________________________________

5 10

[issue15952] format(value) and value.__format__() behave differently with unicode format
by Chris Jerdonek 31 May '20

31 May '20

New submission from Chris Jerdonek: format(value) and value.__format__() behave differently even though the documentation says otherwise: "Note: format(value, format_spec) merely calls value.__format__(format_spec)." (from http://docs.python.org/library/functions.html?#format ) The difference happens when the format string is unicode. For example: >>> format(10, u'n') u'10' >>> (10).__format__(u'n') # parentheses needed to prevent SyntaxError '10' So either the documentation should be changed, or the behavior should be changed to match. Related to this: neither the "Format Specification Mini-Language" documentation nor the string.Formatter docs seem to say anything about the effect that a unicode format string should have on the return value (in particular, should it cause the return value to be unicode or not): http://docs.python.org/library/string.html#formatspec http://docs.python.org/library/string.html#string-formatting See also issue 15276 (int formatting), issue 15951 (empty format string), and issue 7300 (unicode arguments). ---------- assignee: docs@python components: Documentation messages: 170575 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: format(value) and value.__format__() behave differently with unicode format type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15952> _______________________________________

5 8