Mailman 3 February 2020 - docs

[issue27779] Sync-up docstrings in C version of the the decimal module
by Raymond Hettinger May 27, 2020

May 27, 2020

New submission from Raymond Hettinger: The pure python version of decimal has extensive docstrings with text and explanatory examples drawn directly from the decimal arithmetic specification. Those should all be copied to the C version as well. This will improve usability for interactive use and improve help(). I would like to leave this work for one of the new aspiring core devs (perhaps Elizabeth, Lisa, or Nofar). ---------- assignee: docs@python components: Documentation keywords: easy messages: 272875 nosy: docs@python, rhettinger priority: normal severity: normal stage: needs patch status: open title: Sync-up docstrings in C version of the the decimal module versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________

4 18

[issue35714] Document that the null character '\0' terminates a struct format spec
by Dan Snider May 26, 2020

May 26, 2020

New submission from Dan Snider <mr.assume.away(a)gmail.com>: ie.: >>> from struct import calcsize >>> calcsize('\144\u0064\000xf\U00000031000\60d\121\U00000051') 16 I'm sure some people think it's obvious or even expect the null character to signal EOF but it probably isn't obvious at all to those without experience in lower level languages. It actually seems like Python goes out of its way to make sure everything treats the null character no more special than the letter "H", which is good. At first glance I'd think something like this was just another trivial quirk of the language and not bring it up, but because the documentation doesn't mention it I actually got stuck on something related for half an hour when unit testing some dynamically generated format specs. Without going into unnecessary detail, what happened was that a typo in another tangentially related part of the test was enabling the generation of a rogue null byte. I'm bad at those "find face in the crowd" puzzles and this was hardly different, being literally camouflaged within a 300 character format spec containing a random mixture of escaped and non-escaped source characters in the forms: \Uffffffff, \uffff, \777, \xff, \x00, + latin/ascii. If I'm not the only one who sees this as a slightly bigger deal than poor documentation, the fix is trivial with an extra call to PyBytes_GET_SIZE when null is found. But just because I can't think of a use case in allowing the null character to precede other characters in the format string doesn't mean there isn't one, which is why only documentation is currently selected. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 333424 nosy: bup, docs@python priority: normal severity: normal status: open title: Document that the null character '\0' terminates a struct format spec versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35714> _______________________________________

6 16

[issue39301] Specification of bitshift on integers should clearly state floor division used
by Nick Coghlan May 26, 2020

May 26, 2020

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: While reviewing ISO-IECJTC1-SC22-WG23's latest draft of their Python security annex, I noticed that https://docs.python.org/3.7/library/stdtypes.html#bitwise-operations-on-int… doesn't explicitly state that *floor* division is used for right shift operations, so right-shifting a negative number by more bits than it contains gives -1 rather than 0. This is consistent with the way the language spec defines both binary right-shifts (as division by "pow(2, n)" and floor division (as rounding towards negative infinity), so this is just a documentation issue to note that we should make it clearer that this behaviour is intentional. ---------- assignee: docs@python components: Documentation messages: 359786 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Specification of bitshift on integers should clearly state floor division used type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39301> _______________________________________

4 15

[issue37973] improve docstrings of sys.float_info
by Sergey Fedoseev May 24, 2020

May 24, 2020

New submission from Sergey Fedoseev <fedoseev.sergey(a)gmail.com>: In [8]: help(sys.float_info) ... | | dig | DBL_DIG -- digits | This is not very helpful, https://docs.python.org/3/library/sys.html#sys.float_info is more verbose, so probably docstrings should be updated from where. ---------- assignee: docs@python components: Documentation messages: 350703 nosy: docs@python, sir-sigurd priority: normal severity: normal status: open title: improve docstrings of sys.float_info type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37973> _______________________________________

5 8

[issue23738] Clarify documentation of positional-only default values
by Martin Panter May 22, 2020

May 22, 2020

New submission from Martin Panter: This patch adds the PEP 457 positional-only slash “/” indicator to some function signatures in the documentation. I only looked at the the os, builtin, binascii, zlib and fcntl modules, and their functions where the documentation incorrectly suggests that they accept keyword arguments. For example, I changed eval(expression, globals=None, locals=None) to eval(expression, globals=None, locals=None, /) References: * Issue 22832: “fcntl” module changed to look like accepting keyword arguments * Ongoing discussion: <https://mail.python.org/pipermail/python-dev/2015-March/138847.html> There are many more instances where square brackets are used, or the arguments are mandatory. See the PEP for examples, but I do not think it is so important to “fix” them. I also fixed parameter name mismatches that I discovered for a quite a few functions that do take keyword arguments. One more thing I noticed, that I do not know how to fix, is the Argument Clinic signatures list invalid default values for zlib.compressobj(zdict=None) and os.utime(ns=None): >>> zlib.compressobj(zdict=None) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'NoneType' does not support the buffer interface >>> os.utime("dummy", ns=None) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: utime: 'ns' must be a tuple of two ints ---------- assignee: docs@python components: Documentation files: pos-defaults.patch keywords: patch messages: 238890 nosy: docs@python, serhiy.storchaka, vadmium priority: normal severity: normal status: open title: Clarify documentation of positional-only default values versions: Python 3.4, Python 3.5 Added file: http://bugs.python.org/file38632/pos-defaults.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23738> _______________________________________

6 18

[issue39705] Tutorial, 5.6 Looping Techniques, sorted() example
by Mirwi May 18, 2020

May 18, 2020

New submission from Mirwi <mirwi(a)binary-kitchen.de>: >>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana'] >>> for f in sorted(set(basket)): ... print(f) ... apple banana orange pear Shouldn't 'apple' appear two times as basket is a list that allows duplicates, not a set? I'm just doing my first steps into Python and may be mislead. In that case, sorry for the fuzz. ---------- assignee: docs@python components: Documentation messages: 362395 nosy: docs@python, mirwi priority: normal severity: normal status: open title: Tutorial, 5.6 Looping Techniques, sorted() example type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39705> _______________________________________

4 7

[issue34431] Docs does not eval allows code object as argument
by Jonathan Fine May 17, 2020

May 17, 2020

New submission from Jonathan Fine <jfine2358(a)gmail.com>: See https://docs.python.org/3.6/library/functions.html#eval This says the following won't happen. But it does. Python 3.6.2 (default, Jul 29 2017, 00:00:00) [GCC 4.8.4] on linux Type "help", "copyright", "credits" or "license" for more information. >>> def fn(): print(3); return 4 ... >>> eval(fn.__code__) 3 4 Compare with https://docs.python.org/3.6/library/functions.html#exec Search for eval in title of open issues bring up related #22057 (The doc say all globals are copied on eval(), but only __builtins__ is copied) #25810 (Python 3 documentation for eval is incorrect) ---------- assignee: docs@python components: Documentation messages: 323716 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs does not eval allows code object as argument versions: Python 2.7, 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/issue34431> _______________________________________

4 8

[issue18262] ZipInfo.external_attr are not documented
by anatoly techtonik May 17, 2020

May 17, 2020

New submission from anatoly techtonik: zipfile doesn't restore file attributes when extracting. Documentation should at least contain example how to do this manually, because the ony way to do this - through ZipInfo.external_attr is too cryptic. ---------- assignee: docs@python components: Documentation messages: 191447 nosy: docs@python, techtonik priority: normal severity: normal status: open title: ZipInfo.external_attr are not documented versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18262> _______________________________________

6 12

[issue38872] Document exec symbol for codeop.compile_command
by Cheryl Sabella May 15, 2020

May 15, 2020

New submission from Cheryl Sabella <cheryl.sabella(a)gmail.com>: codeop.compile_command accepts 'exec' as a symbol, but it is not documented. Opening this bug report for an issue initially reported in PR3179. ---------- assignee: docs@python components: Documentation messages: 357118 nosy: cheryl.sabella, docs@python priority: normal severity: normal status: open title: Document exec symbol for codeop.compile_command type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38872> _______________________________________

5 10

[issue11425] Cleanup sample codes in tutorial.
by INADA Naoki May 14, 2020

May 14, 2020

New submission from INADA Naoki <songofacandy(a)gmail.com>: * Insert spaces around operators and after commas. * Split one liner blocks (ex. def foo(x, y): return x + y) to multi-line blocks. * Insert empty line after def block for scripts (not interactive mode). * Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/) * Use x ** 3 instead of x * x * x. Attached patch is for Python 2.6. I'll make same changes for Python 3.1 if this patch is accepted. ---------- assignee: docs@python components: Documentation files: cleanup_tutorial_codes.patch keywords: patch messages: 130225 nosy: docs@python, naoki priority: normal severity: normal status: open title: Cleanup sample codes in tutorial. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11425> _______________________________________

5 5