Mailman 3 June 2018 - docs

[issue33774] Improve doc of @lru_cache to avoid misuse and confusion
by Al-Scandar Solstag Sept. 14, 2018

Sept. 14, 2018

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 Sept. 12, 2018

Sept. 12, 2018

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 Sept. 12, 2018

Sept. 12, 2018

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 Sept. 11, 2018

Sept. 11, 2018

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 Sept. 11, 2018

Sept. 11, 2018

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 Sept. 10, 2018

Sept. 10, 2018

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 Sept. 10, 2018

Sept. 10, 2018

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

[issue24632] Improve documentation about __main__.py
by Ezio Melotti Aug. 28, 2018

Aug. 28, 2018

New submission from Ezio Melotti: __main__.py seems to only be mentioned briefly in a couple of places in the official docs: 1) https://docs.python.org/3/library/__main__.html 2) https://docs.python.org/3/using/cmdline.html#cmdoption-m The first link only says: """For a package, the same effect can be achieved by including a __main__.py module, the contents of which will be executed when the module is run with -m.""" ("-m" should actually use :option:`-m` to automatically link to the second URL.) The second link mentions __main__.py in two sentences: """Execute the Python code contained in script, which must be a filesystem path (absolute or relative) referring to either a Python file, a directory containing a __main__.py file, or a zipfile containing a __main__.py file.""" """If the script name refers to a directory or zipfile, the script name is added to the start of sys.path and the __main__.py file in that location is executed as the __main__ module.""" I think it would be better to expand the first link to state clearly what is __main__.py and what is its purpose. In addition, the section should clarify a few more things, e.g. when it should be used, what it should contain, if it's ok to have other __main__.py in the subpackages (e.g. test/__main__.py to run the tests with python -m package.test), how it interacts __init__.py (which one is executed first?). Perhaps it should also get a glossary entry and/or a short mention in the tutorial together with zip imports. In addition to the two links above, a Google search returns the stackoverflow question "What is __main__.py?" as first result, and a couple more related questions that could/should be answered by our docs. ---------- assignee: docs@python components: Documentation messages: 246719 nosy: docs@python, ethan.furman, ezio.melotti, nedbat priority: normal severity: normal stage: needs patch status: open title: Improve documentation about __main__.py type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24632> _______________________________________

9 16

[issue33550] Sigpipe handling issue should be documented
by Alfred Perlstein Aug. 24, 2018

Aug. 24, 2018

New submission from Alfred Perlstein <alfred(a)freebsd.org>: A common anti-pattern in python used to get rid of "ugly" brokenpipe messages is to set the SIGPIPE handler to SIG_DFL, this however will cause your program to seemingly randomly exit if it makes any socket connections during its lifetime. (see github PR for more info) ---------- assignee: docs@python components: Documentation messages: 316877 nosy: docs@python, splbio priority: normal pull_requests: 6597 severity: normal status: open title: Sigpipe handling issue should be documented type: behavior 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/issue33550> _______________________________________

3 3

[issue28206] signal.Signals not documented
by Samuel Colvin Aug. 23, 2018

Aug. 23, 2018

New submission from Samuel Colvin: As per discussion on typeshed pull request discussion (https://github.com/python/typeshed/pull/555) the "signal.Signals" enum is not documented but should be. See https://docs.python.org/3.5/library/signal.html. ---------- assignee: docs@python components: Documentation messages: 276979 nosy: Samuel Colvin, docs@python priority: normal severity: normal status: open title: signal.Signals not documented versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28206> _______________________________________

4 4