Mailman 3 March 2017 - docs

[issue29920] Document cgitb.text and cgitb.html
by Xavier Morel June 1, 2017

June 1, 2017

New submission from Xavier Morel: Currently, cgitb documents the hook (enable) and somewhat unclearly the ability to dump the HTML traceback to stdout, but despite that being technically available it does not document the ability to dump the traceback to a string as either text or html. Possible further improvement: make ``cgitb.html`` and ``cgitb.text`` implicitly call `sys.exc_info()` if not given a parameter (much like `cgitb.handler` does). ---------- assignee: docs@python components: Documentation messages: 290608 nosy: docs@python, xmorel priority: normal pull_requests: 747 severity: normal status: open title: Document cgitb.text and cgitb.html type: enhancement versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29920> _______________________________________

4 10

[issue24692] types.coroutines() idempotence documentation
by Antoine Pietri June 1, 2017

June 1, 2017

New submission from Antoine Pietri: In the new types.coroutines() documentation, it is not clearly stated whether this function is idempotent or not: what happens when it is called on a function that is already a native coroutine? ---------- assignee: docs@python components: Documentation messages: 247184 nosy: docs@python, seirl priority: normal severity: normal status: open title: types.coroutines() idempotence documentation versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24692> _______________________________________

5 9

[issue17188] Document 'from None' in raise statement doc.
by Terry J. Reedy May 30, 2017

May 30, 2017

New submission from Terry J. Reedy: Language manual, section 7.8. The raise statement has no mention of the 'from None' option. Indeed it says "if given, the second expression must be another exception class or instance", which would exclude None. Library manual, Ch 5. Built-in Exceptions, says ''' When raising a new exception (rather than using a bare raise to re-raise the exception currently being handled), the implicit exception context can be supplemented with an explicit cause by using from with raise: raise new_exc from original_exc The expression following from must be an exception or None. It will be set as __cause__ on the raised exception. Setting __cause__ also implicitly sets the __suppress_context__ attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting KeyError to AttributeError, while leaving the old exception available in __context__ for introspection when debugging. ''' I am not sure how much should be copied over, but None should be at least mentioned and perhaps there should be a cross-reference. I am also not sure how much applies to 3.2, but there is no version-added or -changed note with the above. ---------- assignee: docs@python components: Documentation messages: 181939 nosy: docs@python, ncoghlan, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Document 'from None' in raise statement doc. versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17188> _______________________________________

13 34

[issue28845] Clean up known issues for AIX
by Eric N. Vander Weele May 24, 2017

May 24, 2017

New submission from Eric N. Vander Weele: This patch cleans up Misc/README.AIX for addressed known issues. Issues that have been marked fixed: #11184, #11185 Issues resolved by new AIX version: #1745108 Issues resolved, but not yet marked fixed/closed: #11188 Additionally, it looks like #10709 can be closed out as well. For #1745108 and #11188, I have verified they are addressed as of Python 3.5.2 on AIX 7.1 locally. The Python Buildbot is failing to build the curses module, but I believe Setup.local is needed for _curses and _curses_panel. I have gotten the aforementioned curses modules building locally and will figure out the appropriate channels getting Python's PPC64 AIX Buildbot updated independently. ---------- assignee: docs@python components: Documentation files: cleanup-readme-aix.patch keywords: patch messages: 282105 nosy: David.Edelsohn, docs@python, ericvw priority: normal severity: normal status: open title: Clean up known issues for AIX type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45712/cleanup-readme-aix.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28845> _______________________________________

5 13

[issue21056] csv documentation is incorrect
by NRGunby May 23, 2017

May 23, 2017

New submission from NRGunby: The documentation for the csv reader objects next() method is incorrect. It states ' csvreader.next() Return the next row of the reader’s iterable object as a list, parsed according to the current dialect.' Either the documentation for DictReader objects needs to be be made separate from normal reader objects, or this needs to be amended to say ' csvreader.next() Return the next row of the reader’s iterable object as a list (if reader) or dict (if DictReader), parsed according to the current dialect. ' I observed this in the 2.7 online docs, found it to be the case in the 3.4 online docs as well, and haven't checked other versions but assume it's the case. ---------- assignee: docs@python components: Documentation messages: 214775 nosy: NRGunby, docs@python priority: normal severity: normal status: open title: csv documentation is incorrect type: behavior versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21056> _______________________________________

7 11

[issue29321] Wrong documentation for unicode and str comparison
by RK-5wWm9h May 23, 2017

May 23, 2017

New submission from RK-5wWm9h: PROBLEM (IN BRIEF): In the currently published 2.7.13 The Python Language Reference manual, section 5.9 "Comparisons" (https://docs.python.org/2/reference/expressions.html#comparisons): "If both are numbers, they are converted to a common type. Otherwise, objects of different types always compare unequal..." This an *incorrect (and misleading) statement*. PROPOSED FIX: Insert a new sentence, to give this resulting text: "If both are numbers, they are converted to a common type. If one is str and the other unicode, they are compared as below. Otherwise, objects of different types always compare unequal..." DETAILS, JUSTIFICATION, CORRECTNESS, ETC: The behaviour that a str and a unicode object -- despite being objects of different types -- may compare equal, is explicitly stated several paragraphs later: "* Strings are compared lexicographically using the numeric equivalents (the result of the built-in function ord()) of their characters. Unicode and 8-bit strings are fully interoperable in this behavior. [4]" Text in the 2.7.13 The Python Standard Library (Library Reference manual) is careful to cover this unicode - str case (https://docs.python.org/2/library/stdtypes.html#comparisons): "Objects of different types, except different numeric types and different string types, never compare equal; such objects are ordered consistently but arbitrarily (so that sorting a heterogeneous array yields a consistent result)." IMPACT AND RELATED BUG: The current incorrect text is really misleading for anyone reading the Language Ref. It's easy to see the categorical statement and stop reading because your question has been answered. Further, the Library ref about unicode and str (The Python Standard Library (Library Reference manual) section 5.6 "Sequence Types": https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-…), links here. Link text: "(For full details see Comparisons in the language reference.)". (Aside: That paragraph has a mistake similar to this present bug: it says "to compare equal, every element must compare equal and the two sequences must be of the same type"; I'll file a separate bug for it.) PS: First time reporting a Python bug; following https://docs.python.org/2/bugs.html. Hope I did ok! :-) ---------- assignee: docs@python components: Documentation messages: 285790 nosy: RK-5wWm9h, docs@python priority: normal severity: normal status: open title: Wrong documentation for unicode and str comparison type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29321> _______________________________________

2 3

[issue20751] Misleading examples indDescriptor protocol documentation
by Jan Kaliszewski May 20, 2017

May 20, 2017

New submission from Jan Kaliszewski: 1. One misleading detail in the descriptor protocol documentation for super bindings is that the following fragment of the http://docs.python.org/reference/datamodel.html#invoking-descriptors page: """ Super Binding If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__). """ ...introduces the method *call* (".m()") which AFAIK has nothing to do with the actual matter of the description (attribute resolution). Also, the "If *a* is an instance of super" fragment is strange, as *a* is not used in the following sentences at all. I believe the description should be: """ Super Binding If binding to a super instance, super(B, obj).x searches obj.__class__.__mro__ for the base class A immediately preceding B and then invokes the descriptor with the call: A.__dict__['x'].__get__(obj, obj.__class__). """ (using 'x' as the attribute name, as for the other kinds of binding). *** 2. Also, in some earlier fragment of the same page: """ Direct Call The simplest and least common call is when user code directly invokes a descriptor method: x.__get__(a). """ The call x.__get__(a) without the second argument seems to be wrong if __get__ is implemented according to the specification "object.__get__(self, instance, owner)" from the same documentation page. ---------- assignee: docs@python components: Documentation messages: 212035 nosy: docs@python, zuo priority: normal severity: normal status: open title: Misleading examples indDescriptor protocol documentation 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/issue20751> _______________________________________

3 4

[issue29651] Inconsistent/undocumented urlsplit/urlparse behavior on invalid inputs
by Vasiliy Faronov May 16, 2017

May 16, 2017

New submission from Vasiliy Faronov: There is a problem with the standard library's urlsplit and urlparse functions, in Python 2.7 (module urlparse) and 3.2+ (module urllib.parse). The documentation for these functions [1] does not explain how they behave when given an invalid URL. One could try invoking them manually and conclude that they tolerate anything thrown at them: >>> urlparse('http:////::\\\\!!::!!++///') ParseResult(scheme='http', netloc='', path='//::\\\\!!::!!++///', params='', query='', fragment='') >>> urlparse(os.urandom(32).decode('latin-1')) ParseResult(scheme='', netloc='', path='\x7f¼â1gdä»6\x82', params='', query='', fragment='\n\xadJ\x18+fli\x9cÛ\x9ak*ÄÅ\x02³F\x85Ç\x18') Without studying the source code, it is impossible to know that there is a very narrow class of inputs on which they raise ValueError [2]: >>> urlparse('http://[') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.5/urllib/parse.py", line 295, in urlparse splitresult = urlsplit(url, scheme, allow_fragments) File "/usr/lib/python3.5/urllib/parse.py", line 345, in urlsplit raise ValueError("Invalid IPv6 URL") ValueError: Invalid IPv6 URL This could be viewed as a documentation issue. But it could also be viewed as an implementation issue. Instead of raising ValueError on those square brackets, urlsplit could simply consider them *invalid* parts of an RFC 3986 reg-name, and lump them into netloc, as it already does with other *invalid* characters: >>> urlparse('http://\0\0æí\n/') ParseResult(scheme='http', netloc='\x00\x00æí\n', path='/', params='', query='', fragment='') Note that the raising behavior was introduced in Python 2.7/3.2. See also issue 8721 [3]. [1] https://docs.python.org/3/library/urllib.parse.html [2] https://github.com/python/cpython/blob/e32ec93/Lib/urllib/parse.py#L406-L408 [3] http://bugs.python.org/issue8721 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 288577 nosy: docs@python, vfaronov priority: normal severity: normal status: open title: Inconsistent/undocumented urlsplit/urlparse behavior on invalid inputs type: behavior versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29651> _______________________________________

7 11

[issue11681] -b option undocumented
by Éric Araujo May 13, 2017

May 13, 2017

New submission from Éric Araujo <merwok(a)netwok.org>: Python 2 has a -b command-line option which is undocumented. It is used by the warnings machinery to decide to warn about (-b) or raise an error (-bb) if someone uses str(bytes) or str(buffer) (explanation courtesy of grep and Python/pythonrun.c). ---------- assignee: docs@python components: Documentation keywords: easy messages: 132195 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: -b option undocumented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11681> _______________________________________

11 22

[issue29956] math.exp documentation is misleading
by Alexander Belopolsky May 8, 2017

May 8, 2017

New submission from Alexander Belopolsky: The math.exp(x) function is documented to "Return e**x" <https://docs.python.org/3/library/math.html#math.exp>. This is misleading because even in the simplest case, math.exp(x) is not the same as math.e ** x: >>> import math >>> math.exp(2) - math.e ** 2 8.881784197001252e-16 I suggest using e<sup>x instead of e**x to distinguish between Python syntax and mathematical operation and change "Return e**x" to "Return e<sup>x, the base-e exponential of x." ---------- assignee: docs@python components: Documentation messages: 290937 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: math.exp documentation is misleading versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29956> _______________________________________

5 23