Mailman 3 February 2011 - docs

[issue10170] Relationship between turtle speed setting and actual speed is not documented
by Alexander Belopolsky 18 May '15

18 May '15

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As Terry J. Reedy mentioned in his comment on issue 7061, turtle documentation is lacking information on how speed "codes" 0-10 translate into actual turtle speed. Attached script measures the speed of the two primitive operations that form the basis of turtle functionality at various speed settings. The results below show highly irregular pattern. The columns are: the speed code, time to draw a 200 unit line, time to complete a 360 degrees turn and the ratio of the two times. 0: 0.01 0.01 0.83 1: 1.04 2.05 0.51 2: 0.49 1.06 0.46 3: 0.30 0.72 0.42 4: 0.23 0.54 0.44 5: 0.17 0.44 0.38 6: 0.13 0.39 0.35 7: 0.08 0.32 0.26 8: 0.08 0.28 0.30 9: 0.10 0.27 0.37 10: 0.08 0.23 0.36 >From the source code, it appears that the on-screen speed is controlled by the number of animation steps while each step takes approximately time controlled by the "delay" setting that defaults to 10 milliseconds. The number of steps is determined by somewhat peculiar computations. For a rotation by angle of a degrees at speed setting s, the number of steps is n = 2 + int(a / (3 * s)) and for drawing a line of length d, n = 1 + int(d / (3 * 1.1**s * s)) I am not sure what was the reason for these choices, but I think it would be better if numeric speed code had a more direct relationship to the apparent speed. ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 119334 nosy: belopolsky, docs@python, eric.araujo, georg.brandl, gregorlingl, terry.reedy priority: normal severity: normal status: open title: Relationship between turtle speed setting and actual speed is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10170> _______________________________________

3 3

[issue9119] Python download page needs to mention crypto code in Windows installer
by Marc-Andre Lemburg 20 Feb '15

20 Feb '15

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: This needs to be done to protect our users (importing crypto code or using it may be illegal in their home country, see http://rechten.uvt.nl/koops/cryptolaw/ for a survey) and to satisfy an attribution requirement in the OpenSSL license and code base: """ This product includes cryptographic software written by Eric Young (eay(a)cryptsoft.com). This product includes software written by Tim Hudson (tjh(a)cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) """ ---------- assignee: docs@python components: Build, Documentation messages: 108929 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Python download page needs to mention crypto code in Windows installer versions: 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/issue9119> _______________________________________

10 23

[issue9913] Misc/SpecialBuilds.txt is out of date
by Alexander Belopolsky 19 Feb '15

19 Feb '15

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: It looks like Misc/SpecialBuilds.txt has not been updated since 2.4. This file is referenced from C-API documentation [1], but is not accessible as a hyperlink. Some of the recommendations in this file are out of date, in particular those that recommend setting make variables where a configure switch is available. I believe it would be best to retire Misc/SpecialBuilds.txt and move still relevant sections to proper .rst files. [1] http://docs.python.org/dev/py3k/c-api/intro.html#debugging-builds ---------- assignee: docs@python components: Documentation messages: 117076 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Misc/SpecialBuilds.txt is out of date versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9913> _______________________________________

3 3

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner 13 Dec '14

13 Dec '14

New submission from John Posner <jjposner(a)optimum.net>: The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__. The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine. ---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9536> _______________________________________

7 11

[issue10583] Encoding issue with chm help in 2.7.1
by flashk 07 Oct '14

07 Oct '14

New submission from flashk <flashk(a)gmail.com>: I just updated to Python 2.7.1 and noticed a small issue with the chm help file. The search results tab displays incorrect characters for various topic titles. It seems to be an encoding issue. For example, searching for 'json' yields the following results: - 18.2 json â€” JSON encoder and decoder - Whatâ€™s New in Python 2.6 I noticed this issue on Windows XP 32-bit and Windows 7 64-bit. This issue does not exist with the 2.7 chm file. ---------- assignee: docs@python components: Documentation, Windows messages: 122857 nosy: docs@python, flashk priority: normal severity: normal status: open title: Encoding issue with chm help in 2.7.1 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10583> _______________________________________

7 11

[issue10031] Withdraw anti-recommendation of relative imports from documentation
by Darren Dale 06 Oct '14

06 Oct '14

New submission from Darren Dale <dsdale24(a)gmail.com>: Old-style relative imports have been strongly discouraged in some sections of the python documentation. This was discussed on the python-dev mailing list. Executive summary: "The issue is implementing a PEP with nice support for relative imports, and then documenting that it should never be used." To which Guido responded: --- "Isn't this mostly historical? Until the new relative-import syntax was implemented there were various problems with relative imports. The short-term solution was to recommend not using them. The long-term solution was to implement an unambiguous syntax. Now it is time to withdraw the anti-recommendation. Of course, without going overboard -- I still find them an acquired taste; but they have their place." --- It was suggested I open a ticket and suggest specific changes. They are listed below: The faq at http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practice… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write from . import m2, even though it’s legal. Write from package.sub import m2 instead. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. See PEP 328 for details." The programming faq for python-2.7 at http://docs.python.org/faq/programming.html#what-are-the-best-practices-for… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write import m2, even though it’s legal. Write from package.sub import m2 instead. Relative imports can lead to a module being initialized twice, leading to confusing bugs. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Support for relative imports has recently been improved, and the use of the old-style relative imports is strongly discouraged. See PEP 328 for details." There is also this warning against relative imports in PEP 8, that could go from: - Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 [7] is fully implemented in Python 2.5, its style of explicit relative imports is actively discouraged; absolute imports are more portable and usually more readable. to: - While the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Now that PEP 328 [7] is fully implemented in Python 2.5 and later, the older style of implicit relative imports is strongly discouraged. ---------- assignee: docs@python components: Documentation messages: 118031 nosy: docs@python, dsdale24 priority: normal severity: normal status: open title: Withdraw anti-recommendation of relative imports from documentation versions: 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/issue10031> _______________________________________

5 5

[issue10702] bytes and bytearray methods are not documented
by Alexander Belopolsky 28 Sep '14

28 Sep '14

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Library reference manual has a section dedicated to string methods [1], but similar methods of bytes and bytearray types are not documented. Adding two new sections would probably be too repetitious, so I wonder if it would make sense to add notes about byte/bytearray methods to the matching string methods' entries. See also issue10587. [1] http://docs.python.org/dev/py3k/library/stdtypes.html#string-methods ---------- assignee: docs@python components: Documentation messages: 123960 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: bytes and bytearray methods are not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10702> _______________________________________

6 7

[issue10503] os.getuid() documentation should be clear on what kind of uid it is referring
by Giampaolo Rodola' 08 Jun '14

08 Jun '14

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: http://docs.python.org/library/os.html#os.getuid os.getuid() documentation just states: > Return the current process’s user id. It is not clear, however, whether "user id" refers to real, effective or saved user id. As per: http://linux.about.com/library/cmd/blcmdl2_getuid.htm ...it should refer to _real_ user id. ---------- assignee: docs@python components: Documentation messages: 122117 nosy: docs@python, giampaolo.rodola priority: normal severity: normal status: open title: os.getuid() documentation should be clear on what kind of uid it is referring versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10503> _______________________________________

5 6

[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
by Alexander Belopolsky 29 Apr '14

29 Apr '14

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

[issue9364] some problems with the documentation of pydoc
by Eli Bendersky 20 Apr '14

20 Apr '14

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