Mailman 3 March 2017 - docs

[issue17286] Make subprocess handling text output with universal_newlines more obious
by Baptiste Lepilleur June 11, 2018

June 11, 2018

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 June 2, 2018

June 2, 2018

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

[issue29428] Doctest documentation unclear about multi-line fixtures
by Jim DeLaHunt May 21, 2018

May 21, 2018

New submission from Jim DeLaHunt: I just had a problem with doctests. It manifested as an error that occurred when I did >>> import StringIO in my doctest. After some investigation, I realised that my actual problem was that the doctest library documentation https://docs.python.org/3/library/doctest.html left me unclear about three aspects of multi-line doctest fixtures. 1. There is no example of a multiple-line doctest fixture: specifically, a fixture which involves at least one line to set up state, and another line to be the example that tested. I suggest adding such an example as a new section, "26.3.2. Usage: multi-line tests". Note that the example in 26.3.3.2 doesn't count: that is a Compound Statement, and I'm talking about a test consisting of multiple interactive statements. 2. Section "26.3.3.2. How are Docstring Examples Recognized?" does not talk about when to use a PS1 prefix (>>>) and when to use a PS2 prefix (...). It should say to use the PS1 at the start of each Python "interactive statement", that is, a statement list ending with a newline, or a Compound Statement. And, to use the PS2 to prefix each continuing line within a Compound Statement. 3. Section "26.3.3.3. What’s the Execution Context?" is not clear about the crucial difference between state that accumulates within a single docstring from Example to Example, and that is reset from one docstring to another. The phrase "so that one test in M can’t leave behind crumbs that accidentally allow another test to work" can be interpreted as applying within a single docstring. The phrase "names defined earlier in the docstring being run" is easy to miss. A StackOverflow Question and Answer describing my problem and my insight about what the library documentation didn't tell me is at http://stackoverflow.com/questions/41070547/why-is-importing-a-module-break… . A blog post of mine, a source for documentation improvements, is at http://blog.jdlh.com/en/2017/01/31/multi-line-doctests/ . I actually encountered this problem in a Python 2.7 context, with https://docs.python.org/2/library/doctest.html . But it also applies to Python 3.6 https://docs.python.org/3/library/doctest.html and to the current dev https://docs.python.org/dev/library/doctest.html . In the spirit of fixing the new stuff first, I am filing this issue against Python 3.7. Unless someone tells me otherwise, I'll get around to filing similar issues against Python 3.6 and Python 2.7. Then it's my intention to write improvements to the documentation for Python 3.7, 3.6, and 2.7, and submit each of those. It looks like they will be pretty similar, because the library documentation is pretty similar in each version. I'm new to Python issue filing and doc fixing, so I would appreciate correction if (when?) I start to blunder. ---------- assignee: docs@python components: Documentation messages: 286843 nosy: JDLH, docs@python priority: normal severity: normal status: open title: Doctest documentation unclear about multi-line fixtures type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29428> _______________________________________

4 14

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

May 19, 2018

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

[issue26701] Documentation for int constructor mentions __int__ but not __trunc__
by Robert Smallshire May 10, 2018

May 10, 2018

New submission from Robert Smallshire: The documentation for the int(x) constructor explains that if possible, it delegates to x.__int__(). The documentation does not explain that there is a fallback to x.__trunc__() if x.__int__() is not available. The only mention of __trunc__ in the Python documentation is in the entry for math.trunc; the documentation for the numbers module does not describe the underlying special methods. Given that all Real numbers are required to implement __trunc__ but only Integral subclasses are required to implement __int__ this could be important to implementers of other Real types, although in practice I imagine that most Real types will implement __int__ as float does. ---------- assignee: docs@python components: Documentation messages: 262941 nosy: Robert Smallshire2, docs@python priority: normal severity: normal status: open title: Documentation for int constructor mentions __int__ but not __trunc__ type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26701> _______________________________________

6 22

[issue13525] Tutorial: Example of Source Code Encoding triggers error
by Nicolas Goutte May 9, 2018

May 9, 2018

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 May 3, 2018

May 3, 2018

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

[issue24027] IMAP library lacks documentation about expected parameter types
by Pablo April 21, 2018

April 21, 2018

New submission from Pablo: I used the IMAP library and I feel it lacks a lot of documentation regarding types and encoding. Example: IMAP4.list([directory[, pattern]]): It doesn't state if it expects the directory argument to be an string (unicode) or a imap_utf7 encoded string or bytes. It also expects names with spaces to be between double quotation marks and it doesn't state that it returns a bytes raw output. This is valid for every function that receives a directory or mailbox argument. Also for most return values. Documentation aside, I think it would be a nice improvement in the implementation to add an imap_utf7 convertion function, and check every directory or mailbox argument to see if it has characters outside the imap_utf7 charset and attempts to convert them automatically. ---------- assignee: docs@python components: Documentation messages: 241812 nosy: docs@python, pmoleri priority: normal severity: normal status: open title: IMAP library lacks documentation about expected parameter types type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24027> _______________________________________

3 2

[issue27544] Document checking dict types
by hannah April 14, 2018

April 14, 2018

New submission from hannah: While there is documentation that dict.keys(), dict.values(), and dict.items() are now view objects(https://docs.python.org/3/library/stdtypes.html#dict-views), there's no mention dictviews, dict_keys, dict_values, and dict_items not being built-ins. This is confusing because type(dict.keys()) returns dict_keys, type(dict.values()) returns dict_values, etc., and the documentation uses `dictview` as the object signature, and so it's unclear how to do object introspection on dictview objects. The #python-dev channel suggested that the canonical way to do the object introspection is to use the collections.abc.mapview types; the documentation for dicts should reflect this (and that dictview and the rest are not __builtin__ types/in the python namspace). ---------- assignee: docs@python components: Documentation messages: 270672 nosy: docs@python, story645 priority: normal severity: normal status: open title: Document checking dict types type: enhancement versions: 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/issue27544> _______________________________________

4 5

[issue28393] Update encoding lookup docs wrt #27938
by Ville Skyttä April 4, 2018

April 4, 2018

New submission from Ville Skyttä: The attached patch brings codecs docs up to date with respect to changes in #27938. ---------- assignee: docs@python components: Documentation files: codecs-doc.patch keywords: patch messages: 278354 nosy: docs@python, haypo, scop priority: normal severity: normal status: open title: Update encoding lookup docs wrt #27938 type: enhancement Added file: http://bugs.python.org/file45030/codecs-doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28393> _______________________________________

5 12