Mailman 3 October 2014 - docs

[issue13211] urllib2.HTTPError does not have 'reason' attribute.
by Jason R. Coombs Oct. 3, 2014

Oct. 3, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: The urllib2 docs indicate that HTTPError is a subclass of URLError and that URLError has an attribute of 'reason', but HTTPError does not have this attribute. The docs should be updated to reflect this deviance. It appears the Python 3.2 docs no longer include documentation for URLError Python 2.7.2 >>> try:urllib2.urlopen('http://api.wordnik.com/v4/word.json/foo/examples') ... except urllib2.HTTPError as exc: ... print(dir(exc)) ... ['_HTTPError__super_init', '__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__getitem__', '__getslice__', '__hash__', '__init__', '__iter__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__setstate__', '__sizeof__', '__str__', '__subclasshook__', '__unicode__', '__weakref__', 'args', 'close', 'code', 'errno', 'filename', 'fileno', 'fp', 'getcode', 'geturl', 'hdrs', 'headers', 'info', 'message', 'msg', 'next', 'read', 'readline', 'readlines', 'strerror', 'url'] The same issue exists in Python 3.2.2. Here's what I propose: - For Python 3.2 and 3.3, update HTTPError to supply a @property, aliasing .msg (will .msg always be a suitable .reason?). - For Python 2.7, document the deviance, such as by adding the following wording to the HTTPError docs: "Unlike URLError, HTTPError does not supply a reason attribute. The reason can be retrieved through the msg attribute." ---------- assignee: docs@python components: Documentation messages: 145805 nosy: docs@python, jason.coombs priority: normal severity: normal status: open title: urllib2.HTTPError does not have 'reason' attribute. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13211> _______________________________________

8 23

[issue19472] inspect.getsource() raises a wrong exception type
by Marco Buttu Oct. 3, 2014

Oct. 3, 2014

New submission from Marco Buttu: I was looking at inspect.getsource(). In Python 3.3 and 3.4 either the docstring and the online doc say it raises a OSError, and in fact: >>> import inspect >>> def foo(): ... pass ... >>> inspect.getsource(foo) Traceback (most recent call last): ... OSError: could not get source code However, getsource() calls getfile(), and this one raises a TypeError: >>> inspect.getsource(0) Traceback (most recent call last): ... TypeError: 0 is not a module, class, method, function, traceback, frame, or code object ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 201891 nosy: docs@python, marco.buttu priority: normal severity: normal status: open title: inspect.getsource() raises a wrong exception type type: behavior versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19472> _______________________________________

3 3

typos in docs
by Hinton, Scott (ESEA Space) Oct. 3, 2014

Oct. 3, 2014

Hello, I was reading in the multiprocessing module section today https://docs.python.org/2/library/multiprocessing.html#all-platforms and noticed a few minor errors: "Remember also that non-daemonic processes will be automatically be joined." That sentence has the word 'be' twice. The word wrap must have got somebody. Then a few lines later it says: "A fix here would be to swap the last two lines round (or simply remove the p.join() line)." Though most people probably understand this because 'round' is a slang-ish way to say 'around', we should probably change this to use the proper spelling. Scott Hinton Honeywell Aerospace Engineer I Systems

2 1

another minor typo
by Hinton, Scott (ESEA Space) Oct. 2, 2014

Oct. 2, 2014

Hello, There is a minor misspelling in the documentation in section https://docs.python.org/2/library/multiprocessing.html#miscellaneous The line says: "Calling this has the side affect of "joining" any processes which have already finished." But in this case I believe that affect is incorrect and effect should be used instead. Scott Hinton Honeywell Aerospace Engineer I Systems

1 0

[issue22537] Failure building 2.7 docs on Windows
by Terry J. Reedy Oct. 2, 2014

Oct. 2, 2014

New submission from Terry J. Reedy: I was able to build docs of all versions with the old system. When 3.4 was changed to the new system, 'pip install sphinx' installed everything needed so that 'sphinx-build -bhtml . build/html' in .../Doc (Devguide 7.5.2) works for 3.4 (and 3.5). "PYTHON=C:\programs\python27\python.exe" does not seem to matter. After the recent conversion for 2.7, that command and 'make html' (devguide 7.5.1) do not work for 2.7. The devguide instructions are version-independent, but the reality does not seem to be. Both commands give this. Running Sphinx v1.2.2 Configuration error: There is a syntax error in your configuration file: invalid syntax (patchlevel.py, line 71) Did you change the syntax from 2.x to 3.x? tools/patchlevel.py. line 71, is "print x'. When I added ()s, this error goes away and I get Running Sphinx v1.2.2 Exception occurred: File "F:\Python\dev\2\py27\Doc\tools\pyspecific.py", line 247, in <module> import suspicious File "F:\Python\dev\2\py27\Doc\tools\suspicious.py", line 57 detect_all = re.compile(ur''' ::(?=[^=])| # two :: (but NOT ::=) :[a-zA-Z][a-zA-Z0-9]+| # :foo `| # ` (seldom used by itself) (?<!\.)\.\.[ \t]*\w+: # .. foo: (but NOT ... else:) ''', re.UNICODE | re.VERBOSE).finditer ^ SyntaxError: invalid syntax I expect the problem is the 'ur' prefix, invalid in 3.4+. I tried to install a 2.7 version of sphinx, but pip refuses. C:\Programs\Python27>pip install sphinx Requirement already satisfied (use --upgrade to upgrade): sphinx in c:\programs\python34\lib\site-packages So I don't know how to sensibly proceed without disabling 3.x builds. ---------- assignee: docs@python components: Devguide, Documentation messages: 228152 nosy: docs@python, ezio.melotti, georg.brandl, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Failure building 2.7 docs on Windows type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22537> _______________________________________

4 4

[issue18729] In unittest.TestLoader.discover doc select the name of load_tests function
by py.user Oct. 2, 2014

Oct. 2, 2014

New submission from py.user: http://docs.python.org/3/library/unittest.html#unittest.TestLoader.discover "If load_tests exists then discovery does not recurse into the package" ---------- assignee: docs@python components: Documentation files: issue.diff keywords: patch messages: 195092 nosy: docs@python, py.user priority: normal severity: normal status: open title: In unittest.TestLoader.discover doc select the name of load_tests function type: enhancement versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file31283/issue.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18729> _______________________________________

4 3

[issue19434] Wrong documentation of MIMENonMultipart class
by Vajrasky Kok Oct. 2, 2014

Oct. 2, 2014

New submission from Vajrasky Kok: >>> from email.mime.nonmultipart import MIMENonMultipart >>> MIMENonMultipart.__doc__ 'Base class for MIME multipart/* type messages.' >>> Attached the patch to fix the doc of MIMENonMultipart class. ---------- assignee: docs@python components: Documentation files: fix_doc_for_mime_non_multipart.patch keywords: patch messages: 201643 nosy: docs@python, r.david.murray, vajrasky priority: normal severity: normal status: open title: Wrong documentation of MIMENonMultipart class versions: Python 3.4 Added file: http://bugs.python.org/file32410/fix_doc_for_mime_non_multipart.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19434> _______________________________________

3 3

[issue22528] Missing hint to source code
by Friedrich Spee von Langenfeld Oct. 1, 2014

Oct. 1, 2014

New submission from Friedrich Spee von Langenfeld: Nearly every module entry in the documentation has a headline with the pattern <module name -- description>, followed (in the second line) by <Source code: directory>. In the entry concerning pdb (https://docs.python.org/3/library/pdb.html), there is no hint where the source code is located. This is especially annoying, because the user of the Python Debugger is explicitely invented to extend the module´s capabilities ("The debugger is extensible – it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source."). A link to the source code should be added as the second line. The same thing should done for symtable, compileall and perhaps some other modules, which I haven´t checked by now. ---------- assignee: docs@python components: Documentation messages: 227989 nosy: Friedrich.Spee.von.Langenfeld, docs@python priority: normal severity: normal status: open title: Missing hint to source code _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22528> _______________________________________

2 3

[issue19342] Improve grp module docstrings
by Marius Gedminas Oct. 1, 2014

Oct. 1, 2014

New submission from Marius Gedminas: This patch gives grp.getgrnam and grp.getgrgid sligtly more useful docstrings, and brings them in line with pwd.getpwnam/pwd.getpwuid. Compare pydoc pwd.getpwnam: pwd.getpwnam = getpwnam(...) getpwnam(name) -> (pw_name,pw_passwd,pw_uid, pw_gid,pw_gecos,pw_dir,pw_shell) Return the password database entry for the given user name. See help(pwd) for more on password database entries. After looking at it I know that I can convert a name to an UID by doing pwd.getpwnam(name).pw_uid. Meanwhile pydoc grp.getgrnam: grp.getgrnam = getgrnam(...) getgrnam(name) -> tuple Return the group database entry for the given group name. If name is not valid, raise KeyError. is rather unfriendly and makes me reach for Google just so that I could find out the names of the namedtuple members. ---------- assignee: docs@python components: Documentation files: grpmodule-docstrings.patch keywords: patch messages: 200896 nosy: docs@python, mgedmin priority: normal severity: normal status: open title: Improve grp module docstrings type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file32295/grpmodule-docstrings.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19342> _______________________________________

4 4

[issue19622] Default buffering for input and output pipes in subprocess module
by Martin Panter Oct. 1, 2014

Oct. 1, 2014

New submission from Martin Panter: Currently the documentation for the “bufsize” parameter in the “subprocess” module says: """ Changed in version 3.2.4,: 3.3.1 bufsize now defaults to -1 to enable buffering by default to match the behavior that most code expects. In 3.2.0 through 3.2.3 and 3.3.0 it incorrectly defaulted to 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected. """ First of all the formatting is a bit screwy. There’s a colon in the wrong place, so it’s not obvious that the “changed in version” heading applies to the following paragraph. The main issue is that I got the impression the default of 0 was a regression, and that Python 3.1 and Python 2 defaulted to -1. However, as far as I can tell the default was actually 0 in 3.1 and 2. The change to -1 was for Issue 17488, which seems to be focussed on the behaviour of reading from a subprocess’s output pipe. In Python 2, file.read() blocks to read as much as possible, even when buffering is disabled. In Python 3, you end up with either a FileIO or a BufferedIOBase object, and they have different read() behaviours. Perhaps the documentation should say something like """ The “bufsize” argument now defaults to -1 to enable buffering. In 3.2.3, 3.3.0, and earlier, it defaulted to 0 which was unbuffered and allowed short reads. """ I would take out the “most code expects buffering” bits. Maybe most code expects the greedy read behaviour from output pipes, but I would say most code writing to an input pipe expects unbuffered behaviour. The big issue with buffering for me is that BufferedWriter.close() may raise a broken pipe condition. If you want to mention Python 2, maybe say that Python 2 did not use buffering by default, but that file.read() always had blocking read behaviour, which can be emulated by using buffered reading in Python 3. ---------- assignee: docs@python components: Documentation messages: 203010 nosy: docs@python, vadmium priority: normal severity: normal status: open title: Default buffering for input and output pipes in subprocess module type: behavior versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19622> _______________________________________

4 5