Mailman 3 November 2015 - docs

[issue12743] C API marshalling doc contains XXX
by JJeffries 27 Jul '18

27 Jul '18

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 26 Jul '18

26 Jul '18

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

[issue24459] Mention PYTHONFAULTHANDLER in the man page
by Antony Lee 09 Jul '18

09 Jul '18

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

[issue24978] Contributing to Python 2x and 3x Documentation. Translation to Russian.
by Eugene 16 Jun '18

16 Jun '18

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 16 Jun '18

16 Jun '18

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

[issue17286] Make subprocess handling text output with universal_newlines more obious
by Baptiste Lepilleur 11 Jun '18

11 Jun '18

New submission from Baptiste Lepilleur: It tooks me a while to figure out that using universal_newlines was the solution to "tell" subprocess that I wanted text string output instead of byte string. A search on stackoverflow shows that this issue is common and the solution nearly unknown (answer is usually to decode the byte string manually)... Because dealing with text output is IMHO the most common use case, the subprocess documentation should make it easier to "find" the recipe. I would suggest changing the documentation so that the universal_newlines is made obvious as it is very important: 1) the first /bin/vikings example be modified to show the use of this flag (at the top of the documentation, most people copy/past that): >>> p = subprocess.Popen(args, universal_newlines=True) # Success! and at a small comment below the example to explain that flag 2) change other example similarly when that make sense, IMHO: - ifconfig example - one of the subprocess.check_output example - subprocess.check_output() example, consider separating the byte string / text string example for increased visibility 3) consider adding a section with an obvious title "Dealing with binary and text input/output", providing examples and pointer to the correct documentation (I would place it after the convenience functions section for visibility). I think this would help attracting "eye" on this large piece of documentation. ---------- assignee: docs@python components: Documentation messages: 182872 nosy: Baptiste.Lepilleur, docs@python priority: normal severity: normal status: open title: Make subprocess handling text output with universal_newlines more obious type: enhancement versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17286> _______________________________________

5 5

[issue23495] The writer.writerows method should be documented as accepting any iterable (not only a list)
by Steven Barker 02 Jun '18

02 Jun '18

New submission from Steven Barker: The documentation for the csv.writer.writerows method says that it expects "a list of row objects", when it really will accept any iterable that yields rows (such as a generator). While it's often nice for code to be more accepting than the documented requirements, I think the docs in this case should state that writerows() expects an iterable, rather than misinforming users that a list is required. This documentation issue was brought up in a Stack Overflow question here: http://stackoverflow.com/questions/28636848/csv-writer-writerows-takes-iter… I expect the necessary documentation patch will be pretty trivial, and if nobody else gets to it first, I will try to provide one when I have enough time to update my cpython checkout (not soon, alas). ---------- assignee: docs@python components: Documentation messages: 236328 nosy: Steven.Barker, docs@python priority: normal severity: normal status: open title: The writer.writerows method should be documented as accepting any iterable (not only a list) type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23495> _______________________________________

9 16

[issue19950] Document that unittest.TestCase.__init__ is called once per test
by Claudiu.Popa 19 May '18

19 May '18

New submission from Claudiu.Popa: I was surprised that in the following __init__ is actually called once per test function, although nothing in documentation implied so. a.py ------ import unittest class A(unittest.TestCase): def __init__(self, *args, **kwargs): print('called only once!') super().__init__(*args, **kwargs) def test(self): self.assertEqual(1, 1) def test2(self): self.assertEqual(2, 2) if __name__ == '__main__': unittest.main() $ python a.py called only once! called only once! .. ---------------------------------------------------------------------- Ran 2 tests in 0.001s OK The attached patch adds a note regarding this behaviour for the TestCase class. ---------- assignee: docs@python components: Documentation files: unittest_init.patch keywords: patch messages: 205864 nosy: Claudiu.Popa, docs@python, michael.foord priority: normal severity: normal status: open title: Document that unittest.TestCase.__init__ is called once per test type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file33086/unittest_init.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19950> _______________________________________

8 15

[issue13525] Tutorial: Example of Source Code Encoding triggers error
by Nicolas Goutte 09 May '18

09 May '18

New submission from Nicolas Goutte <nicolas.goutte(a)extragroup.de>: Current Behaviour The tutorial of Python 3.2.x has an example to set an encoding in a source file: http://docs.python.org/py3k/tutorial/interpreter.html#source-code-encoding It explains to set the following line at the start of the source code: # -*- coding: cp-1252 -*- However when done exactly so, Python raises the following exception: SyntaxError: encoding problem: with BOM The problem seems to be that Python knows Windows codepage 1252 as windows-1252 (its IANA charset name, see http://www.iana.org/assignments/charset-reg/windows-1252 ) or alternatively as cp1252 (without dash) but not as cp-1252 (with dash). As this is an example in the tutorial is particularly problematic, as users might not understand how to do it correctly. This is still the case in the tutorial of Python 3.3 alpha: http://docs.python.org/dev/tutorial/interpreter.html#source-code-encoding Expected Behaviour The tutorial should give a correct example, for example with: # -*- coding: windows-1252 -*- Alternatively a totally other example as for Python 2.7 would be nice too: http://docs.python.org/tutorial/interpreter.html#source-code-encoding Notes: I have tested this with following Python implementations: - Python 3.2.1 (openSUSE 12.1) on Linux - Python 3.2.2 on Windows 7 SP1 64 Bits - Python 3.2.2 on MacOS 10.5.8 (Always on the command line; I have not tested in IDLE.) ---------- assignee: docs@python components: Documentation files: cp_1252broken.py messages: 148798 nosy: docs@python, nicolasg priority: normal severity: normal status: open title: Tutorial: Example of Source Code Encoding triggers error versions: Python 3.2 Added file: http://bugs.python.org/file23840/cp_1252broken.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13525> _______________________________________

5 14

[issue20722] newline is (partially) independent of universal newlines; needs to be made more clear in docs
by Devin Jeanpierre 03 May '18

03 May '18

New submission from Devin Jeanpierre: http://docs.python.org/3.4/library/functions.html#open says "newline controls how universal newlines mode works (it only applies to text mode)." My reading of this when I saw it was that newline= doesn't do anything unless universal newlines mode is enabled. This is untrue, and you can infer it's untrue from the following lines, but then the docs appear to contradict themselves. Please fix to say something more along the lines of "newline controls how newlines are read and written. It only applies to text mode." The interactions with universal newlines mode are explained in the following text, so they don't need to be called out upfront. newline does more than just that. ---------- assignee: docs@python components: Documentation messages: 211854 nosy: Devin Jeanpierre, docs@python priority: normal severity: normal status: open title: newline is (partially) independent of universal newlines; needs to be made more clear in docs versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20722> _______________________________________

3 2