Mailman 3 August 2013 - docs

[issue17221] Resort Misc/NEWS
by Serhiy Storchaka Oct. 18, 2013

Oct. 18, 2013

New submission from Serhiy Storchaka: The proposed patch moves some Misc/NEWS entities to more appropriate sections (IDLE, C-API, Tests, Documentation, Tools/Demos). Please review. ---------- assignee: docs@python components: Documentation files: NEWS-3.4.patch keywords: patch messages: 182282 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal stage: patch review status: open title: Resort Misc/NEWS type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file29107/NEWS-3.4.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17221> _______________________________________

9 23

[issue18758] Fix internal references in the documentation
by Serhiy Storchaka Oct. 14, 2013

Oct. 14, 2013

New submission from Serhiy Storchaka: This is a meta issue for fixing broken references in the documentation. I will open a child issues for some groups of modules and finally provide a patch for rest files. ---------- assignee: docs@python components: Documentation messages: 195392 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Fix internal references in the documentation versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________

4 30

[issue18736] Invalid charset in HTML pages inside documentation in CHM format
by Basil Peace Oct. 13, 2013

Oct. 13, 2013

New submission from Basil Peace: HTML pages inside CHM documentation use the following tag to set applied character set: <meta http-equiv="Content-Type" content="text/html; charset=iso8859_1" /> `iso8859_1` is neither valid character set according to IANA registry nor is recognized by most browsers (I've checked IE, Firefox and Opera). This isn't notable for text in English. But, in `Python Standard Library` in section `4.7.1 String Methods` there is a documentation for str.casefold(). This paragraph contains German letter `ß`. Without defined character set this letter can be displayed wrongly, depending on user's regional settings. In my Russian I see in CHM `Я`. Firefox displays it as `�`. Fix of charset to `ISO-8859-1` could resolve the problem. P.S. Use of UTF-8 may be more convenient for preventing future errors. ---------- assignee: docs@python components: Documentation messages: 195136 nosy: docs@python, grv87 priority: normal severity: normal status: open title: Invalid charset in HTML pages inside documentation in CHM format versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18736> _______________________________________

4 3

[issue16253] Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples
by Roger Upole Oct. 13, 2013

Oct. 13, 2013

New submission from Roger Upole: The docs for this function state "Nested tuples cannot be parsed when using keyword arguments!" but this restriction was removed some time ago. ---------- assignee: docs@python components: Documentation messages: 173081 nosy: docs@python, rupole priority: normal severity: normal status: open title: Docs for PyArg_ParseTupleAndKeywords say it doesn't accept nested tuples _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16253> _______________________________________

2 1

[issue17375] Add docstrings to methods in the threading module
by Raymond Hettinger Oct. 13, 2013

Oct. 13, 2013

New submission from Raymond Hettinger: It should be an easy task fill-in the missing docstrings using the verbiage in the regular docs. ---------- assignee: docs@python components: Documentation keywords: easy messages: 183645 nosy: docs@python, rhettinger priority: normal severity: normal status: open title: Add docstrings to methods in the threading module versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17375> _______________________________________

6 11

[issue14502] Document better what happens on releasing an unacquired lock
by Georg Brandl Oct. 13, 2013

Oct. 13, 2013

New submission from Georg Brandl <georg(a)python.org>: >From docs(a)python.org: """ I recently ran into a situation where I could not be certain that a lock was currently in the acquired state. I checked the documentation to determine what would happen if I attempted to release a lock that was already released, and saw an ominous warning of "Do not call this method when the lock is unlocked." Needing to know what would happen, I cautiously tested it out. I half expected my computer to explode as I released a lock for the second time, but was pleased to see it raise a 'thread.error' exception which could be caught and handled. I generally expect the documentation to tell me what will happen if I do something invalid. In this case the documentation should indicate that a thread.error will be raised if you release an unlocked lock. """ I agree: if we know that a ThreadError will always be raised in this instance, we should document it as such. ---------- assignee: docs@python components: Documentation messages: 157544 nosy: docs@python, georg.brandl, pitrou priority: normal severity: normal status: open title: Document better what happens on releasing an unacquired lock versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14502> _______________________________________

9 23

[issue11120] threading.Thread.daemon Documentation Incomplete
by cardinalbiggles Oct. 13, 2013

Oct. 13, 2013

New submission from cardinalbiggles <jmandersen(a)gmail.com>: In the threading module, the documentation for Thread.isDaemon()/Thread.setDaemon() indicates they are the old API for Thread.daemon, which does not indicate the version in which it was introduced (2.6 I believe). Additionally, the documentation for Thread.setDaemon() should at least include the daemonic parameter, if not the full usage documentation for those targeting older versions. Targeting Python 2.4, and being unable to (as) efficiently navigate the old documentation site, I have come to rely on the various 'Changed/New in version 2.X' messages in the current documentation. This caused some confusion on my part. ---------- assignee: docs@python components: Documentation messages: 127927 nosy: cardinalbiggles, docs@python priority: normal severity: normal status: open title: threading.Thread.daemon Documentation Incomplete type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11120> _______________________________________

2 1

[issue14486] Add some versionchanged notes in threading docs
by Nick Coghlan Oct. 13, 2013

Oct. 13, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: A (very) minor irritation discovered today - the PEP 8 style names were added to the threading.Thread API in 2.6, but the only notice of this is up at the top of the module docs. Some embedded notices like: ..versionchanged:: 2.6 Added PEP 8 compliant interfaces. See note at top of page. might be helpful. ---------- assignee: docs@python components: Documentation keywords: easy messages: 157451 nosy: docs@python, ncoghlan priority: low severity: normal stage: needs patch status: open title: Add some versionchanged notes in threading docs type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14486> _______________________________________

3 2

[issue13744] raw byte strings are described in a confusing way
by Barry A. Warsaw Oct. 13, 2013

Oct. 13, 2013

New submission from Barry A. Warsaw <barry(a)python.org>: The lexical analysis documentation says this: http://docs.python.org/py3k/reference/lexical_analysis.html?highlight=raw%2… "Bytes literals are always prefixed with 'b' or 'B';..." "Both string and bytes literals may optionally be prefixed with a letter 'r' or 'R';..." But that would lead you to believe that to get raw byte strings you should use rb"foo". In fact, that's a SyntaxError in Python 2.6+ and Python 3. What *does* work though is br"foo". Either Python should accept both spellings (harder) or the documentation should make it clear that the 'b' must preceded the 'r'. ---------- assignee: docs@python components: Documentation messages: 150936 nosy: barry, docs@python priority: normal severity: normal status: open title: raw byte strings are described in a confusing way versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13744> _______________________________________

7 11

[issue13915] Update Tutorial 6.1.3 for PEP 3145
by Terry J. Reedy Oct. 12, 2013

Oct. 12, 2013

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: http://docs.python.org/py3k/tutorial/modules.html#compiled-python-files needs to be updated for 3.2+ to reflect http://python.org/dev/peps/pep-3147/ The first sentence is still technically correct, but finding x.pyc in the same directory as x.py is now an anomaly, so that sentence, revised, should be near the bottom. Otherwise, the text should say that the default is to put x.<version>.pyc in __pycache__, where <version> is, for instance, 'cpython-32'. Note that this allows other implementations and other versions of cpython to use the same .py file. I do not know if there is anywhere else that this info is or should be. Using Python?. ---------- assignee: docs@python components: Documentation messages: 152415 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Tutorial 6.1.3 for PEP 3145 type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13915> _______________________________________

5 5