Mailman 3 August 2018 - docs

[issue33216] Wrong order of stack for CALL_FUNCTION_VAR and CALL_FUNCTION_VAR_KW
by Manuel Vazquez Acosta 17 Sep '18

17 Sep '18

New submission from Manuel Vazquez Acosta <manuel(a)merchise.org>: The documentation of the dis module says that: CALL_FUNCTION_VAR (argc) Calls a function. *argc* is interpreted as in CALL_FUNCTION. The top elements on the stack are the keyword arguments, followed by the variable argument list, and then the positional arguments. However, inspecting the how ``f(b=1, *args)`` is actually compiled shows a different order: >>> import dis >>> dis.dis(compile('f(b=1, *args)', '<>', 'eval')) 1 0 LOAD_NAME 0 (f) 3 LOAD_NAME 1 (args) 6 LOAD_CONST 0 ('b') 9 LOAD_CONST 1 (1) 12 CALL_FUNCTION_VAR 256 (0 positional, 1 keyword pair) 15 RETURN_VALUE Notice that the top of the stack contains the explicit keyword arguments. The documentation of CALL_FUNCTION_VAR_KW is also incorrect. ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python title: CALL_FUNCTION_VAR -> Wrong order of stack for CALL_FUNCTION_VAR and CALL_FUNCTION_VAR_KW versions: +Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33216> _______________________________________

7 26

[issue25296] Simple End-of-life guide covering all unsupported versions
by Nick Coghlan 15 Sep '18

15 Sep '18

New submission from Nick Coghlan: Katie McLaughlin recently pointed me at PHP's summary page for the End-of-Life dates for their various releases: http://php.net/eol.php That seems like a useful thing to offer, but we unfortunately don't currently have a great place for this kind of documentation: - the main docs are version specific, while this kind of page should be version independent - the update process, access control model and reader experience for python.org is too different from that for the main documentation - ditto for the wiki - informational PEPs are closer from an access control perspective, but aren't generated with Sphinx and are still disconnected from the main docs from a reader perspective - it's off-topic for the developer guide The "right" answer seems to be setting up a separate "docs" project on hg.python.org to use as the landing page for docs.python.org and for version independent information like this (the redirects already defined as part of PEP 430 should continue to handle unqualified deep links into the Python 2 docs). I'm not sure how much reconfiguration work such a change would entail, though. ---------- assignee: docs@python components: Documentation messages: 252084 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Simple End-of-life guide covering all unsupported versions type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25296> _______________________________________

12 18

[issue28955] Not matched behavior of numeric comparison with the documentation
by woo yoo 14 Sep '18

14 Sep '18

New submission from woo yoo: According to the documentation, which said "Additionally, comparing any number to a not-a-number value will return False. ",the comparison of `float('nan')!= 1`should yield False, while the result is True. Small errors like this in documentation should be corrected? The related link https://docs.python.org/3/reference/expressions.html#value-comparisons ---------- assignee: docs@python components: Documentation messages: 283069 nosy: docs@python, woo yoo priority: normal severity: normal status: open title: Not matched behavior of numeric comparison with the documentation type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28955> _______________________________________

7 8

[issue33774] Improve doc of @lru_cache to avoid misuse and confusion
by Al-Scandar Solstag 14 Sep '18

14 Sep '18

New submission from Al-Scandar Solstag <solstag(a)member.fsf.org>: Ni! It is not clear at all in the documentation of @lru_cache that the cache takes into account the exact way the function was called, not the values passed to its arguments, as one could/would expect. I mean that for function(a, b, c=3) the three calls below are not considered equivalent as far as the cache is concerned: function(1, 2, 3) function(1, 2, c=3) function(1, 2) I hope this can be clarified in the documentation. I wasted a great deal of time today trying to understand why my calls were not getting cached and only figured it out when I decided to go read @lru_cache's code. It seems very likely that other people have had the same problem. Or worse, people might be using @lru_cache believing it is working when it isn't. Cheers! ---------- assignee: docs@python components: Documentation messages: 318770 nosy: docs@python, solstag priority: normal severity: normal status: open title: Improve doc of @lru_cache to avoid misuse and confusion _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33774> _______________________________________

5 9

[issue33986] Typo: BaseSubprocessTransport -> SubprocessTransport
by Bumsik Kim 12 Sep '18

12 Sep '18

New submission from Bumsik Kim <kbumsik(a)gmail.com>: https://docs.python.org/3/library/asyncio-protocol.html#basesubprocesstrans… I belive the doc has a wrong name "basesubprocesstransport" and it should be "Subprocesstransport". You can see this in the source code: https://github.com/python/cpython/blob/3.6/Lib/asyncio/transports.py ---------- assignee: docs@python components: Documentation messages: 320638 nosy: docs@python, kbumsik priority: normal severity: normal status: open title: Typo: BaseSubprocessTransport -> SubprocessTransport versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33986> _______________________________________

3 6

[issue25041] document AF_PACKET socket address format
by Tim Tisdall 12 Sep '18

12 Sep '18

New submission from Tim Tisdall: As mentioned in #24984, I'm making another issue to document the address format for AF_PACKET. In this case there's already documentation in Modules/socketmodule.c that says: - an AF_PACKET socket address is a tuple containing a string specifying the ethernet interface and an integer specifying the Ethernet protocol number to be received. For example: ("eth0",0x1234). Optional 3rd,4th,5th elements in the tuple specify packet-type and ha-type/addr. But nothing has been added to Doc/library/socket.rst . The documentation needs to be confirmed with the code. (It probably should be altered somewhat to state how you "specify packet-type and ha-type/addr"... and maybe what a "ha-type/addr" is... A quick Google search found this very useful reference: https://books.google.ca/books?id=Chr1NDlUcI8C&pg=PA472&ots=OCEwyjdXJo&sig=P… ) ---------- assignee: docs@python components: Documentation messages: 250306 nosy: Tim.Tisdall, docs@python priority: normal severity: normal status: open title: document AF_PACKET socket address format type: enhancement versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25041> _______________________________________

9 16

[issue26502] traceback.extract_tb breaks compatibility by returning FrameSummary
by Petr Viktorin 11 Sep '18

11 Sep '18

New submission from Petr Viktorin: According to the docs [0], traceback.extract_tb should return 4-tuples (filename, line number, function name, text). [0] https://docs.python.org/3/library/traceback.html#traceback.extract_tb Instead, since Python 3.5, it returns FrameSummary objects, which are not tuples, nor tuple subclasses, nor even sequences. (This broke some code in the wild that called len() on FrameSummary.) Issue 25111 pointed out another tuple incompatibility, which was fixed. Should __len__ be added as well? Or the whole Sequence ABC? I can provide a patch when those questions are answered. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 261296 nosy: docs@python, encukou priority: normal severity: normal status: open title: traceback.extract_tb breaks compatibility by returning FrameSummary versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26502> _______________________________________

4 8

[issue33883] doc Mention mypy, pytype and PyAnnotate in FAQ
by Andrés Delfino 11 Sep '18

11 Sep '18

New submission from Andrés Delfino <adelfino(a)gmail.com>: As far as I know, mypy and pytype are more advanced that any of the other tools mentioned in the FAQ for static analysis, however we are not touching them. PR adds mentions. ---------- assignee: docs@python components: Documentation messages: 319798 nosy: adelfino, docs@python priority: normal severity: normal status: open title: doc Mention mypy, pytype and PyAnnotate in FAQ type: enhancement versions: Python 2.7, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33883> _______________________________________

3 5

[issue33032] Mention implicit cache in struct.Struct docs
by Nick Coghlan 11 Sep '18

11 Sep '18

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The struct.Struct docs claim that creating and re-using a Struct object will be noticeably faster than calling the module level methods repeatedly with the same format string, as it will avoid parsing the format string multiple times: https://docs.python.org/3/library/struct.html#struct.Struct This claim is questionable, as struct has used an internal Struct cache since at least 2.5, so if you're using less than 100 different struct layouts in any given process, the only thing you'll be saving is a string-keyed dictionary lookup. ---------- assignee: docs@python components: Documentation messages: 313468 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Mention implicit cache in struct.Struct docs type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33032> _______________________________________

4 7

[issue32027] argparse allow_abbrev option also controls short flag combinations
by Jörn Hees 11 Sep '18

11 Sep '18

New submission from Jörn Hees <nrej9TyO(a)joernhees.de>: The allow_abbrev option (default True) currently is documented like this (https://docs.python.org/3/library/argparse.html#allow-abbrev): > Normally, when you pass an argument list to the parse_args() method of an ArgumentParser, it recognizes abbreviations of long options. However, it also controls combinations of short options and especially the combination of flags (store_const) like `-a -b` as `-ab`. Example snippet for testing: import argparse import sys parser = argparse.ArgumentParser( allow_abbrev=False ) parser.add_argument('-a', action='store_true') parser.add_argument('-b', action='store_true') parser.add_argument('x', nargs='*') parser.parse_args('-a -b foo bar'.split()) parser.parse_args('-ab foo bar'.split()) As you can see the 2nd parse will fail if allow_abbrev=False. This issue is either a doc issue only or an unintended combination of long option shortening and (the way more common) flag combinations. When i deactivated this in my code, i wanted to disable the (nice to have) long option shortening, but i unintentionally also deactivated (MUST have) short flag combinations. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 306229 nosy: docs@python, joern priority: normal severity: normal status: open title: argparse allow_abbrev option also controls short flag combinations versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32027> _______________________________________

3 3