Mailman 3 June 2013 - docs

[issue18261] Confusing description in Minimal DOM implementation
by Emcisq Zhao 18 Jun '13

18 Jun '13

New submission from Emcisq Zhao: Visit http://docs.python.org/2.7/library/xml.dom.minidom.html, please notice the first paragraph. The last sentence is " should consider using the xml.etree.ElementTree module for their XML processing instead". Shouldn't it be " should consider using the xml.dom.minidom module for their XML processing instead"? ---------- assignee: docs@python components: Documentation messages: 191444 nosy: docs@python, zhjweizhjwei priority: normal severity: normal status: open title: Confusing description in Minimal DOM implementation type: resource usage versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18261> _______________________________________

2 1

[issue1159] os.getenv() not updated after external module uses C putenv()
by Terry J. Reedy 18 Jun '13

18 Jun '13

Terry J. Reedy added the comment: The problem is the 'putenv' and 'getenv' appear to be parallel, and seem to be documented as being parallel "Set the environment variable named key to the string value." "Return the value of the environment variable key if it exists," but they are not. Getenv actually looks up the key in the internal os.environ copy while putenv puts to the actual external environment. This tripped-up someone today on python-list, who did putenv(key, val); getenv(key) and wondered why putenv seemed to have no effect. I think the solution for this should be to document the asymmetry by adding ' in os.environ' after 'key' in the getenv doc. -- putenv should not also update os.environ because one can already do that with "os.environ[key] = value" (as recommended) and because the latter uses putenv *if available* to also update the external environment *if possible*. Note that at the time this system was designed, not all systems supported putenv (and perhaps not 'true' getenv either). getenv(key) is not the same as os.environ[key] because the former has an optional 'default' parameter that defaults to None. So aside from back-compatibility, I do not think the behavior of existing code should change. A new parameter might be possible. To implement it, one would have to augment the underlying, undocumented, C-coded (for CPython) os-specific module -- posix, nt, os2, ce -- to define a new os-specific getenv function that parallels the os-specific putenv function. Adding os.environ.update (or .synchronize) to resynchronize os.environ with the external environment would also require a new os-specific function. Currently, the original os.environ is imported as a *data* attribute of the os-specific module. However, neither of these changes are needed for python code that used os.environ as intended. I don't think we should necessarily cater to badly written C libraries that modify the enviroment in a way that cannot be easily intercepted or controlled. So after making a doc change, I would be inclined to close this pending a python-ideas discussion that supported a new feature. ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python, terry.reedy versions: +Python 2.7, Python 3.3, Python 3.4 -Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1159> _______________________________________

1 0

[issue16901] In http.cookiejar.FileCookieJar() the .load() and .revert() methods don't work
by Martin Panter 17 Jun '13

17 Jun '13

Changes by Martin Panter <vadmium+py(a)gmail.com>: ---------- nosy: +vadmium _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16901> _______________________________________

1 0

Error in Section 3.1.2. of The Python Tutorial
by Christopher Brautigam 17 Jun '13

17 Jun '13

To whom it may concern, I believe I have found a minor error in the example given on String "slicing" in section 3.1.2. "Strings" of "The Python Tutorial" documentation. The error concerns the first example of slicing given (where the variable "word" is equal to "Python"), which reads: >>> word[0:2] # characters from position 0 (included) to 2 (excluded)'Py'>>> word[2:5] # characters from position 2 (included) to 4 (excluded)'tho' I believe the second comment is incorrect as the character at the 4th index "o" is included. I propose that the comment should be changed so that "excluded" is changed to "included" as below: >>> word[0:2] # characters from position 0 (included) to 2 (excluded)'Py'>>> word[2:5] # characters from position 2 (included) to 4 (included)'tho' This could also be solved by changing the 4 to a 5 however that statement would be making the same point as the first and would therefore be redundant. Kind Regards, Christopher Brautigam

1 0

[issue18245] In itertools.groupby() make data plural
by py.user 17 Jun '13

17 Jun '13

New submission from py.user: http://en.wiktionary.org/wiki/data "data (uncountable) or plural noun" ---------- assignee: docs@python components: Documentation files: issue.diff keywords: patch messages: 191354 nosy: docs@python, py.user priority: normal severity: normal status: open title: In itertools.groupby() make data plural versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file30624/issue.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18245> _______________________________________

4 4

[issue18176] Builtins documentation refers to old version of UCD.
by Alexander Belopolsky 16 Jun '13

16 Jun '13

Alexander Belopolsky added the comment: I have found another place where explicit UCD version is used in the docs: Doc/reference/lexical_analysis.rst:729:.. [#] http://www.unicode.org/Public/6.1.0/ucd/NameAliases.txt I am not sure how this case should be handled. The language reference was deliberately written so that it avoids mentioning specific version of Unicode. For example, PropList.txt in the "Identifiers and keywords" section is linked to the location of the latest published PropList.txt: <http://unicode.org/Public/UNIDATA/PropList.txt>. This means that as of today, all versions of documentation (3.0 through 3.4) refere to Unicode 6.2.0 version of this file. This may be misleading for the users of the older python versions. In the same section, there is a reference top a "non-normative HTML file listing all valid identifier characters for Unicode 4.1." I would suggest that instead of linking to an external resource we generate a similar table (possibly in ReST format) in makeunicodedata.py and include it with documentation. ---------- nosy: +loewis _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18176> _______________________________________

1 0

Typo in 3.3 tutorial
by Neil Kelleher 16 Jun '13

16 Jun '13

File: http://docs.python.org/3.3/tutorial/introduction.html Section: 3.1.2. Strings There is a typo in this block ===BLOCK START=== In addition to indexing, slicing is also supported. While indexing is used to obtain individual characters, slicing allows you to obtain substring: >>> >>> word[0:2] # characters from position 0 (included) to 2 (excluded) 'Py' >>> word[2:5] # characters from position 2 (included) to 4 (excluded) 'tho' ===BLOCK END=== The comment on the 2nd last line should read # characters from position 2 (included) to 5 (excluded) Regards Neil

1 0

[issue18176] Builtins documentation refers to old version of UCD.
by Alexander Belopolsky 16 Jun '13

16 Jun '13

Alexander Belopolsky added the comment: Here is what grep revealed: $ find Doc -name \*.rst | xargs grep -n '6\.2\.0' Doc/library/stdtypes.rst:357: See http://www.unicode.org/Public/6.2.0/ucd/extracted/DerivedNumericType.txt Doc/library/unicodedata.rst:18:this database is compiled from the `UCD version 6.2.0 Doc/library/unicodedata.rst:19:<http://www.unicode.org/Public/6.2.0/ucd>`_. Doc/library/unicodedata.rst:169:.. [#] http://www.unicode.org/Public/6.2.0/ucd/NameAliases.txt Doc/library/unicodedata.rst:171:.. [#] http://www.unicode.org/Public/6.2.0/ucd/NamedSequences.txt I added a note next to UNIDATA_VERSION = "6.2.0" in makeunicodedata.py script. The makeunicodedata.py would be a place to put code that would update the docs automatically, but with only two affected files I don't think this is worth the effort. Chances are at least unicodedata.rst will benefit from a manual review to reflect any substantive changes in the UCD. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18176> _______________________________________

1 0

[issue18176] Builtins documentation refers to old version of UCD.
by Alexander Belopolsky 16 Jun '13

16 Jun '13

Changes by Alexander Belopolsky <alexander.belopolsky(a)gmail.com>: Added file: http://bugs.python.org/file30608/bd092995907c.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18176> _______________________________________

1 0

[issue14015] surrogateescape largely missing from documentation
by Jim Jewett 16 Jun '13

16 Jun '13

New submission from Jim Jewett <jimjjewett(a)gmail.com>: Recent discussion on the mailing lists and in http://bugs.python.org/issue13997 make it clear that the best way to get python2 results for "ASCII-in-the-parts-I-might-process-or-change" is to replace f = open(fname) with f = open(fname, encoding="ascii", errors="surrogateescape") Unfortunately, surrogateescape (let alone this recipe) is not easily discoverable. http://docs.python.org/dev/library/functions.html#open lists 5 error-handlers -- but not this one. It says that other error handlers are possible if they are registered with http://docs.python.org/dev/library/codecs.html#codecs.register_error but I haven't found a way to determine which error handlers are already registered. The codecs.register (as opposed to register_error) documentation does list it as a possible value, but that is the only reference. The other 5 error handlers are also available as module-level functions within the codecs module, and have their own documenation sections within http://docs.python.org/dev/library/codecs.html Neither help(open) nor import codecs; help(codecs) provides any hints of the existence of surrogateescape. Both explicitly suggest that it does not exist, by enumerating other values. ---------- assignee: docs@python components: Documentation, Unicode messages: 153359 nosy: Jim.Jewett, docs@python, ezio.melotti priority: normal severity: normal status: open title: surrogateescape largely missing from documentation versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14015> _______________________________________

5 5