Mailman 3 November 2015 - docs

[issue21864] Error in documentation of point 9.8 'Exceptions are classes too'
by Peibolvig 06 Nov '16

06 Nov '16

New submission from Peibolvig: At point 9.8 of the 3.4.1 version documentation, ( https://docs.python.org/3/tutorial/classes.html#exceptions-are-classes-too ), there is an example of two ways to use the 'raise' statement: raise Class raise Instance The next two lines, state: "In the first form, Class must be an instance of type or of a class derived from it. The first form is a shorthand for: raise Class()" That only says something about the first form twice. I think that the correct way would be: "In the first form, Class must be an instance of type or of a class derived from it. The SECOND form is a shorthand for: raise Class()" ---------- assignee: docs@python components: Documentation messages: 221511 nosy: Peibolvig, docs@python priority: normal severity: normal status: open title: Error in documentation of point 9.8 'Exceptions are classes too' versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21864> _______________________________________

6 9

[issue21501] submitting mmap example for use in documentation
by Steve Foley 06 Nov '16

06 Nov '16

New submission from Steve Foley: Hello, I would like to submit an example for the mmap docs page. It demonstrates the use of shared memory and message passing between processes. Thanks! -------------------- import mmap, os, select NUM_CHILDREN = 30 MSG_LEN = 8 BUF_LEN = NUM_CHILDREN * MSG_LEN buf = mmap.mmap(-1, BUF_LEN) p = select.poll() def write_buffer(i): msg = '%s\t%d\n' % (i, os.getpid()) offset = MSG_LEN * i buf.seek(offset) buf.write(msg) def child(i, pipeout): write_buffer(i) os.write(pipeout, 'OK\0'.encode()) os._exit(0) def fork(i, p): pipein, pipeout = os.pipe() if os.fork() == 0: child(i, pipeout) else: p.register(pipein) def loop(msgs, p): while msgs: for fd, event in p.poll(): p.unregister(fd) msgs = msgs - 1 for i in range(NUM_CHILDREN): fork(i, p) loop(NUM_CHILDREN, p) buf.seek(0) print buf.read(BUF_LEN) ---------- assignee: docs@python components: Documentation messages: 218478 nosy: docs@python, hudson priority: normal severity: normal status: open title: submitting mmap example for use in documentation type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21501> _______________________________________

2 2

[issue25152] venv documentation doesn't tell you how to specify a particular version of python
by Laura Creighton 28 Oct '16

28 Oct '16

New submission from Laura Creighton: https://docs.python.org/3/library/venv.html nowhere explicitly states how you are supposed to get a venv with a particular python version. Users of virtualenv will be looking for a -p option. The doc says: "Creation of virtual environments is done by executing the pyvenv script:" which undoubtably works if you _have_ a pyenv script, but I don't have one. It is nowhere stated where I should find one. Fortunately, I can also run things as some_python_version -m venv myvenv This, everybody is able to do. (However, it may not work, see issue 25151 -- but forget that for now.) This is something that everybody ought to be able to do. Thus I propose either deleting the mention of pyenv, (if it is exactly equivalent to running python -m venv) or expanding the section, indicating where the script lives, and why you might want to run it instead of python -m venv. Then, before the line: The command, if run with -h, will show the available options: add the line: The version of python used in the venv is determined at this time. If the default version of python is not the one desired, use: /path/to/the/python/I/want -m venv myenv instead. (Plus, if there is a way to do this with pyenv, then list that part here). ---------- assignee: docs@python components: Distutils, Documentation messages: 250891 nosy: docs@python, dstufft, eric.araujo, lac priority: normal severity: normal status: open title: venv documentation doesn't tell you how to specify a particular version of python versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25152> _______________________________________

8 18

[issue18789] XML Vunerability Table Unclear
by Joe Tennies 13 Oct '16

13 Oct '16

New submission from Joe Tennies: EASY This is an issue with the 2.x and 3.x documentation. http://docs.python.org/3.2/library/xml.html#xml-vulnerabilities http://docs.python.org/dev/library/xml.html#xml-vulnerabilities http://docs.python.org/2/library/xml.html#xml-vulnerabilities This section has a table with a bunch of Trues and Falses. This is a bit confusing, especially for something that is trying to describe security concerns. After looking at the table, I'm pretty sure that True means vunerable (only due to the (1), (2), & (3) comments), but it's not clear. All that is needed is a heading stating "Vunerable", or change the "True" to "Vunerable" and "False" to "Not Vunerable" (probably V and NV w/ a legend). ---------- assignee: docs@python components: Documentation messages: 195691 nosy: docs@python, joe-tennies priority: normal severity: normal status: open title: XML Vunerability Table Unclear type: security versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18789> _______________________________________

8 12

[issue21443] asyncoio logging documentation clarifications.
by steven Michalske 13 Oct '16

13 Oct '16

New submission from steven Michalske: The asyncio documentation should comment on how to mute and increase some of it's logging. 18.5.7.3. Logging The asyncio module logs information with the logging module in the logger 'asyncio'. Adding a bit of text that mentions the following line would be great. """ The default verbosity will include messages at logging.INFO level. To modify the verbosity of asyncio logging add a similar line to your application. `logging.getLogger('asyncio').setLevel(logging.WARNING)` """ Note: While this is clear to active users of the logging module, it is not clear to novices, who want INFO in their applications but not from asyncio. ---------- assignee: docs@python components: Documentation messages: 217952 nosy: docs@python, hardkrash priority: normal severity: normal status: open title: asyncoio logging documentation clarifications. type: enhancement versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21443> _______________________________________

6 7

[issue15013] smtplib: add low-level APIs to doc?
by Sandro Tosi 13 Oct '16

13 Oct '16

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: In the smtplib doc I read: Low-level methods corresponding to the standard SMTP/ESMTP commands HELP, RSET, NOOP, MAIL, RCPT, and DATA are also supported. Normally these do not need to be called directly, so they are not documented here. For details, consult the module code. Well, I think the documentation should include also those low-level apis (maybe in a separate subsection). >From my POV, smtplib should implement the protocol, and give the programmers the tools to use the protocol as they prefers, and as a plus some companion methods to easy the most common operations. I'm in need to use the low-level apis, and not finding them in the doc is a disservice to me (with my user hat on ;)) and just say "go read the source" is kinda rude and unexpected. What do you think? ---------- assignee: docs@python components: Documentation messages: 162395 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: smtplib: add low-level APIs to doc? versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15013> _______________________________________

4 4

[issue10415] readline.insert_text documentation incomplete
by Justin Lebar 01 Oct '16

01 Oct '16

New submission from Justin Lebar <justin.lebar(a)gmail.com>: The readline documentation currently says: > readline.insert_text(string) > Insert text into the command line. But as far as I can tell, readline.insert_text() does something only when called from startup_hook or pre_input_hook. Here's an example of someone using the module in a way that works: http://swapoff.org/svn/cly/tags/0.7/cly/interactive.py ---------- assignee: docs@python components: Documentation messages: 121178 nosy: Justin.Lebar, docs@python priority: normal severity: normal status: open title: readline.insert_text documentation incomplete versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10415> _______________________________________

6 7

[issue21903] ctypes documentation MessageBoxA example produces error
by Dan O'Donovan 28 Sep '16

28 Sep '16

New submission from Dan O'Donovan: There is an example in the ctypes python3 documentation for producing a native Windows MessageBoxA https://docs.python.org/3.3/library/ctypes.html#ctypes.PYFUNCTYPE Try as I might, I cannot get this example to run under python 3 (it is in the python3 documentation) - it always produces an error Traceback (most recent call last): File "<stdin>", line 1, in <module> ctypes.ArgumentError: argument 2: <class 'TypeError'>: wrong type I apologise for not attaching a fix, I have tried and cannot find one. ---------- assignee: docs@python components: Documentation messages: 222088 nosy: Dan.O'Donovan, docs@python priority: normal severity: normal status: open title: ctypes documentation MessageBoxA example produces error type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21903> _______________________________________

4 5

[issue20100] epoll docs are not clear with regards to CLOEXEC.
by R. David Murray 27 Sep '16

27 Sep '16

New submission from R. David Murray: http://docs.python.org/dev/library/select.html#select.epoll documents the EPOLL_CLOEXEC flag as something you can specify that makes the file descriptor be closed on exec. But then it goes on to say that the file descriptor is non-inheritable. So is the flag useless and should be removed from the docs, or is the documentation just unclear as to its purpose? Or, conversely, do we need a way to say that the file descriptor should *not* be closed on exec? ---------- assignee: docs@python components: Documentation messages: 207121 nosy: docs@python, haypo, r.david.murray priority: normal severity: normal stage: needs patch status: open title: epoll docs are not clear with regards to CLOEXEC. type: behavior versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20100> _______________________________________

6 13

[issue15941] Time module: effect of time.timezone change
by Terry J. Reedy 15 Sep '16

15 Sep '16

New submission from Terry J. Reedy: "time.timezone The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK)." Quite aside from #9305 (UTC is not a place), this does not specify the effect of setting this attribute. It does not change the output of localtime, asctime, or ctime (on Windows). Does is affect anything else? strftime? If setting it has no effect, the doc should say so. (And then perhaps it should be made read-only in the future, as setting it expecting an effect would be a bug.) ---------- assignee: docs@python components: Documentation messages: 170450 nosy: belopolsky, docs@python, haypo, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Time module: effect of time.timezone change versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15941> _______________________________________

2 5