Mailman 3 March 2017 - docs

[issue29013] zipfile: inconsistent doc for ZIP64 file size
by Monte Davidoff Sept. 21, 2018

Sept. 21, 2018

New submission from Monte Davidoff: The documentation for the zipfile module, https://docs.python.org/3.5/library/zipfile.html, contains inconsistent descriptions of the maximum size of a ZIP file when allowZip64 is False. The second paragraph in the zipfile module documentation states: "It can handle ZIP files that use the ZIP64 extensions (that is ZIP files that are more than 4 GiB in size)." Later on, in the description of the zipfile.ZipFile class, it says: "If allowZip64 is True (the default) zipfile will create ZIP files that use the ZIP64 extensions when the zipfile is larger than 2 GiB." The two sizes (4 GiB and 2 GiB) should be the same. According to https://en.wikipedia.org/wiki/Zip_(file_format)#ZIP64, 4 GiB is the correct value. There is a similar problem in the 2.7.13 documentation, https://docs.python.org/2.7/library/zipfile.html. ---------- assignee: docs@python components: Documentation messages: 283597 nosy: docs@python, mndavidoff priority: normal severity: normal status: open title: zipfile: inconsistent doc for ZIP64 file size versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29013> _______________________________________

4 9

[issue19431] Document PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError()
by STINNER Victor Sept. 20, 2018

Sept. 20, 2018

New submission from STINNER Victor: (Copy of an email) Georg Brandl via python.org Am 29.10.2013 01:19, schrieb victor.stinner: > http://hg.python.org/cpython/rev/4ef4578db38a > changeset: 86715:4ef4578db38a > user: Victor Stinner <victor.stinner(a)gmail.com> > date: Tue Oct 29 01:19:37 2013 +0100 > summary: > Issue #18408: Add a new PyFrame_FastToLocalsWithError() function to handle > exceptions when merging fast locals into f_locals of a frame. > PyEval_GetLocals() now raises an exception and return NULL on failure. You'll have to either make this private or document it. ---------- assignee: docs@python components: Documentation messages: 201618 nosy: docs@python, georg.brandl, haypo, pitrou priority: normal severity: normal status: open title: Document PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError() versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19431> _______________________________________

4 15

[issue21702] asyncio: remote_addr of create_datagram_endpoint() is not documented
by STINNER Victor Sept. 19, 2018

Sept. 19, 2018

New submission from STINNER Victor: See issue #21701 for a recent issue about this parameter. ---------- assignee: docs@python components: Documentation, asyncio messages: 220147 nosy: ariddell, docs@python, gvanrossum, haypo, yselivanov priority: normal severity: normal status: open title: asyncio: remote_addr of create_datagram_endpoint() is not documented versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21702> _______________________________________

1 1

[issue25296] Simple End-of-life guide covering all unsupported versions
by Nick Coghlan Sept. 15, 2018

Sept. 15, 2018

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

Sept. 14, 2018

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

[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

[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

[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

[issue18925] select.poll.modify is not documented
by Giampaolo Rodola' Aug. 19, 2018

Aug. 19, 2018

New submission from Giampaolo Rodola': It was introduced in Python 2.6: http://bugs.python.org/issue1657 Will commit a patch soon. ---------- assignee: docs@python components: Documentation messages: 196953 nosy: docs@python, giampaolo.rodola priority: normal severity: normal status: open title: select.poll.modify is not documented versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18925> _______________________________________

4 3