Mailman 3 October 2017 - docs

[issue30456] 2to3 docs: example of fix for duplicates in second argument of isinstance has superfluous parentheses
by Eli_B 24 Nov '17

24 Nov '17

New submission from Eli_B: The documentation says isinstance(x, (int, int)) would be fixed to isinstance(x, (int)). The fix is actually isinstance(x, int). I propose the following text instead: " 2to3fixer:: isinstance Fixes duplicate types in the second argument of :func:`isinstance`. For example, isinstance(x, (int, int)) is converted to isinstance(x, int) and isinstance(x, (int, float, int)) is converted to isinstance(x, (int, float)). " ---------- assignee: docs@python components: Documentation files: 2to3.rst messages: 294351 nosy: Eli_B, docs@python priority: normal pull_requests: 1867 severity: normal status: open title: 2to3 docs: example of fix for duplicates in second argument of isinstance has superfluous parentheses versions: Python 2.7 Added file: http://bugs.python.org/file46894/2to3.rst _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30456> _______________________________________

2 5

[issue28951] re.flags not documented in Module Contents as promised.
by kevin 16 Nov '17

16 Nov '17

New submission from kevin: In the online documentation of module re (https://docs.python.org/3.5/library/re.html) under 6.2.1. Regular Expression Syntax for item (?aiLmsux) we are promised "The flags are described in Module Contents" but no description is found there. In fact a number of other references are found to flags, but no description of the individual flags. AFAICT the closest thing to a description is found at the original reference -- at least it gives a code and name for each one. ---------- assignee: docs@python components: Documentation messages: 283034 nosy: 4Dummies, docs@python priority: normal severity: normal status: open title: re.flags not documented in Module Contents as promised. type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28951> _______________________________________

3 10

[issue24896] It is undocumented that re.UNICODE affects re.IGNORECASE
by Leif Arne Storset 16 Nov '17

16 Nov '17

New submission from Leif Arne Storset: A non-ASCII string does not match a regular expression case-insensitively unless the UNICODE flag is set. This seems reasonable, but the documentation seems to imply that this is not the case. The example: import re # Does not match re.compile(u"неоднозначность", re.IGNORECASE) \ .findall(u"Неоднозначность") # Matches re.compile(u"неоднозначность", re.IGNORECASE | re.UNICODE) \ .findall(u"Неоднозначность") (In Python 3, it does not match if re.ASCII is given.) The documentation (2.7) says: re.UNICODE Make \w, \W, \b, \B, \d, \D, \s and \S dependent on the Unicode character properties database. (https://docs.python.org/2/library/re.html#re.UNICODE) My regex does not use any of those escapes, yet the regex changes behavior with the UNICODE flag. This leads to confusion when the regex doesn't match. The documentation is very specific about the behavior that changes with the flag, implying that behavior not mentioned is unaffected. Of course, it's easy to guess the correct (hopefully) solution. Still, I suggest changing the documentation to mention that re.IGNORECASE is affected. Looking at the source code, there seems to be further consequences (it mentions "Unicode locale") which may also warrant a mention. If you do want to avoid specifics, however, even a hand-wavy reference to something like "match according to Unicode" would help, because it implies that not only the escapes change behavior. In Python 3, there is a counterpart to the 2.7 problem: re.ASCII makes our Cyrillic string not match. Again, this behavior makes intuitive sense, but the documentation seems to indicate something different: re.ASCII Make \w, \W, \b, \B, \d, \D, \s and \S perform ASCII-only matching instead of full Unicode matching. This is only meaningful for Unicode patterns, and is ignored for byte patterns. … re.IGNORECASE Perform case-insensitive matching; expressions like [A-Z] will match lowercase letters, too. This is not affected by the current locale and works for Unicode characters as expected. re.ASCII does appear to affect re.IGNORECASE. Since this is the non-default case, however, I'm not sure it's worth calling it out. I'd be happy even if only the 2.7 docs change. ---------- assignee: docs@python components: Documentation messages: 248829 nosy: Leif Arne Storset, docs@python priority: normal severity: normal status: open title: It is undocumented that re.UNICODE affects re.IGNORECASE versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24896> _______________________________________

8 14

[issue31824] Missing default argument detail in documentation of StreamReaderWriter
by Peter Lovett 11 Nov '17

11 Nov '17

New submission from Peter Lovett <pacqa100(a)yahoo.com.au>: Documentation of StreamReaderWriter at https://docs.python.org/3/library/codecs.html#codecs.StreamReaderWriter section 7.2.1.4.3 is missing the default value on the errors argument. Should change from: class codecs.StreamReaderWriter(stream, Reader, Writer, errors) to be: class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict') ---------- assignee: docs@python components: Documentation messages: 304646 nosy: PeterLovett, docs@python priority: normal severity: normal status: open title: Missing default argument detail in documentation of StreamReaderWriter type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31824> _______________________________________

4 8

[issue14124] _pickle.c comment/documentation improvement
by Merlijn van Deen 10 Nov '17

10 Nov '17

New submission from Merlijn van Deen <valhallasw(a)gmail.com>: As suggested by loewis in msg154233, I created some documentation to help people get started with _pickle.c. ---------- assignee: docs@python components: Documentation, Extension Modules files: _pickle_c_doc.diff keywords: patch messages: 154284 nosy: docs@python, valhallasw priority: normal severity: normal status: open title: _pickle.c comment/documentation improvement type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24641/_pickle_c_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14124> _______________________________________

3 4

[issue31811] async and await missing from keyword list in lexical analysis doc
by Colin Dunklau 09 Nov '17

09 Nov '17

New submission from Colin Dunklau <colin.dunklau(a)gmail.com>: I see that code making async/await real keywords has been merged, but it looks like Doc/reference/lexical_analysis.rst doesn't have those added https://github.com/python/cpython/blob/4a2d00c/Doc/reference/lexical_analys… Is that list autogenerated somehow or was it just overlooked? ---------- assignee: docs@python components: Documentation messages: 304583 nosy: Colin Dunklau, docs@python priority: normal severity: normal status: open title: async and await missing from keyword list in lexical analysis doc type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31811> _______________________________________

6 10

[issue29179] Py_UNUSED is not documented
by Petr Viktorin 09 Nov '17

09 Nov '17

New submission from Petr Viktorin: The Py_UNUSED macro, which was added in Python 3.4, is not documented. Is this an omission, or is it undocumented on purpose? I can prepare a patch if it's the former. The macro was added in: http://bugs.python.org/issue19976 and referenced in: http://bugs.python.org/issue26179 Usage on Github: https://github.com/search?q=py_unused&type=Code ---------- assignee: docs@python components: Documentation messages: 284821 nosy: docs@python, encukou priority: normal severity: normal status: open title: Py_UNUSED is not documented versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29179> _______________________________________

3 6

[issue11253] autodocument first appearance of ctypes.wintypes constants
by anatoly techtonik 08 Nov '17

08 Nov '17

New submission from anatoly techtonik <techtonik(a)gmail.com>: I've just noticed that my application is incompatible with Python 2.5, because ctypes.wintypes is missing SHORT constants. However, I can't find the information when these symbols were introduced first. To prevent such confusion in future it would be nice to extract symbol information for each Python release and automatically include the version of the first appearance in documentation. ---------- assignee: docs@python components: Documentation messages: 128893 nosy: docs@python, techtonik priority: normal severity: normal status: open title: autodocument first appearance of ctypes.wintypes constants versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11253> _______________________________________

6 7

[issue31668] "fixFirefoxAnchorBug" function in doctools.js causes navigating problem in Py3 doc in Chrome
by fireattack 04 Nov '17

04 Nov '17

New submission from fireattack <human.peng(a)gmail.com>: Problem This is a regression bug/flaw in Sphinx's doctools.js, a JS file used in its base template, and therefore got inherited to Python 3's documentation website. Python 2's documentation website is not affected because it's based on an older version of Sphinx. There is a function in doctools.js: /** * workaround a firefox stupidity * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 */ fixFirefoxAnchorBug : function() { if (document.location.hash) window.setTimeout(function() { document.location.href += ''; }, 10); } This function was supposed to fix an anchor bug in Firefox (see comment). It *used to* have a condition of $.browser outside, so it will only be applied to Firefox; but it was removed in JQuery so it was removed here as well. Therefore, this function now applies to all the browsers. Unfortunately, it causes navigating problem in Chrome now, when you use back and forward. The problem STR (Chrome only): 1. Open a link with hash (anchor), e.g. https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str 2. Scroll away from the anchor position. 3. Click any external link (means the link that is not an anchor of current page). 4. Hit "back" button in the browser. What happened: When you navigating back, it doesn't go to your previous position. Instead, it goes to the anchor's location. What it should do: It should go to your previous position. Ironically, it won't cause this problem in Firefox, despite it's supposed to be a fix for (a different) anchor bug in Firefox. Comments I reported it to Sphinx as well: https://github.com/sphinx-doc/sphinx/issues/3549 but didn't get any response so far. Please keep in mind the Firefox anchor bug mentioned above will only happen if the anchor is assigned with <section id>. From my observation we don't really use <section> in HTML, so I don't think this workaround function is really necessary here to begin with. ---------- assignee: docs@python components: Documentation messages: 303576 nosy: docs@python, fireattack priority: normal severity: normal status: open title: "fixFirefoxAnchorBug" function in doctools.js causes navigating problem in Py3 doc in Chrome type: behavior versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31668> _______________________________________

3 3

[issue31678] Incorrect C Function name for timedelta
by Михаил Миронов 04 Nov '17

04 Nov '17

New submission from Михаил Миронов <phobosmir(a)gmail.com>: Documentation: PyDateTime_DELTA_GET_MICROSECOND https://docs.python.org/3/c-api/datetime.html#c.PyDateTime_DELTA_GET_MICROS… Should be: PyDateTime_DELTA_GET_MICROSECONDS ---------- assignee: docs@python components: Documentation messages: 303616 nosy: docs@python, Михаил Миронов priority: normal severity: normal status: open title: Incorrect C Function name for timedelta versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31678> _______________________________________

4 5