Mailman 3 March 2011 - docs

typo on http://docs.python.org/tutorial/classes.html
by Mark Zollinger March 22, 2011

March 22, 2011

FWIW, On page http://docs.python.org/tutorial/classes.html, the text "where one at least one of the parent classes" should probably be changed to "where at least one of the parent classes". (too many "one"s) -Mark Z

2 1

HTMLParser documentation bug
by tomo cocoa March 22, 2011

March 22, 2011

Hello I am a Japanese Pythonophilia and also a member of the python-doc-ja project. I found a small bug in HTMLParser library reference. http://docs.python.org/library/htmlparser.html There is duplicated word "be" in the explanation of the unknown_decl method. > It is sometimes useful to be be overridden Regards. -- class Cocoatomo: name = 'cocoatomo' email_address = 'cocoatomo77(a)gmail.com' twitter_id = '@cocoatomo'

2 1

[issue11625] Typo in collections.abc docs
by Doug Latornell March 22, 2011

March 22, 2011

New submission from Doug Latornell <djl(a)douglatornell.ca>: There is a minor type in note (1) regarding use of Set and MutableSet mixins. The method to be overridden when a special constructor signature is required should be _from_iterator, not from_iterator. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11625> _______________________________________

4 6

[issue11622] Documentation
by Roberto De Renzi March 22, 2011

March 22, 2011

New submission from Roberto De Renzi <roberto.derenzi(a)unipr.it>: I don't know if a suggestion is allowed here. I am an absolute beginner trying to substitute my matlab+fortran with python. I just passed the stage of tutorials and I have to struggle looking for the right syntax to implement my simple-minded programs. The learning curve is much steeper than for matlab, certainly due to the greater power of the language. The thing I need is a good reference manual. I find the Language Reference extremely poor in examples. The Library Reference is marginally better. Would you please consider sponsoring (as a developer-user community) a style that forces to include very short examples? Thanks Roberto ---------- assignee: docs@python components: Documentation messages: 131658 nosy: docs@python, roberto.derenzi priority: normal severity: normal status: open title: Documentation type: feature request versions: Python 2.7, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11622> _______________________________________

3 4

[issue11625] Typo in collections.abc docs
by Doug Latornell March 21, 2011

March 21, 2011

Changes by Doug Latornell <djl(a)douglatornell.ca>: ---------- assignee: docs@python components: Documentation nosy: dlatornell, docs@python priority: normal severity: normal status: open title: Typo in collections.abc docs _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11625> _______________________________________

1 0

[issue3722] print followed by exception eats print with doctest
by Terry J. Reedy March 20, 2011

March 20, 2011

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: You misunderstood my last response. The first paragraph *dismisses* the case of temporary print (raised by Charles-Axle) as out of scope for doctests and hence this issue. The next ones addresses *your* case of code *permanently* intended to print and raise and gives a workable solution to your example. After failing to find a simpler example that works with 3.x*, I am now thinking of the following doc fix. 1. Add 'directly' before 'supported' in Tim's first sentence: "Examples containing both expected output and an exception are not supported." 2. After the next sentence of explanation, add """Instead, try something like: >>> def test(): ... print("hello") ... raise IndexError() ... >>> try: ... test() ... raise BaseException # Fail if no IndexError ... except IndexError: ... pass hello """ * I discovered a subtle consequence of the print change: "print 1, 1/0" will print '1' on a line by itself and then a traceback. "print(1,1/0)" just prints a traceback. Something like class C(): def __str__(self): raise IndexError print(1, C(), sep='\n') is required to print a value by itself on a line and then a traceback. That is no simpler and probably less realistic than test() above. ---------- keywords: +patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue3722> _______________________________________

1 0

[issue901727] extra_path kwarg to setup() undocumented
by Éric Araujo March 20, 2011

March 20, 2011

Éric Araujo <merwok(a)netwok.org> added the comment: I added the missing words and reworded a few lines in the attached patch. That said, I find that the new doc is barely helpful; it describes what the code does, but does not explain why one would want to use it. Comments in the source suggest it’s a hack to support some corner case. This is still obscure to me after reading about it and looking at the code :( ---------- Added file: http://bugs.python.org/file21313/apiref-followup.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue901727> _______________________________________

1 0

[issue3722] print followed by exception eats print with doctest
by Chris Withers March 20, 2011

March 20, 2011

Chris Withers <chris(a)simplistix.co.uk> added the comment: Terry, My original post was not about *temporary* output inserted for debugging, but test mocks and the like which form a permanent part of the test and which output to stdout. cheers, Chris ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue3722> _______________________________________

1 0

[issue8387] use universal newline mode in csv module examples
by Skip Montanaro March 19, 2011

March 19, 2011

Changes by Skip Montanaro <skip(a)pobox.com>: ---------- nosy: -skip.montanaro _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8387> _______________________________________

1 0

[issue9755] Fix refcounting details in Py3k C API documentation
by Skip Montanaro March 19, 2011

March 19, 2011

Changes by Skip Montanaro <skip(a)pobox.com>: ---------- nosy: -skip.montanaro _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9755> _______________________________________

1 0

[issue9650] format codes in time.strptime docstrings
by Skip Montanaro March 19, 2011

March 19, 2011

Changes by Skip Montanaro <skip(a)pobox.com>: ---------- nosy: -skip.montanaro _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9650> _______________________________________

1 0

[issue11456] Documentation csv RFC4180
by Tony Wallace March 19, 2011

March 19, 2011

New submission from Tony Wallace <tony(a)tony.gen.nz>: Change to documentation preamble for csv module: From: There is no “CSV standard”, so the format is operationally defined by the many applications which read and write it. The lack of a standard means that subtle differences often exist in the data produced and consumed by different applications. To: CSV has been used for many years prior to attempts to standardise it in RFC4180. This has resulted in subtle differences often exist in the data produced and consumed by different applications. ---------- assignee: docs@python components: Documentation messages: 130469 nosy: docs@python, tonywallace priority: normal severity: normal status: open title: Documentation csv RFC4180 type: feature request versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11456> _______________________________________

4 3

[issue11465] Set documentation: Link to wikipedia
by Thomas Guettler March 19, 2011

March 19, 2011

New submission from Thomas Guettler <guettli(a)thomas-guettler.de>: A link from http://docs.python.org/library/stdtypes.html#set.union to http://en.wikipedia.org/wiki/Union_%28set_theory%29 would help young people to understand sets. Of course it is the same for intersection(), difference(), and symmetric_difference(). The images of the wikipedia article explain it very good. ---------- assignee: docs@python components: Documentation messages: 130555 nosy: docs@python, guettli priority: normal severity: normal status: open title: Set documentation: Link to wikipedia versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11465> _______________________________________

4 3

[issue11418] Method's global scope is module containing function definition, not class.
by Terry J. Reedy March 19, 2011

March 19, 2011

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: "Methods defined within a class may reference..." would make the tutorial correct without introducing the complication of methods defined outside a class, let alone in another module. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11418> _______________________________________

1 0

[issue11476] StreamHandler code broken by change of parameter name
by follower March 18, 2011

March 18, 2011

New submission from follower <bugs.python.org(a)rancidbacon.com>: The following change broke pre-existing code that used "strm" as the parameter name (as documented http://docs.python.org/release/2.6.6/library/logging.html#streamhandler): http://hg.python.org/cpython/diff/7391436d8a74/Lib/logging/__init__.py The parameter name was changed with no documentation note that it had changed in 2.7: http://docs.python.org/library/logging.html#stream-handler This breaks existing code with the error: TypeError: __init__() got an unexpected keyword argument 'strm' I encountered it in pyres but it broke Ubuntu bug reporting too: https://bugs.launchpad.net/ubuntu/+source/launchpad-integration/+bug/702455 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 130691 nosy: docs@python, follower priority: normal severity: normal status: open title: StreamHandler code broken by change of parameter name type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11476> _______________________________________

4 5

[issue11573] Improve Unicode Documentation with Known Caveats
by Éric Araujo March 17, 2011

March 17, 2011

Changes by Éric Araujo <merwok(a)netwok.org>: ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python versions: -Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11573> _______________________________________

1 0

[issue11568] docstring of select.epoll.register() is wrong
by Gennadiy Zlobin March 17, 2011

March 17, 2011

Gennadiy Zlobin <gennad.zlobin(a)gmail.com> added the comment: The patch fixes the docstring ---------- keywords: +patch nosy: +gennad Added file: http://bugs.python.org/file21265/11568.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11568> _______________________________________

1 0

[issue11568] docstring of select.epoll.register() is wrong
by Gennadiy Zlobin March 17, 2011

March 17, 2011

Changes by Gennadiy Zlobin <gennad.zlobin(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python type: -> behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11568> _______________________________________

1 0

[issue11298] unittest discovery needs better explanation
by blokeley March 15, 2011

March 15, 2011

New submission from blokeley <blokeley(a)gmail.com>: `python -m unittest discover` caught me out. I had a test module called `test-foo.py` and no test was loaded. When I renamed to `test_foo.py` it worked. The documentation says "For a project’s tests to be compatible with test discovery they must all be importable". I didn't realise that test-foo would not be importable. Could the documentation say "For a project’s tests to be compatible with test discovery they must all be importable, so ensure that the module names are valid Python identifiers." Stackoverflow question is here: http://stackoverflow.com/questions/5088960/python-unittest-discovery-does-n… ---------- assignee: docs@python components: Documentation messages: 129176 nosy: blokeley, docs@python priority: normal severity: normal status: open title: unittest discovery needs better explanation type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11298> _______________________________________

5 33

[issue9362] Make exit/quit hint more novice friendly
by Alexander Belopolsky March 15, 2011

March 15, 2011

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: This bikeshed have been repainted several times already, but here is a true story. Cast: Me = myself Novice = a 14-year-old boy Laptop = a MacBook Air Novice: How do i exit [from python prompt]? Me: What's your best guess? Novice: [typing] exit [pressing Enter] Laptop: Use exit() or Ctrl-D (i.e. EOF) to exit Novice: [typing] Ctrl... Me: OMG, you don't know what Ctrl-D means? Look for the Ctrl key. Novice: There is no such key. --- curtains --- I suggest changing Use exit() or Ctrl-D (i.e. EOF) to exit to Type exit() or quit() and press the Enter key to exit or Type exit() or quit() and press Enter to exit or just Use exit() to exit My theory is that someone who knows what EOF is, will probably already know how to exit from common terminal oriented programs and Ctrl-D is not universally bound to EOF. TOOWTDI: two ways to exit is more than enough to teach a novice. ---------- assignee: docs@python components: Documentation keywords: easy messages: 111374 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Make exit/quit hint more novice friendly type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9362> _______________________________________

10 27

[issue8158] Docstring of optparse.OptionParser incomplete
by R. David Murray March 14, 2011

March 14, 2011

R. David Murray <rdmurray(a)bitdance.com> added the comment: It looks to me like description is still missing from the docstring, at least on python3 tip. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8158> _______________________________________

1 0

[issue8158] Docstring of optparse.OptionParser incomplete
by Jeff Ramnani March 14, 2011

March 14, 2011

Jeff Ramnani <jeff(a)jefframnani.com> added the comment: I've read through the doc and the code. All keyword arguments for OptionParser.__init__() are in the documentation for branches 2.7 and default (as of ecc176488349). Does that mean this issue can be closed? ---------- nosy: +jramnani _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8158> _______________________________________

1 0

[issue10433] Document unique behavior of 'getgroups' on OSX
by Ronald Oussoren March 14, 2011

March 14, 2011

Ronald Oussoren <ronaldoussoren(a)mac.com> added the comment: I do understand the issue, but I'm not sure if I can write it down consisely. I've attached an initial attempt (patch is relative to the default branch, I'll port to 2.7 and 3.2 if it looks OK) ---------- keywords: +needs review, patch Added file: http://bugs.python.org/file21133/issue10433.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10433> _______________________________________

1 0

[issue11497] Devguide: re-run configure in Unix setup step after installing deps
by Matias Bordese March 14, 2011

March 14, 2011

New submission from Matias Bordese <mbordese(a)gmail.com>: When setting up dev environment in Unix and there are missing dependencies after running make, you may need to re-run configure before a new make (relates to #11496). ---------- assignee: docs@python components: Documentation messages: 130820 nosy: docs@python, matiasb priority: normal severity: normal status: open title: Devguide: re-run configure in Unix setup step after installing deps type: resource usage _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11497> _______________________________________

2 2

[issue10885] multiprocessing docs
by Ross Lagerwall March 14, 2011

March 14, 2011

Changes by Ross Lagerwall <rosslagerwall(a)gmail.com>: ---------- assignee: docs@python -> rosslagerwall resolution: -> fixed stage: -> committed/rejected status: open -> closed versions: +Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10885> _______________________________________

1 0