Mailman 3 March 2014 - docs

argparse FAQ: how it is different from optparse (issue 17462)
by techtonik＠gmail.com 18 Mar '14

18 Mar '14

Reviewers: , http://bugs.python.org/review/17462/diff/11350/Doc/library/argparse.rst File Doc/library/argparse.rst (right): http://bugs.python.org/review/17462/diff/11350/Doc/library/argparse.rst#new… Doc/library/argparse.rst:1892: * Providing a much simpler interface for custom ``type`` and ``action``. This info is copy/pasted from http://stackoverflow.com/questions/3217673/why-use-argparse-rather-than-opt… which is `cc by-sa 3.0 with attribution required`, so please consult on core mailing list how to handle that. Please review this at http://bugs.python.org/review/17462/ Affected files: Doc/library/argparse.rst diff -r 14c1ff6a8086 Doc/library/argparse.rst --- a/Doc/library/argparse.rst Tue Mar 11 08:12:48 2014 +0100 +++ b/Doc/library/argparse.rst Tue Mar 18 12:22:01 2014 +0100 @@ -1915,6 +1915,16 @@ :mod:`optparse` had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility. +The :mod:`argparse` module improves on the standard library :mod:`optparse` +module in a number of ways including: + +* Handling positional arguments. +* Supporting sub-commands. +* Allowing alternative option prefixes like ``+`` and ``/``. +* Handling zero-or-more and one-or-more style arguments. +* Producing more informative usage messages. +* Providing a much simpler interface for custom ``type`` and ``action``. + A partial upgrade path from :mod:`optparse` to :mod:`argparse`: * Replace all :meth:`optparse.OptionParser.add_option` calls with

1 0

[issue14332] Better explain "junk" concept in difflib doc
by Alba Magallanes 18 Mar '14

18 Mar '14

Alba Magallanes added the comment: I removed the References to 2.x version. ---------- Added file: http://bugs.python.org/file34479/issue14332_2.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14332> _______________________________________

1 0

Re: [docs] Bring Doc/using/windows up to date (issue 20265)
by kathleen＠kweaver.org 17 Mar '14

17 Mar '14

I've just uploaded the new patches. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst File Doc/faq/windows.rst (right): http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode14 Doc/faq/windows.rst:14: XXX need review for Windows Vista/Seven? On 2014/03/13 15:11:23, Zach Ware wrote: > If you've confirmed that things are right for Python 3 and Windows past Vista, > you can remove these comments. I left the comment since I just review for 7/8 I'm hoping no one has Vista any more. Done. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode42 Doc/faq/windows.rst:42: Windows Icon or type Command Prompt at the Start Menu. You should be able to recognize On 2014/03/13 15:11:23, Zach Ware wrote: > A general comment that applies throughout the docs: long lines should be wrapped > somewhere under 80 characters, matching what the rest of the file does. I would > actually suggest wrapping at 78 characters, which should prevent line wrapping > in an 80 character wide Command Prompt when viewing a diff (80, minus 1 for the > +/ /- diff character, and 1 for the two-character EOL on Windows). Done. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode1… Doc/faq/windows.rst:119: a list of directories where Windows will look for programs. On 2014/03/13 06:34:55, eric.araujo wrote: > Minor: trailing whitespace here. Done. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode1… Doc/faq/windows.rst:143: :ref:`below<setting-envvars>` . On 2014/03/13 06:34:55, eric.araujo wrote: > Minor: please add a space before the <. Done. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:352: How do I Change Enviroment Settings? On 2014/03/13 06:34:55, eric.araujo wrote: > Typo: Environment Done. http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:359: Windows XP: Right-click the icon for your machine On 2014/03/13 06:34:55, eric.araujo wrote: > Indentation is like special markup in reStructuredText; here it would mean > “quote block”, which is not your intent, I think. I am not sure I understand. I want to separate Windows XP directions from Windows 7 and from Windows 8. Please suggest a better way. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst File Doc/using/windows.rst (right): http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:49: .. see also:: On 2014/03/13 06:34:55, eric.araujo wrote: > Roles and directives in reStructuredText are like keywords in Python code: > changing one letter or adding a space makes them invalid. If you build the doc, > you’ll get a warning for that line. > > http://sphinx-doc.org/rest.html#directives > http://sphinx-doc.org/markup/para.html#directive-seealso Didn't see one but put it back. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:61: `For Windows users <http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_ On 2014/03/13 06:34:55, eric.araujo wrote: > This link changed (the right address is used just below). Done. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:63: in "`A Byte of Python <http://swaroopch.com/notes/python_en-installation/>`_" On 2014/03/13 06:34:55, eric.araujo wrote: > I see that the byteofpython.info domain name is not useful anymore; I would > remove that line. Done. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:83: .. sectionauthor:: Kathleen Weaver <kathleen(a)kweaver.org> On 2014/03/13 06:34:55, eric.araujo wrote: > Sections are created by headings, so a directive applying to a section should be > after the heading. > > In general, there aren’t many “sectionauthor” directives in doc files, but just > one or two at the top of the file. I removed those. Is there a way I should indicate I made major additions? http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:88: The following shortcuts are creating during installation and can be used to run Python: On 2014/03/13 15:11:23, Zach Ware wrote: > creating -> created Done. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:105: raw_input() On 2014/03/13 15:11:23, Zach Ware wrote: > raw_input doesn't exist in Python 3, just input(). I'm not sure we want to > encourage this kind of workaround anyway. If you need the output, run from a > Command Prompt window or write it to a file. It'll quickly become annoying > having to remember to hit Enter at the end of every script run. Besides, this > trick won't work in the most common case where you really want the output: > unhandled exceptions. I will remove. It was something I found in my research. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:212: #. Launch a command prompt [Windows 8 - Launch Command Prompt (Admin)] On 2014/03/13 15:11:23, Zach Ware wrote: > I don't think this new comment adds much, considering the "(might require > administrative rights)" comment a line above and the fact that it probably > applies to Vista and 7 as well as 8. It may be better to move that comment to > this line, though; it fits better here since this is the step where you would > acquire admin privileges. Actually it is a new available option for Windows 8 users, so it should be there. The average Windows 8 probably doesn't know there are two choices, it had me scratching my head for a while. http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcod… Doc/using/windows.rst:220: On 2014/03/13 15:11:23, Zach Ware wrote: > I don't think the blank line here should have been removed. Whitespace is even > more important in reStructuredText than in Python: vertical whitespace means > something too in some situations :) Done. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst File Doc/faq/windows.rst (right): http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode14 Doc/faq/windows.rst:14: XXX need review for Windows Vista/Seven? Reviewed Windows 7/8 by kw So when we accomplish a task on a comment, we delete the comment? On 2014/03/15 05:13:58, Zach Ware wrote: > Better to just remove the comment. If we have XP and 7 covered, Vista should be > pretty well covered too. The number of people still stuck with Vista is pretty > small compared to XP and 7+ anyway. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode23 Doc/faq/windows.rst:23: Some users may find that method more efficient than the below method. On 2014/03/15 05:13:58, Zach Ware wrote: > I think adding this paragraph before the next one makes the next one make less > sense. I think it would be better to segue into this from the end of the next > paragraph, something like "The situation has been made somewhat simpler since > Python 3.3, which introduced the :ref:`launcher`..." Done. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode49 Doc/faq/windows.rst:49: "command prompt", which usually looks like this:: On 2014/03/15 05:13:58, Zach Ware wrote: > Sorry, I wasn't entirely clear. Lines that you've changed should be wrapped at > <80 characters, but lines that you haven't changed should be left as is. If you > have to, you can leave a very short line in the middle of a paragraph, and if > it's really bad, the committer can reflow the paragraph at commit time. > > For instance, this paragraph could be left like this: > > @@ -37,7 +38,8 @@ > *typing* Windows commands into what is variously referred to as a "DOS window" > or "Command prompt window". Usually you can create such a window from your > Start menu; under Windows 7 the menu selection is :menuselection:`Start --> > -Programs --> Accessories --> Command Prompt`. You should be able to recognize > +Programs --> Accessories --> Command Prompt`; under Windows 8 right click the > +Windows Icon or type Command Prompt at the Start Menu. You should be able to > +recognize > when you have started such a window because you will see a Windows "command > prompt", which usually looks like this:: Done. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode1… Doc/faq/windows.rst:142: an "Enter" to get out of it). Once you have verified the directory, you can On 2014/03/15 05:13:58, Zach Ware wrote: > This comment about needing Ctrl-Z to exit the interpreter isn't quite right > anymore, there is now exit() and quit(). Since this looks like a reminder of a > previous notice, that previous notice could stand to be removed (or reworded) as > well. Done. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode1… Doc/faq/windows.rst:147: More information about environment variables and path can be found On 2014/03/15 05:13:58, Zach Ware wrote: > The added "and path" doesn't sound right to me, but I can't put my finger on > what's wrong with it. I've decided to take the directions for environment variables out. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:361: built-in dialog. There is an alternative method that works for prior On 2014/03/15 05:13:58, Zach Ware wrote: > This isn't true, `set` and `setx` work just as well on 7+. Okay, it doesn't work on some of my machines. However, two of those machines have been in an restricted environment, and they have added oddly ever since. It does work on this machine, which is Windows 8 and it hasn't been exposed <grin> http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:375: --> Advanced It does work, but the method for Windows 7 is shorter, and even shorter for Windows 8. On 2014/03/15 05:13:58, Zach Ware wrote: > This also works for 7, except "My Computer" is just "Computer" and "Advanced" is > "Advanced System Settings" in the left side menu. I'm pretty sure it also works > on 8, but I've only tried it once and don't remember for certain. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:378: Windows 7: Right-click the Windows Icon, choose :menuselection:`Contol Panel`. Yes, there is a Windows Icon on Windows 7 that takes you to the start menu. That Icon went away on Windows 8 and came back on Windows 8.1 You click on it for Windows 7 (my mistake) and right click on it for Windows 8. This is the shortest path to get there from the desktop. On 2014/03/15 05:13:58, Zach Ware wrote: > What do you mean by "Windows Icon"? Is that the Start Menu button (that hasn't > said 'start' since Vista)? If I right click on it in 7, I only get "Properties" > and "Open Windows Explorer". http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode3… Doc/faq/windows.rst:389: Windows 8: Right-click the Windows Icon, choose On 2014/03/15 05:13:58, Zach Ware wrote: > Same question about Windows Icon, though I haven't tested on 8. Right click is correct. Clicking takes you to the start menu. http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode4… Doc/faq/windows.rst:405: Windows 7 and 8 is using the :command:`set` On 2014/03/15 05:13:58, Zach Ware wrote: > This is still true for 7 and 8. Put it back, I tried it on an "unaffected" machine. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst File Doc/using/windows.rst (right): http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:23: On 2014/03/15 05:13:58, Zach Ware wrote: > A couple too many blank lines. Done. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:26: Start Menu under the title Python x.x where x.x is the version number. On 2014/03/15 05:13:58, Zach Ware wrote: > I think there is markup for something that expands to the version number > (`|version|` perhaps?) that would simplify this. Or just hard code the version > and we'll add it as a place that needs to change at release time. Yes, but we tell them that they can run multiple versions at once sometime here.... http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:28: * IDLE (Python GUI) - suitable for creating and running Python Scripts along with being a command line interpreter On 2014/03/15 05:13:58, Zach Ware wrote: > I think IDLE can be better described as "a simple IDE for Python, written in > Python using Tkinter" Done. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:28: * IDLE (Python GUI) - suitable for creating and running Python Scripts along with being a command line interpreter On 2014/03/15 05:13:58, Zach Ware wrote: > I think IDLE can be better described as "a simple IDE for Python, written in > Python using Tkinter" Done. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:32: On 2014/03/15 05:13:58, Zach Ware wrote: > The 'Module Docs' entry is missing. Done. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:34: prompt typically runs the last installed version of Python. On 2014/03/15 05:13:58, Zach Ware wrote: > This isn't really true: Command Prompt runs whichever one it finds first when it > checks PATH for 'python', which will be none of the above unless you choose to > let the installer change your PATH. I'm not sure how best to word that for this > section, so it may be best to just nix this sentence and cover it in more detail > elsewhere. Done. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:60: in "`Installing Python" <http://swaroopch.com/notes/python_en-installation/>`_" I deleted it then. On 2014/03/15 05:13:58, Zach Ware wrote: > This needs some work; the section in question no longer has "For Windows users" > in its title anywhere, and is "Python: Installation" rather than "Installing > Python". Also, it looks like this guide doesn't say anything that we aren't > already saying here or in the FAQ. http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcod… Doc/using/windows.rst:97: window will close immediately, usually faster than the user can read. On 2014/03/15 05:13:58, Zach Ware wrote: > Both of these lines and several others have trailing whitespace. You can get > rid of all trailing whitespace with relative ease by running > Tools\scripts\patchcheck.py using a repository build of Python > (PCbuild\python[_d].exe) before creating the patch file for upload. Done. http://bugs.python.org/review/20265/

1 0

[issue20963] side_effects swapped in Mock example
by chris-buccella 17 Mar '14

17 Mar '14

New submission from chris-buccella: http://docs.python.org/3.4/library/unittest.mock-examples.html Section 26.5.3.9. Mocking a dictionary with MagicMock In the Note area: >>> mock.__setitem__ = Mock(side_effect=getitem) >>> mock.__getitem__ = Mock(side_effect=setitem) I think these are swapped; should be: >>> mock.__setitem__ = Mock(side_effect=setitem) >>> mock.__getitem__ = Mock(side_effect=getitem) ---------- assignee: docs@python components: Documentation messages: 213891 nosy: chris-buccella, docs@python priority: normal severity: normal status: open title: side_effects swapped in Mock example versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20963> _______________________________________

3 3

[issue20960] Fix usage of the versionchanged directive in the sys.hash_info documentation
by Roundup Robot 17 Mar '14

17 Mar '14

New submission from Roundup Robot: New changeset a2fd7e452167 by R David Murray in branch '3.4': closes #20960 http://hg.python.org/cpython/rev/a2fd7e452167 New changeset 3a3a5467baa9 by R David Murray in branch 'default': Merge fix for #20960 http://hg.python.org/cpython/rev/3a3a5467baa9 ---------- nosy: +python-dev resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20960> _______________________________________

1 0

[issue20960] Fix usage of the versionchanged directive in the sys.hash_info documentation
by Berker Peksag 17 Mar '14

17 Mar '14

Changes by Berker Peksag <berker.peksag(a)gmail.com>: ---------- assignee: docs@python components: Documentation files: sys-versionchanged.diff keywords: patch nosy: berker.peksag, docs@python priority: normal severity: normal stage: patch review status: open title: Fix usage of the versionchanged directive in the sys.hash_info documentation versions: Python 3.4, Python 3.5 Added file: http://bugs.python.org/file34463/sys-versionchanged.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20960> _______________________________________

1 0

[issue20814] tracemalloc example
by Jeong-Min Lee 17 Mar '14

17 Mar '14

New submission from Jeong-Min Lee: Running the Pretty top example (http://docs.python.org/dev/library/tracemalloc.html#pretty-top) in the tracemalloc module documentation causes a ValueError. Traceback (most recent call last): File "t.py", line 32, in <module> display_top(snapshot, 10) File "t.py", line 9, in display_top top_stats = snapshot.statistics(group_by) File "/home/falsetru/h/cpython/Lib/tracemalloc.py", line 449, in statistics grouped = self._group_by(key_type, cumulative) File "/home/falsetru/h/cpython/Lib/tracemalloc.py", line 395, in _group_by raise ValueError("unknown key_type: %r" % (key_type,)) ValueError: unknown key_type: 10 The last line of the example should be: display_top(snapshot, limit=10) or: display_top(snapshop) ---------- assignee: docs@python components: Documentation messages: 212493 nosy: Jeong-Min.Lee, docs@python priority: normal severity: normal status: open title: tracemalloc example versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20814> _______________________________________

5 7

[issue19060] docs: note that subprocess doesn't replace os.exec*
by anatoly techtonik 17 Mar '14

17 Mar '14

New submission from anatoly techtonik: I always thought that subprocess is replacing all other methods of executing external programs from Python and it is a preferred way. Perhaps I was not attentive that people isolate: os.system os.spawn* os.popen* and os.exec* While subprocess replaces three first, it doesn't do this with the last one. The documentation should mention this in the header block. Proposed edit: ... replace several other, older modules and functions, such as: os.system os.spawn* os.popen* popen2.* commands.* + Note that it doesn't replace other ways of executing external + processes from Python, such as: + + os.exec* Information about how the subprocess module can be used ... ---------- assignee: docs@python components: Documentation messages: 198188 nosy: docs@python, techtonik priority: normal severity: normal status: open title: docs: note that subprocess doesn't replace os.exec* versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19060> _______________________________________

6 16

[issue20694] asyncio.docs: Document subprocess_exec and subprocess_shell
by Yury Selivanov 17 Mar '14

17 Mar '14

New submission from Yury Selivanov: (I'd document this myself, but I lack the experience of working with these functions) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20694> _______________________________________

2 7

[issue20652] Example in asyncio task gives resource warning
by Vajrasky Kok 17 Mar '14

17 Mar '14

New submission from Vajrasky Kok: >From http://docs.python.org/3.4/library/asyncio-task.html#example-future-with-ru… there is an example code: import asyncio @asyncio.coroutine def slow_operation(future): yield from asyncio.sleep(1) future.set_result('Future in done!') def got_result(future): print(future.result()) loop.stop() loop = asyncio.get_event_loop() future = asyncio.Future() asyncio.Task(slow_operation(future)) future.add_done_callback(got_result) loop.run_forever() I got this: ethan@amiau:~/Documents/code/python/cpython3.4$ ./python /tmp/demo.py Future in done! sys:1: ResourceWarning: unclosed <socket object at 0x7feb49df1058> sys:1: ResourceWarning: unclosed <socket object at 0x7feb493b48c8> Here is the patch to shut off the resource warning. ---------- assignee: docs@python components: Documentation files: shut_off_resource_warning_run_forever_asyncio_example.patch keywords: patch messages: 211392 nosy: docs@python, haypo, vajrasky priority: normal severity: normal status: open title: Example in asyncio task gives resource warning type: resource usage versions: Python 3.4 Added file: http://bugs.python.org/file34111/shut_off_resource_warning_run_forever_asyn… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20652> _______________________________________

2 4