Mailman 3 March 2017 - docs

[issue12706] timeout sentinel in ftplib and poplib
by Senthil Kumaran Jan. 25, 2018

Jan. 25, 2018

New submission from Senthil Kumaran <senthil(a)uthcode.com>: - ftplib and poplib, has them as timeout=None, while they default to socket._GLOBAL_DEFAULT_TIMEOUT object. This is wrong; someone may pass None thinking it will trigger the default behaviour, and have nasty surprises. ---------- assignee: docs@python messages: 141740 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: timeout sentinel in ftplib and poplib type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12706> _______________________________________

5 7

[issue17799] settrace docs are wrong about "c_call" events
by Ned Batchelder Jan. 24, 2018

Jan. 24, 2018

New submission from Ned Batchelder: Looking into this Stack Overflow question: http://stackoverflow.com/questions/16115027/pythons-sys-settrace-wont-creat… Reading the code in c_eval.c and friends, it looks like "c_call" events are never passed to the trace function, only to the profile function. The docs are wrong and should be fixed. The setprofile docs simply point to settrace for details, so the text needs to accommodate both functions' needs. ---------- assignee: docs@python components: Documentation messages: 187406 nosy: docs@python, nedbat priority: low severity: normal status: open title: settrace docs are wrong about "c_call" events versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17799> _______________________________________

7 15

[issue15221] os.path.is*() may return False if path can't be accessed
by Giampaolo Rodola' Jan. 15, 2018

Jan. 15, 2018

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: It seems a doc fix is the best way to go, in which case I leave this one to a native English speaker: http://mail.python.org/pipermail/python-dev/2012-June/120788.html Alternatively a new 'strict' parameter has been proposed as a workaround: http://mail.python.org/pipermail/python-dev/2012-June/120800.html ---------- assignee: docs@python components: Documentation messages: 164307 nosy: christian.heimes, docs@python, eric.araujo, ezio.melotti, georg.brandl, giampaolo.rodola, ncoghlan priority: normal severity: normal status: open title: os.path.is*() may return False if path can't be accessed versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15221> _______________________________________

7 9

[issue11260] smtpd-as-a-script feature should be documented and should use argparse
by Xavier Morel Jan. 10, 2018

Jan. 10, 2018

New submission from Xavier Morel <xavier.morel(a)masklinn.net>: argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments. Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse). I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation. smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers). * The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden) * The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs * The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen * Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different: - running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1 - providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1) ---------- assignee: docs@python components: Documentation, Library (Lib) files: smtpd-to-argparse.diff keywords: patch messages: 128917 nosy: barry, docs@python, xmorel priority: normal severity: normal status: open title: smtpd-as-a-script feature should be documented and should use argparse versions: Python 3.3 Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11260> _______________________________________

8 18

[issue28942] await expressions in f-strings
by Adam Gregory Dec. 21, 2017

Dec. 21, 2017

New submission from Adam Gregory: Hi, I've been playing with f-strings, which seem like a great addition to the language. I noticed in the definition of f_expression that it can include any or_expr. As far as I understand, this includes "await" expressions, so I tried using await inside an f-string in a coroutine with CPython 3.6.0b4. This produces a SyntaxError. Should await be allowed in f-strings? I don't know if this is a bug or a documentation issue. Personally, I think it would be an occasionally useful feature - more so than yield, at least, which does work. Ref: https://docs.python.org/3.6/reference/lexical_analysis.html#formatted-strin… ---------- assignee: docs@python components: Documentation, asyncio messages: 282980 nosy: Adam Gregory, docs@python, gvanrossum, yselivanov priority: normal severity: normal status: open title: await expressions in f-strings versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28942> _______________________________________

5 8

[issue28697] asyncio.Lock, Condition, Semaphore docs don't mention `async with` syntax
by Ulrich Petri Dec. 20, 2017

Dec. 20, 2017

New submission from Ulrich Petri: The docs for asyncio's Lock, Condition and Semaphore should use the new clean `async with lock:` syntax instead of the older (and IMO rather ugly) `with (yield from lock):` version. ---------- assignee: docs@python components: Documentation, asyncio messages: 280861 nosy: docs@python, gvanrossum, ulope, yselivanov priority: normal severity: normal status: open title: asyncio.Lock, Condition, Semaphore docs don't mention `async with` syntax versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28697> _______________________________________

2 1

[issue22671] Typo in class io.BufferedIOBase docs
by gigaplastik Dec. 12, 2017

Dec. 12, 2017

New submission from gigaplastik: The online documentation for class io.BufferedIOBase states the following: "Besides, the read() method does not have a default implementation that defers to readinto()." According to the documentation for class io.RawIOBase (which the statement compares with) read() method actually defers to readall(), NOT readinto() as misleadingly stated. The same typo is present in help('io.BufferedIOBase') output and, very likely, in all 3.X line docs for this class. ---------- assignee: docs@python components: Documentation messages: 229677 nosy: docs@python, gigaplastik priority: normal severity: normal status: open title: Typo in class io.BufferedIOBase docs type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22671> _______________________________________

9 14

[issue29247] Document return value of epoll.poll
by Nathaniel Smith Dec. 11, 2017

Dec. 11, 2017

New submission from Nathaniel Smith: The documentation for select.epoll.poll doesn't document the return value at all, which is somewhat important information :-) I think it's a list of (fd, eventmask) tuples? https://docs.python.org/3.7/library/select.html#select.epoll.poll ---------- assignee: docs@python components: Documentation messages: 285285 nosy: docs@python, njs priority: normal severity: normal status: open title: Document return value of epoll.poll versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29247> _______________________________________

5 6

[issue29879] typing.Text not available in python 3.5.1
by Charles Bouchard-Légaré Nov. 26, 2017

Nov. 26, 2017

New submission from Charles Bouchard-Légaré: The real issue here is that this is not documented in Doc/library/typing.rst. ---------- assignee: docs@python components: Documentation messages: 289985 nosy: Charles Bouchard-Légaré, docs@python priority: normal severity: normal status: open title: typing.Text not available in python 3.5.1 versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29879> _______________________________________

5 11

[issue28951] re.flags not documented in Module Contents as promised.
by kevin Nov. 16, 2017

Nov. 16, 2017

New submission from kevin: In the online documentation of module re (https://docs.python.org/3.5/library/re.html) under 6.2.1. Regular Expression Syntax for item (?aiLmsux) we are promised "The flags are described in Module Contents" but no description is found there. In fact a number of other references are found to flags, but no description of the individual flags. AFAICT the closest thing to a description is found at the original reference -- at least it gives a code and name for each one. ---------- assignee: docs@python components: Documentation messages: 283034 nosy: 4Dummies, docs@python priority: normal severity: normal status: open title: re.flags not documented in Module Contents as promised. type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28951> _______________________________________

3 10