Mailman 3 September 2018 - docs

[issue26369] doc for unicode.decode and str.encode is unnecessarily confusing
by Ben Spiller 30 May '20

30 May '20

New submission from Ben Spiller: It's well known that lots of people struggle writing correct programs using non-ascii strings in python 2.x, but I think one of the main reasons for this could be very easily fixed with a small addition to the documentation for str.encode and unicode.decode, which is currently quite vague. The decode/encode methods really make most sense when called on a unicode string i.e. unicode.encode() to produce a byte string, or on a byte string e.g. str.decode() to produce a unicode object from a byte string. However, the additional presence of the opposite methods str.encode() and unicode.decode() is quite confusing, and a frequent source of errors - e.g. calling str.encode('utf-8') first DECODES the str object (which might already be in utf8) to a unicode string **using the default encoding of "ascii"** (!) before ENCODING to a utf-8 byte str as requested, which of course will fail at the first stage with the classic error "UnicodeDecodeError: 'ascii' codec can't decode byte" if there are any non-ascii chars present. It's unfortunate that this initial decode/encode stage ignores both the "encoding" argument (used only for the subsequent encode/decode) and the "errors" argument (commonly used when the programmer is happy with a best-effort conversion e.g. for logging purposes). Anyway, given this behaviour, a lot of time would be saved by a simple sentence on the doc for str.encode()/unicode.decode() essentially warning people that those methods aren't that useful and they probably really intended to use str.decode()/unicode.encode() - the current doc gives absolutely no clue about this extra stage which ignores the input arguments and sues 'ascii' and 'strict'. It might also be worth stating in the documentation that the pattern (u.encode(encoding) if isinstance(u, unicode) else u) can be helpful for cases where you unavoidably have to deal with both kinds of input, string calling str.encode is such a bad idea. In an ideal world I'd love to see the implementation of str.encode/unicode.decode changed to be more useful (i.e. instead of using ascii, it would be more logical and useful to use the passed-in encoding to perform the initial decode/encode, and the apss-in 'errors' value). I wasn't sure if that change would be accepted so for now I'm proposing better documentation of the existing behaviour as a second-best. ---------- assignee: docs@python components: Documentation messages: 260359 nosy: benspiller, docs@python priority: normal severity: normal status: open title: doc for unicode.decode and str.encode is unnecessarily confusing type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26369> _______________________________________

7 16

[issue31869] commentary on ssl.PROTOCOL_TLS
by J Sloot 30 May '20

30 May '20

New submission from J Sloot <jsloot(a)gmail.com>: on https://docs.python.org/2/library/ssl.html#ssl.PROTOCOL_TLS for ssl.PROTOCOL_TLS When the commentary from ssl.PRTOCOL_TLS moved from PROTOCOL_SSLv23 to PROTOCOL_TLS the note {Despite the name, this option can select "TLS" protocols as well as "SSL"} didn't change. Suggested new wording {Despite the name, this option can select "SSL" protocols as well as "TLS"} ---------- assignee: docs@python components: Documentation messages: 304996 nosy: J Sloot, docs@python priority: normal severity: normal status: open title: commentary on ssl.PROTOCOL_TLS versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31869> _______________________________________

5 6

[issue29017] Docs: PySide is provided by 'The Qt Company' and not by 'Nokia'
by Ettore Atalan 29 May '20

29 May '20

New submission from Ettore Atalan: Regarding URL: http://docs.python.org/3/library/othergui.html Section: PySide PySide is provided by 'The Qt Company' and no longer by 'Nokia' like mentioned in the documentation. ---------- assignee: docs@python components: Documentation messages: 283646 nosy: Ettore Atalan, docs@python priority: normal severity: normal status: open title: Docs: PySide is provided by 'The Qt Company' and not by 'Nokia' versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29017> _______________________________________

4 8

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

27 May '20

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

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

22 May '20

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

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

17 May '20

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 17 May '20

17 May '20

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

[issue11425] Cleanup sample codes in tutorial.
by INADA Naoki 13 May '20

13 May '20

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

[issue23677] Mention dict and set comps in library reference
by Frank Millman 10 May '20

10 May '20

New submission from Frank Millman: This is from the documentation at Section 4.6.4. Lists """ Lists may be constructed in several ways: Using a pair of square brackets to denote the empty list: [] Using square brackets, separating items with commas: [a], [a, b, c] Using a list comprehension: [x for x in iterable] Using the type constructor: list() or list(iterable) """ Comprehensions are mentioned as a constructor. This is from the documentation at Section 4.10. Mapping Types """ Dictionaries can be created by placing a comma-separated list of key: value pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}, or by the dict constructor. class dict(**kwarg) class dict(mapping, **kwarg) class dict(iterable, **kwarg) Return a new dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments. """ There is no mention of dictionary comprehensions. For consistency, I believe that the documentation for Dicts and Sets should mention comprehensions. ---------- assignee: docs@python components: Documentation messages: 238186 nosy: FrankMillman, docs@python priority: normal severity: normal status: open title: Mention dict and set comps in library reference versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23677> _______________________________________

8 11

[issue26817] Docs for StringIO should link to io.BytesIO
by Thomas Guettler 09 May '20

09 May '20

New submission from Thomas Guettler: I think a warning at the top of StringIO docs is needed. And it should link to io.BytesIO. Maybe even deprecate StringIO and cStringIO in Python2? StringIO docs: https://docs.python.org/2/library/stringio.html io.BytesIO docs: https://docs.python.org/2/library/io.html#io.BytesIO I would like to see this at the top of StringIO: {{{ Please use io.BytesIO and io.StringIO since this module is not supported in Python3 }} ---------- assignee: docs@python components: Documentation messages: 263917 nosy: docs@python, guettli priority: normal severity: normal status: open title: Docs for StringIO should link to io.BytesIO versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26817> _______________________________________

3 2