Mailman 3 March 2017 - docs

[issue24356] venv documentation incorrect / misleading
by Graham Oliver July 28, 2018

July 28, 2018

New submission from Graham Oliver: See my question here https://groups.google.com/forum/#!topic/comp.lang.python/BUmyc_hzAsA In particular Carl Meyer's response https://groups.google.com/d/msg/comp.lang.python/BUmyc_hzAsA/-cT-N-g_LL4J I am not sure what is possible with venv but I would suggest that the statement 'allowing creation of environments with various Python versions' needs to be clarified and / or altered. Thanks Graham ---------- assignee: docs@python components: Documentation messages: 244618 nosy: Graham.Oliver, docs@python priority: normal severity: normal status: open title: venv documentation incorrect / misleading versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24356> _______________________________________

8 15

[issue27717] sqlite documentation bug
by Eyal Mor July 27, 2018

July 27, 2018

New submission from Eyal Mor: In the SQlite module documentation there a code section showing how to securely use the sqlite.execute method. The problem with this code section is that just from a glance, without reading the paragraph before, or the comments in the section, users could use the insecure version. It would be better if only a secure example would be in the code section. https://docs.python.org/2/library/sqlite3.html Section: # Never do this -- insecure! symbol = 'RHAT' c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol) # Do this instead t = ('RHAT',) c.execute('SELECT * FROM stocks WHERE symbol=?', t) print c.fetchone() # Larger example that inserts many records at a time purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00), ('2006-04-05', 'BUY', 'MSFT', 1000, 72.00), ('2006-04-06', 'SELL', 'IBM', 500, 53.00), ] c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases) ---------- assignee: docs@python components: Documentation files: Screen Shot 2016-08-09 at 3.28.05 PM.png messages: 272238 nosy: Eyal Mor, docs@python priority: normal severity: normal status: open title: sqlite documentation bug type: security versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file44056/Screen Shot 2016-08-09 at 3.28.05 PM.png _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27717> _______________________________________

3 3

[issue12743] C API marshalling doc contains XXX
by JJeffries July 26, 2018

July 26, 2018

New submission from JJeffries <jamesjeffries1(a)gmail.com>: The Python C API manual page for data marshaling contains the following paragraph. XXX What about error detection? It appears that reading past the end of the file will always result in a negative numeric value (where that’s relevant), but it’s not clear that negative values won’t be handled properly when there’s no error. What’s the right way to tell? Should only non-negative values be written using these routines? I suggest that the XXX should be removed as it is unclear why it's there. Patch to follow in the next couple of days if others agree. ---------- assignee: docs@python components: Documentation messages: 141959 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: C API marshalling doc contains XXX _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12743> _______________________________________

7 13

[issue22374] Replace contextmanager example and improve explanation
by Terry J. Reedy July 26, 2018

July 26, 2018

New submission from Terry J. Reedy: https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager The current html contextmanager example is 'not recommended' for actual use, because there are better ways to accomplish the same goal. To me, is also unsatifactory in that the context management is only metaphorical (conceptual) and not actual. I propose the following as a replacement. It actually manages context and is, I believe, both useful and currently* the best way to accomplish the goal of temporarily monkeypatching a module, It was directly inspired by #20752, see msg226657, though there have been other issues where monkeypatching as a solution has been discussed. --- from contextlib import contextmanager import itertools as its @contextmanager def mp(ob, attr, new): old = getattr(ob, attr) setattr(ob, attr, new) yield setattr(ob, attr, old) def f(): pass print(its.count, its.cycle) with mp(its, 'count', f), mp(its, 'cycle', f): print(its.count, its.cycle) print(its.count, its.cycle) # <class 'itertools.count'> # <function f at 0x00000000035A91E0> # <class 'itertools.count'> --- I am aware that the above does not follow the current style, which I dislike, of confusingly mixing together batch file code and interactive input code. I think the above is how the example should be written. It would work even better if Sphinx gave comment lines a different background color. (A '##' prefix could be used to differentiate code comments from commented-out output lines.) In the same section, I find the following paragraph a bit confusing (perhaps is tries to say too much): "contextmanager() uses ContextDecorator so the context managers it creates can be used as decorators as well as in with statements. When used as a decorator, a new generator instance is implicitly created on each function call (this allows the otherwise “one-shot” context managers created by contextmanager() to meet the requirement that context managers support multiple invocations in order to be used as decorators)." I am guessing that this means, among other things, that ContextDecorator is necessary and sufficient to use mp twice in one with statement. I intentionally added the double use to the example to make this possibility clear. * The only better way I know of would be if mp (spelled out as 'monkeypatch' were considered useful enough to be added to contextlib. ---------- assignee: docs@python components: Documentation messages: 226661 nosy: docs@python, ncoghlan, terry.reedy priority: normal severity: normal status: open title: Replace contextmanager example and improve explanation versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22374> _______________________________________

5 5

[issue28677] difficult to parse sentence structure in "When an instance attribute is referenced that isn't a data attribute"
by Viorel Tabara July 25, 2018

July 25, 2018

New submission from Viorel Tabara: Method objects are explained at: https://docs.python.org/3/tutorial/classes.html#method-objects I'd like to suggest a change from: When an instance attribute is referenced that isn’t a data attribute, its class is searched. to something along this line: When an instance attribute --- that isn’t a data attribute --- is referenced, the instance parent class will be searched. ---------- assignee: docs@python components: Documentation messages: 280671 nosy: docs@python, viorel priority: normal severity: normal status: open title: difficult to parse sentence structure in "When an instance attribute is referenced that isn't a data attribute" type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28677> _______________________________________

8 14

[issue24459] Mention PYTHONFAULTHANDLER in the man page
by Antony Lee July 9, 2018

July 9, 2018

New submission from Antony Lee: The man page doesn't mention PYTHONFAULTHANDER in the list of environment variables (I haven't thoroughly checked that everyone else is there, either). I would also suggest reordering the environment variables in alphabetical order. ---------- assignee: docs@python components: Documentation messages: 245422 nosy: Antony.Lee, docs@python priority: normal severity: normal status: open title: Mention PYTHONFAULTHANDLER in the man page versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24459> _______________________________________

8 33

[issue28710] Sphinx incompatible markup in configparser.ConfigParser.
by Patrick Lehmann June 18, 2018

June 18, 2018

New submission from Patrick Lehmann: Why does e.g. configparser.ConfigParser contain doc strings with Sphinx incompatible markup? The markup starts with back-tick, but ends with a single quote. Example: https://github.com/python/cpython/blob/master/Lib/configparser.py?ts=2#L26 Sphinx writes these messages: D:\git\PoC\py\lib\ExtendedConfigParser\__init__.py:docstring of lib.ExtendedConfigParser.ExtendedConfigParser.read_file:3: WARNING: Inline interpreted text or phrase reference start-str ing without end-string. Note: ExtendedConfigParser is class derived from configparser.ConfigParser. Inherited methods get documented too. ------------------------ Btw. I have some improvements for this class, how can I contribute them? Who is the maintainer for this class? Please contact me: Patrick.Lehmann(a)tu-dresden.de The improved version is available at GitHub: https://github.com/Paebbels/ExtendedConfigParser?ts=2 ---------- assignee: docs@python components: Documentation messages: 280907 nosy: Patrick Lehmann, docs@python priority: normal severity: normal status: open title: Sphinx incompatible markup in configparser.ConfigParser. versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28710> _______________________________________

6 30

[issue24978] Contributing to Python 2x and 3x Documentation. Translation to Russian.
by Eugene June 16, 2018

June 16, 2018

New submission from Eugene: I am very much begging pardon if this is not the place to ask for, but.. I would like to make a thorough translation of the official Library Reference and the beginners guide to Python 2.x 3.x in Russian language. I am aware this type of translation will be placed at https://wiki.python.org/moin/RussianLanguage as current https://docs.python.org/2/ does not allow changing language. I am pretty much aware the translation should not sound any differently from the original in terms of its style, form and overall attitude. And I would also like to know, if possible, can this link be promoted somewhere at python.org. I am not in the slightest have the intentions of promoting in anywhere but in the place where most russian programmers could most definitely find it - at the oficial Python website. Kind regards, Evgeniy. ---------- assignee: docs@python components: Documentation messages: 249478 nosy: docs@python, overr1de priority: normal severity: normal status: open title: Contributing to Python 2x and 3x Documentation. Translation to Russian. type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24978> _______________________________________

6 5

[issue22571] Remove import * recommendations and examples in doc?
by Terry J. Reedy June 16, 2018

June 16, 2018

New submission from Terry J. Reedy: PEP 8 recommends against 'from mod import *' because it makes reading harder and is bad for code analysis. My experience with retrofitting tests to idlelib modules with tkinter * imports is that it also makes testing harder since the testing strategy depends on the specific tkinter objects actually used. So either an explicit list ('from tkinter import x, y, z') or a searchable prefix ('tk.') makes testing easier. Some time ago, 'from tkinter import *' was changed to 'import tkinter as tk' in the tkinter doc examples, though *not* the text. ##10031 changed the import section of the FAQ to "remove the advice to use "from ... import *" with some modules" (from the commit message). Should we finish the job? Or leave the issue to individual chapter authors? Here is the edited result of grepping 'import *' in ...\py34\Doc\*.rst with Idle. F:\Python\dev\4\py34\Doc\distutils\apiref.rst: 1289: This module is safe to use in ``from ... import *`` mode; it only exports F:\Python\dev\4\py34\Doc\library\cmd.rst: 234: from turtle import * F:\Python\dev\4\py34\Doc\library\collections.abc.rst: 14: from collections import * F:\Python\dev\4\py34\Doc\library\collections.rst: 11: from collections import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 54: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 86: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 320: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 562: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 671: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 695: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 714: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 914: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 1074: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\ctypes.rst: 1122: >>> from ctypes import * F:\Python\dev\4\py34\Doc\library\decimal.rst: 20: from decimal import * F:\Python\dev\4\py34\Doc\library\decimal.rst: 56: >>> from decimal import * F:\Python\dev\4\py34\Doc\library\decimal.rst: 125: >>> from decimal import * F:\Python\dev\4\py34\Doc\library\difflib.rst: 13: from difflib import * F:\Python\dev\4\py34\Doc\library\itertools.rst: 12: from itertools import * F:\Python\dev\4\py34\Doc\library\stat.rst: 104: from stat import * F:\Python\dev\4\py34\Doc\library\statistics.rst: 13: from statistics import * F:\Python\dev\4\py34\Doc\library\struct.rst: 313: >>> from struct import * F:\Python\dev\4\py34\Doc\library\tkinter.rst: 63: from tkinter import * F:\Python\dev\4\py34\Doc\library\tkinter.rst: 580: from tkinter import * F:\Python\dev\4\py34\Doc\library\tkinter.tix.rst: 60: from tkinter.constants import * F:\Python\dev\4\py34\Doc\library\tkinter.ttk.rst: 38: from tkinter import * F:\Python\dev\4\py34\Doc\library\tkinter.ttk.rst: 39: from tkinter.ttk import * F:\Python\dev\4\py34\Doc\library\turtle.rst: 11: from turtle import * F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 102: >>> from fibo import * F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 461: Now what happens when the user writes ``from sound.effects import *``? Ideally, F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 470: list of module names that should be imported when ``from package import *`` is F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 479: This would mean that ``from sound.effects import *`` would import the three F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 482: If ``__all__`` is not defined, the statement ``from sound.effects import *`` F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 493: from sound.effects import * F:\Python\dev\4\py34\Doc\tutorial\modules.rst: 501: patterns when you use ``import *``, it is still considered bad practise in F:\Python\dev\4\py34\Doc\tutorial\stdlib2.rst: 372: >>> from decimal import * I removed the reference hits that simply explain. I have not looked at whether the tutorial goes beyond explanation, but should this even be mentioned in so many places? ---------- assignee: docs@python components: Documentation messages: 228734 nosy: docs@python, georg.brandl, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Remove import * recommendations and examples in doc? versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22571> _______________________________________

5 5

[issue27461] Optimize PNGs
by Ville Skyttä June 16, 2018

June 16, 2018

New submission from Ville Skyttä: Running PNGs through zopflipng makes them smaller, with no drawbacks. This patch was done with zopflipng version 1.0.1 with the -m option, and decreases the in-tree total size size of all *.png by almost 100KiB. $ find -name "*.png" | xargs du -bc | tail -n 1 # before 291101 total $ find -name "*.png" | xargs du -bc | tail -n 1 # after 194639 total ---------- assignee: docs@python components: Documentation files: pngs.patch keywords: patch messages: 269929 nosy: docs@python, scop priority: normal severity: normal status: open title: Optimize PNGs type: enhancement Added file: http://bugs.python.org/file43653/pngs.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27461> _______________________________________

3 6