Mailman 3 February 2011 - docs

[issue10741] PyGILState_GetThisThreadState() lacks a doc entry
by Antoine Pitrou Aug. 7, 2011

Aug. 7, 2011

New submission from Antoine Pitrou <pitrou(a)free.fr>: PyGILState_GetThisThreadState() is "documented" in Include/pystate.h but not in the official docs. It should be documented along PyGILState_Ensure() and friends. ---------- assignee: docs@python components: Documentation messages: 124394 nosy: docs@python, haypo, pitrou priority: normal severity: normal status: open title: PyGILState_GetThisThreadState() lacks a doc entry versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10741> _______________________________________

3 3

[issue11047] Bad description for a change
by Oren Held Aug. 6, 2011

Aug. 6, 2011

New submission from Oren Held <oren(a)held.org.il>: In the "what's new in 2.7", there is some mistake in the description of issue 7902. 7902, afaik, disables the fallback to absolute import, when requesting a relative import fails. If I got it right, the description states the opposite. ---------- assignee: docs@python components: Documentation files: whatsnew_issue_7902_fix.patch keywords: patch messages: 127317 nosy: Oren_Held, docs@python priority: normal severity: normal status: open title: Bad description for a change versions: Python 2.7 Added file: http://bugs.python.org/file20577/whatsnew_issue_7902_fix.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11047> _______________________________________

5 4

[issue8982] argparse docs cross reference Namespace as a class but the Namespace class is not documented
by R. David Murray July 29, 2011

July 29, 2011

New submission from R. David Murray <rdmurray(a)bitdance.com>: I wanted to find out if Namespace supported lookup by subscripting (args['someopt']), but the docs are silent on what Namespace is. (The answer, by the way, appears to be "no"; there is a feature request for this in issue 8979). ---------- assignee: bethard components: Documentation messages: 107653 nosy: bethard, docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: argparse docs cross reference Namespace as a class but the Namespace class is not documented type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8982> _______________________________________

4 9

[issue10403] Use "member" consistently
by Fred L. Drake, Jr. July 17, 2011

July 17, 2011

New submission from Fred L. Drake, Jr. <fdrake(a)acm.org>: Some portions of the documentation are using the term "member" to mean "data attribute". This appears to be an aberration at this time, but occurrences should be identified and corrected, and "Documenting Python" updated to note correct usage. Example use: http://docs.python.org/dev/py3k/library/xmlrpc.client.html#fault-objects http://docs.python.org/dev/py3k/library/urllib.request.html#basehandler-obj… (paragraph starting "The following members and methods should") "Members and methods" should just be "attributes". ---------- assignee: docs@python components: Documentation messages: 121110 nosy: docs@python, fdrake priority: normal severity: normal status: open title: Use "member" consistently _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10403> _______________________________________

9 24

[issue9312] Fix usage of :option: markup in stdlib ReST docs
by Eli Bendersky June 9, 2011

June 9, 2011

New submission from Eli Bendersky <eliben(a)gmail.com>: Due to a discussion on python-dev (Subject: "Markup of command-line options in Python's .rst documentation"), Georg Brandl checked in revision r82961 with a clarification of :option: markup which should only be used for Python interpreter's own flags. However, several modules in stdlib use :option: for their own command-line options, which creates confusion (these options get linked by Sphinx to unrelated Python options). I'm attaching a patch that fixes this issue for these files. The affected files are: Doc/library/idle.rst Doc/library/timeit.rst Doc/library/test.rst Doc/library/doctest.rst Doc/library/unittest.rst Doc/library/pydoc.rst Doc/library/webbrowser.rst Doc/library/compileall.rst Note1: :option: was fixed to `` markup (code snippet) as per the recommendation in the updated documentation guide Note2: I didn't patch trace.rst because it's overgoing a major rehaul (http://bugs.python.org/issue9264) ---------- assignee: docs@python components: Documentation messages: 110862 nosy: docs@python, eli.bendersky priority: normal severity: normal status: open title: Fix usage of :option: markup in stdlib ReST docs type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________

6 26

[issue11203] gzip doc is behind
by K Richard Pixley June 9, 2011

June 9, 2011

New submission from K Richard Pixley <rich(a)noir.com>: The documentation for gzip should include the "close" method. It's use in the 2.7 documentation implies it's existence but it should also be stated explicitly that it exists. In the 3.x documentation, the use of "close" not in the examples since the examples use context manager. For 3.x documentation there should be both an explicit mention of the "close" method as well as an explicit mention that GzipFile supports the context manager protocol. Yes, the use of the context manager in the examples implies that this is true but documentation on other modules states so explicitly so this module should too. ---------- assignee: docs@python components: Documentation messages: 128460 nosy: docs@python, teamnoir priority: normal severity: normal status: open title: gzip doc is behind type: feature request versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11203> _______________________________________

4 11

[issue9738] Document the encoding of functions bytes arguments of the C API
by STINNER Victor May 30, 2011

May 30, 2011

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: Many C functions have bytes argument (char* type) but the encoding is not documented. If would not be a problem if the encoding was always the same, but it is not. Examples: - format of PyUnicode_FromFormat() should be encoded as ISO-8859-1 - filename of PyParser_ASTFromString() should be encoded as utf-8 - filename of PyErr_SetFromErrnoWithFilename() should be encoded to the filesystem encoding (with strict error handler, and not surrogateescape) - 's' argument of PyParser_ASTFromString() should be encoded as utf-8 if PyPARSE_IGNORE_COOKIE flag is set, otherwise the parser checks for #coding:xxx cookie (if there is no cookie, utf-8 is used) Attached patch is a try to document most low level functions. I choosed to add the name of function arguments in the headers because I consider that a header can be used as a quick documentation. I only touched .c files to change argument names. It is hard to get the right encoding, so I cannot ensure that my patch is correct. My patch is just a draft. I don't know if "encoded to utf-8" is the right expression. Or should it be "decoded as utf-8"? ---------- assignee: docs@python components: Documentation, Interpreter Core, Unicode files: encodings.patch keywords: patch messages: 115339 nosy: docs@python, haypo priority: normal severity: normal status: open title: Document the encoding of functions bytes arguments of the C API versions: Python 3.2 Added file: http://bugs.python.org/file18705/encodings.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9738> _______________________________________

5 12

[issue9382] os.popen referenced but not documented in Python 3.x
by Chris Rebert May 30, 2011

May 30, 2011

New submission from Chris Rebert <pybugs(a)rebertia.com>: http://docs.python.org/py3k/library/os.html currently mentions os.popen() in several places. The docs for os.popen() itself say: 'These functions are described in section "File Object Creation"' However, unlike the 2.x version of that section ( http://docs.python.org/library/os.html#file-object-creation ), the os.popen*() family is not documented there [or indeed anywhere] anymore ( http://docs.python.org/py3k/library/os.html#os-newstreams ); the entire section now only documents os.fdopen(). The 2.7 docs say that the os.popen*() family are deprecated, and indeed, of the family, only os.popen() seems to still exist in Python 3.x (at least based on my testing via ideone.com). Thus, from what I can see, one of the following is the case: (A) The entire os.popen*() family is supposed be gone in Python 3.x, so os.popen() should be removed entirely from both the code and the docs. (B) os.popen() is the sole legitimate survivor of its family, and should be properly documented again. (C) os.popen() was left in as a kludge, shouldn't be mentioned in the docs, and possibly should be renamed os._popen() to reflect its status. So, which one of these is it? ---------- assignee: docs@python components: Documentation messages: 111597 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: os.popen referenced but not documented in Python 3.x versions: Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

6 6

[issue10912] PyObject_RichCompare differs in behaviour from PyObject_RichCompareBool ; difference not noted in documentation
by Devin Jeanpierre April 30, 2011

April 30, 2011

New submission from Devin Jeanpierre <jeanpierreda(a)gmail.com>: PyObject_RichCoareBool is, according to the documentation in trunk (Doc\c-api\object.rst), exactly the same as PyObject_RichCompare, except it 1, 0, or -1 for error, false, and true respectively. However, it differs in behavior by both that, and also by assuming that identity implies equality. This noted in a two year-old ML post (sadly, no bug report was posted as best as I can find): http://mail.python.org/pipermail/python-list/2009-March/1195170.html Ideally PyObject_RichCompareBool should probably be named something else, since it can no longer be used, strictly, as "PyObject_RichCompare, but returning a C bool" (or, rather, a C int). Some suggestions were offered in the mailing list thread above. I'm filing this as a documentation bug because I find that outcome unlikely. At least the documentation should note the difference in behavior, so that people do not accidentally write C code that does not behave as intended. This issue is related to, but different from issue 4296, which objected to the new container behavior created by the change to PyObject_RichCompareBool. My only objection here is that the latter change does not appear to be documented. I would supply a patch for the tests, but PyObject_RichCompareBool is apparently not directly tested anywhere, just tested obliquely through testing the containment operator, and this was changed by the same commit that changed PyObject_RichCompareBool. I don't know how to word the (very small!) change to the docs. ---------- assignee: docs@python components: Documentation messages: 126306 nosy: Devin Jeanpierre, docs@python priority: normal severity: normal status: open title: PyObject_RichCompare differs in behaviour from PyObject_RichCompareBool ; difference not noted in documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10912> _______________________________________

7 17

Re: [docs] Suggested improvement to turtle module doc
by Alexander Belopolsky April 28, 2011

April 28, 2011

Hi Richard, Thank you for your report. Please take a look at the discussion of various improvements to turtle documentation at <http://bugs.python.org/issue7061>. Please see more answers below. .. > It took me far longer than it should have to figure out how to do the > most basic thing: from an interactive prompt (or elsewhere!) get the > turtle window up and have a controllable turtle. In the end I just > guessed and created a Turtle and it worked - though I still struggle to > see where this is mentioned in the docs. > We have recently added a sidebar to the introduction in the turtle manual that should help newcomers. See <http://docs.python.org/dev/library/turtle.html>. > I believe the docs would benefit greatly from a simple example right at > the top like: > > """ > The easiest method of getting started is to open an interactive prompt > and type: > >>>> from turtle import * >>>> turtle = Turtle() > .. The turtle module provides both procedural and object-oriented interfaces. In my opinion, beginners should start with the procedural interface and this is what is now used in the sidebar. It is unfortunate that the manual uses "turtle" for both the name of the module and the name of the turtle instance used in OO examples. Any suggestions on how to improve this are welcome.

2 1