Mailman 3 August 2013 - docs

[issue15871] Online docs: make index search always available.
by Terry J. Reedy May 13, 2014

May 13, 2014

New submission from Terry J. Reedy: For the Windows Help version of the docs, the left side box has 4 tabs: Contents, Index, Search, Favorites. I now mostly use the Index tab. That means that I can enter an indexed keyword, topic, or object name and jump from place to place in the docs. The left margin of the online docs only has a text search box equivalent to the Windows search tab (which I essentially never use). The index is only available on the front page, possibly not even visible without scrolling. Consequently, people, especially beginners, tend to use the text search box when they should be using the index. The result is often useless. The issue came up on python-list about a beginner entering 'print' and getting nothing useful. With the Windows doc, 'print' in the index search immediately brings up print (builtin function) (twice, I did not look into why). The same thing in the search lists 153 pages, with the builtin functions page at 75. Not too surprising, as it is a long page with only 3 occurrences of 'print'. Also not useful. So I think the online docs should also have an always available index search box in addition to the text search box (which should be properly labeled as such). 'Enter a module, class, for function name.' should be applied to index search, not text search. An alternative is for the one box to give both index search results and text search results, but doing the latter when one only wants the former is a waste of both server and reader resources. ---------- assignee: docs@python components: Documentation messages: 169930 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, terry.reedy priority: normal severity: normal status: open title: Online docs: make index search always available. type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15871> _______________________________________

7 14

[issue13030] Be more generic when identifying the Windows main dir in installation doc
by Sandro Tosi May 6, 2014

May 6, 2014

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Given I have no knowledge of the windows system, I'm just proxying http://mail.python.org/pipermail/docs/2011-September/005793.html : >>> Under: http://docs.python.org/install/index.html#inst-how-install-works It notes "Windows prefix\Lib\site-packages C:\PythonXY\Lib\site-packages" for default values on Windows. In the paragraph following the table is the text: "prefix and exec-prefix stand for the directories that Python is installed to, and where it finds its libraries at run-time. They are always the same under Windows, and very often the same under Unix and Mac OS X. " I don't know if it's hardcoded into Python distributions to use C, but it's not correct. The correct way to identify what most people think of as C is via the %SYSTEMROOT% environment variable, so the path described would be "%SYSTEMROOT%\PythonXY\Lib\site-packages" (This is still not the correct way to do things on Windows, but it at least shouldn't break on systems with a %SYSTEMROOT% other than C. I've seen configurations like that on systems which boot multiple versions of Windows.) <<< ---------- assignee: docs@python components: Documentation messages: 144422 nosy: brian.curtin, docs@python, sandro.tosi, tim.golden priority: normal severity: normal stage: needs patch status: open title: Be more generic when identifying the Windows main dir in installation doc type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13030> _______________________________________

4 5

[issue17386] Bring Doc/make.bat as close to Doc/Makefile as possible
by Zachary Ware April 29, 2014

April 29, 2014

New submission from Zachary Ware: I have found Doc/make.bat to be very useful, but I have hit a few of its limitations now and then. Thus, I have made extensive modifications to bring it much closer to the way Doc/Makefile works. Among the things changed in the attached patch: - Use pushd/popd to make sure everything is done in the Doc directory. - Allow variables to be set on the command line, e.g.: make html "PYTHON2=python" - Set PYTHON2 and PYTHON3 variables separately; the Sphinx version and associated tools we're currently using want Python 2, which defaults to "py -2". Other tools, like Tools/scripts/serve.py (the make serve target), expect Python 3; setting the default PYTHON3 searches for python(_d).exe in PCbuild(\amd64), and falls back to "py -3" if not found. - Set the HTML Help Workshop default path to %ProgramFiles(x86)%\..., if that variable is defined. (If I understand correctly, that variable is only defined on x64 installations, and in cases where it is not defined on x64, %ProgramFiles% silently copies %ProgramFiles(x86)%.) - Convert target choice to a single for loop, rather than several lines of if. Anything not in the list falls through to the help message. - Expand the help message to match the message given by Doc/Makefile - Add the "clean" target, which does the same as Makefile - Reimplement "update" to match Makefile (call clean, call checkout. I do wonder if maybe it should be done the other way around, though; reimplement Makfile's "update" target to simply update the svn checkouts, rather than re-pull them) - Add separate labels for each target. The old method of sending everything to :build was very clever and kept the file short, but limited flexibility. It's also nice to get a message at the end (matching Makefile), which is much easier to do with separate labels. - Add support for the PAPER environment variable in LaTeX building. - Add coverage, doctest, pydoc-topics, dist, check, and serve targets. "dist" cannot be completed in the same way with default tools on Windows, so all it does is build html, text, latex (a4 and letter), and epub and copy them into the dist directory. - checkout checks for the existence of the checked out packages before checking out - build calls checkout before building, so you can go right to "make html" instead of having to do "make checkout && make html" - Add support for SOURCES and SPHINXOPTS environment variables. Everything seems to work for me, but I've only been able to test on Windows 7 (32 and 64 bit). I don't believe there's anything in there that doesn't exist in XP, though. Also, since this version of the file has a lot of labels, this patch does somewhat rely on resolution of issue 17202. It should probably work without any changes to .hgeol, but that can't be guaranteed. There are a couple of drawbacks to the patched version; it's a much longer file, and it does lose a good chunk of the elegance of the original solution. If anyone has any suggestions for regaining some of that elegance without losing any of the functionality, I am of course all ears :). In particular, I'm not a huge fan of having to have "pushd ." at the beginning of every label, but the only other solutions I came up with involved setting and unsetting a "DISALLOW_POPD" variable in several places, and a condition on the popd at :end, or forgetting the pushd/popd thing entirely. I'm looking forward to hearing what anyone else thinks of this, positive or negative :) ---------- assignee: docs@python components: Build, Documentation, Windows files: win_doc_make.diff keywords: patch messages: 183768 nosy: christian.heimes, docs@python, zach.ware priority: normal severity: normal status: open title: Bring Doc/make.bat as close to Doc/Makefile as possible type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file29353/win_doc_make.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17386> _______________________________________

4 18

[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
by Alexander Belopolsky April 28, 2014

April 28, 2014

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Is there a reason for not documenting Py_TPFLAGS_LONG_SUBCLASS (Py_TPFLAGS_INT_SUBCLASS in 2.x)? This flag is used in PyLong_Check, but neither this flag or its inheritance properties are explained anywhere in the docs. See also issue5476. ---------- assignee: docs@python components: Documentation messages: 110787 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Py_TPFLAGS_LONG_SUBCLASS is not documented type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9307> _______________________________________

6 8

[issue18243] mktime_tz documentation out-of-date
by Jakub Wilk April 26, 2014

April 26, 2014

New submission from Jakub Wilk: email.utils.mktime_tz documentations says: "Minor deficiency: mktime_tz() interprets the first 8 elements of tuple as a local time and then compensates for the timezone difference. This may yield a slight error around changes in daylight savings time, though not worth worrying about for common use." But now that issue #14653 is fixed, this is no longer true. ---------- assignee: docs@python components: Documentation messages: 191346 nosy: docs@python, jwilk priority: normal severity: normal status: open title: mktime_tz documentation out-of-date _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18243> _______________________________________

5 5

[issue9364] some problems with the documentation of pydoc
by Eli Bendersky April 19, 2014

April 19, 2014

New submission from Eli Bendersky <eliben(a)gmail.com>: The first paragraph in its documentation says: """ In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. """ Which is no longer accurate, because the help() function has long ago become a built-in. Below is an excerpt from Terry Reedy in a private email discussion on this subject, that raises more issues. --------------------------------------------- 1. The output from help(help) could be made more clear. The nature of 'help' has been a point of confusion. A recent python-list post asked something like "What is 'help'?" Now (with some parallel examples: >>> help(int) Help on class int in module builtins: class int(object) [snip] >>> help(1) Help on int object: class int(object) [snip] >>> help(help) Help on _Helper in module site object: class _Helper(builtins.object) | Define the built-in 'help'. | This is a wrapper around pydoc.help (with a twist). | | Methods defined here: | | __call__(self, *args, **kwds) | a. 'module site object' is nonsense, it should just be 'module site', except that to be parallel to what is done for other instances, it should be 'Help on _Helper object'. Why should help special-case itself (with a slightly garbled line?) Is that done in site._Helper or pydoc.help? However, it would be more helpful for all instances to give the location of the class when one asks for help on an instance, just as when one asks for help on the class itself. It is annoying to to have to repeat help(<classname>) just to get that info. So I would like to see "Help on instance of class int in module builtins:" "Help on instance of class _Helper in module site:" This would be a code patch to pydoc.help b. "This is a wrapper around pydoc.help" good so far "(with a twist)" thanks a lot. I think the comment should be either removed or explained. A reference manual should explain, not tease. Replace "Define the built-in 'help'." with something clearer and more accurate, such as "The name 'help' is injected in module builtins after being bound to an instance of this class.". Put this after, not before, the 'wrapper' line. A patch for site._Helper doc string. 2. Improve manual chapter for site module. a. It currently starts "Importing this module will append site-specific paths to the module search path." Add "inject 'help' into builtins and " after append. Then add a short explanation paragraph before the search path stuff. Something like "This module contains a class (_Helper) that wraps function pydoc.help. An instance of the class is bound to name 'help' in the builtins module." A recent discussion on pydev or maybe python-list (in the thread mentioned above?) implied that one could usefully make another instance of _Helper or maybe a subclass thereof. I did not pay enough attention, though, to really get it. b. It currently ends with "XXX Update documentation XXX document python -m site –user-base –user-site" ---------- assignee: docs@python components: Documentation messages: 111426 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: some problems with the documentation of pydoc type: behavior versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9364> _______________________________________

9 21

[issue18628] PEP 8 and encodings
by Terry J. Reedy April 17, 2014

April 17, 2014

New submission from Terry J. Reedy: Three related doc change proposals. The Versions only apply to the third as the first two are for PEP 8. 1. PEP 8 has a section entitled "Encodings (PEP 263)" with a link to the verbose PEP. I think it would be better if it were "Source Encoding" with a link to the 'current' Reference Manual section 2.1.4. Encoding declarations. The latter gets right to the point. 2. This section twice uses the informal and undefined term 'coding cookie'. It is not in the ref manual section above, nor in the glossary, nor in the index. (Dave Angel asked about the definition on python-list. Before searching on the web, he first thought it meant BOM.) I suggest changing "a coding cookie" to "an encoding declaration". 3. The index has several entries that begin with 'encode', including one that just says 'encodings'. The last is the one that points to 2.1.4., but one would only guess by process of elimination. I think 'encoding (source file)' or 'encoding declarations (source file)' would be clearer. ---------- assignee: docs@python components: Documentation messages: 194152 nosy: docs@python, ncoghlan, terry.reedy priority: normal severity: normal stage: needs patch status: open title: PEP 8 and encodings versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18628> _______________________________________

7 7

[issue18566] In unittest.TestCase docs for setUp() and tearDown() don't mention AssertionError
by py.user April 16, 2014

April 16, 2014

New submission from py.user: http://docs.python.org/3/library/unittest.html#unittest.TestCase.setUp "any exception raised by this method will be considered an error rather than a test failure" http://docs.python.org/3/library/unittest.html#unittest.TestCase.tearDown "Any exception raised by this method will be considered an error rather than a test failure." utest.py #!/usr/bin/env python3 import unittest class Test(unittest.TestCase): def setUp(self): raise AssertionError def tearDown(self): raise AssertionError def test_nothing(self): pass [guest@localhost py]$ python3 -m unittest -v utest test_nothing (utest.Test) ... FAIL ====================================================================== FAIL: test_nothing (utest.Test) ---------------------------------------------------------------------- Traceback (most recent call last): File "./utest.py", line 8, in setUp raise AssertionError AssertionError ---------------------------------------------------------------------- Ran 1 test in 0.000s FAILED (failures=1) [guest@localhost py]$ also raising unittest.SkipTest works properly ---------- assignee: docs@python components: Documentation messages: 193772 nosy: docs@python, py.user priority: normal severity: normal status: open title: In unittest.TestCase docs for setUp() and tearDown() don't mention AssertionError type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18566> _______________________________________

9 18

[issue18229] attribute headers of http.server.BaseHTTPRequestHandler sometimes does not exists
by Jordan Szubert April 16, 2014

April 16, 2014

New submission from Jordan Szubert: it seems that problem is someone connecting to port 8080 with non-http client, could not find warning in documentation ---fragment of `less access.log`------------ 81.172.30.254 - - [16/Jun/2013 11:36:58] "^SBitTorrent protocol^@^@^@^@^@^X^@^Ej 81.172.30.254 - - [16/Jun/2013 11:38:11] "^N<U+008E>^@f¸ãÄòQ;³x<U+0092>b^C^HÄA7 81.172.30.254 - - [16/Jun/2013 11:39:22] "^SBitTorrent protocol^@^@^@^@^@^X^@^Ej 81.172.30.254 - - [16/Jun/2013 11:40:35] "Ã<U+008D>¬0æz<U+0093>zr^D<U+009B>2]WQ Exception happened during processing of request from ('81.172.30.254', 63650) Traceback (most recent call last): File "c:\Python33\lib\socketserver.py", line 306, in _handle_request_noblock self.process_request(request, client_address) File "c:\Python33\lib\socketserver.py", line 332, in process_request self.finish_request(request, client_address) File "c:\Python33\lib\socketserver.py", line 345, in finish_request self.RequestHandlerClass(request, client_address, self) File "c:\Python33\lib\socketserver.py", line 666, in __init__ self.handle() File "c:\Python33\lib\http\server.py", line 400, in handle self.handle_one_request() File "c:\Python33\lib\http\server.py", line 380, in handle_one_request if not self.parse_request(): File "c:\Python33\lib\http\server.py", line 283, in parse_request self.send_error(400, "Bad request version (%r)" % version) File "c:\Python33\lib\http\server.py", line 428, in send_error self.send_response(code, message) File "c:\Python33\lib\http\server.py", line 443, in send_response self.log_request(code) File "c:\Users\joru\Dropbox\programowanie\demoniszcze\server\_lowerHTTP.py", line 30, in log_request xff=req.headers.get('X-Forwarded-For') AttributeError: '_HNDL_3' object has no attribute 'headers' # _HNLD_3 derives from http.server.BaseHTTPRequestHandler ---------- assignee: docs@python components: Documentation messages: 191264 nosy: docs@python, joru priority: normal severity: normal status: open title: attribute headers of http.server.BaseHTTPRequestHandler sometimes does not exists type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18229> _______________________________________

5 7

[issue15840] Ambiguity with regard to the effect of accessing a closed IOBase instance
by Alexander Konovalenko April 16, 2014

April 16, 2014

New submission from Alexander Konovalenko: Two pieces of the documentation for io.IOBase seem to contradict each other: At http://docs.python.org/library/io.html#io.IOBase: "Note that calling any method (even inquiries) on a closed stream is undefined. Implementations may raise IOError in this case." At http://docs.python.org/library/io.html#io.IOBase.close: "Once the file is closed, any operation on the file (e.g. reading or writing) will raise a ValueError." Perhaps the confusion arises in part because it is not clear when a requirement for all IOBase implementations is documented and when the docs merely describe the default behavior of IOBase that implementations are free to override. Those passages are inconsistent on two points: 1) IOError and ValueError are not subclasses one of another. So what should we expect an IOBase implementation to raise? 2) Undefined behavior means literally anything can happen. Technically, that means calling read() or readable() on a closed file (or other kind of stream) could wreak havoc in a totally unrelated part of the system or segfault the Python interpreter. That is definitely a thing to carefully avoid in any production systems. On the other hand, raising an exception, even if we don't know in advance whether it will be ValueError or IOError, is pretty much defined behavior. An exception is easy to deal with and to contain inside a module. So please clarify how dangerous it actually is to access an IOBase stream after it has been closed. ---------- assignee: docs@python components: Documentation messages: 169660 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Ambiguity with regard to the effect of accessing a closed IOBase instance versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15840> _______________________________________

8 12