Mailman 3 October 2012 - docs

[issue10481] subprocess PIPEs are byte streams
by Glenn Linderman April 14, 2014

April 14, 2014

New submission from Glenn Linderman <v+python(a)g.nevcal.com>: While http://bugs.python.org/issue2683 did clarify the fact that the .communicate API takes a byte stream as input, it is easy to miss the implication. Because Python programs start up with stdin as a text stream, it might be good to point out that some action may need to be taken to be sure that the receiving program expects a byte stream, or that the byte stream supplied should be in an encoding that the receiving program is expecting and can decode appropriately. No mention is presently made in the documentation for .communicate that its output is also a byte stream, and if text will correspond to whatever encoding is used by the sending program. ---------- assignee: docs@python components: Documentation messages: 121869 nosy: docs@python, v+python priority: normal severity: normal status: open title: subprocess PIPEs are byte streams versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10481> _______________________________________

4 5

[issue15067] sqlite3 docs reference PEP 246, which was rejected
by Zachary Ware April 1, 2014

April 1, 2014

New submission from Zachary Ware <zachary.ware(a)gmail.com>: See: http://hg.python.org/cpython/file/d31e83497c5a/Doc/library/sqlite3.rst#l708 PEP 246 is headed by: """ Rejection Notice I'm rejecting this PEP. Something much better is about to happen; it's too early to say exactly what, but it's not going to resemble the proposal in this PEP too closely so it's better to start a new PEP. GvR. """ I don't know what the "something much better" was/is, so I have no idea how that line in the docs should be replaced, but I don't think the PEP 246 reference is valid. Thanks, Zach ---------- assignee: docs@python components: Documentation messages: 162797 nosy: docs@python, ghaering, zach.ware priority: normal severity: normal status: open title: sqlite3 docs reference PEP 246, which was rejected versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15067> _______________________________________

4 12

[issue12209] Minor edits to faulthandler doc
by Éric Araujo March 25, 2014

March 25, 2014

New submission from Éric Araujo <merwok(a)netwok.org>: I made some grammar fixes in faulthandler.rst and tweaked the example to better show what the module does. I’d like to fix the synopsis too: “dump the Python traceback” is not very clear to me. It is the traceback or the stack trace? Why is it called “the” traceback? Something like “dumping the stack trace on CPython crashes” would be better IMO. ---------- assignee: docs@python components: Documentation files: faulthandler-doc.diff keywords: needs review, patch messages: 137206 nosy: docs@python, eric.araujo, haypo priority: normal severity: normal stage: patch review status: open title: Minor edits to faulthandler doc versions: Python 3.3 Added file: http://bugs.python.org/file22177/faulthandler-doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12209> _______________________________________

3 7

[issue11481] The copy module already uses copyreg
by Daniel Urban March 24, 2014

March 24, 2014

New submission from Daniel Urban <urban.dani+py(a)gmail.com>: In the copyreg documentation there is this sentence: "The copy module is likely to use this in the future as well." (http://docs.python.org/dev/py3k/library/copyreg) But the copy module already uses the copyreg module. ---------- assignee: docs@python components: Documentation messages: 130732 nosy: docs@python, durban priority: normal severity: normal status: open title: The copy module already uses copyreg versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11481> _______________________________________

5 5

[issue13437] Provide links to the source code for every module in the documentation
by Julian Berman March 19, 2014

March 19, 2014

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The documentation occasionally contains a link to the source code for a module in the stdlib. See for instance http://docs.python.org/library/urlparse.html and http://docs.python.org/library/collections.html , or many others. With a quick perusal, I couldn't immediately guess as to which ones managed to have one and which ones don't, but it'd be convenient to have a link in as many places as possible, which is certainly more than we have now. (See e.g. http://docs.python.org/library/json.html and http://docs.python.org/library/itertools.html and many others for examples of pages that lack a link). Perhaps putting it in a more conspicuous but still consistent location would be reasonable (the sidebar?). ---------- assignee: docs@python components: Documentation messages: 147973 nosy: Julian, docs@python priority: normal severity: normal status: open title: Provide links to the source code for every module in the documentation type: feature request versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13437> _______________________________________

6 14

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous
by Ryan Kelly March 16, 2014

March 16, 2014

New submission from Ryan Kelly <ryan(a)rfk.id.au>: The docs for HTTPConnection.set_tunnel(host,port) are ambiguous. They simply say "Set the host and the port for HTTP Connect Tunnelling". But should I specify the address of the server *through* which I want to tunnel, or the address of the *endpoint* of the tunnel? Turns out it's the latter, but I just wasted an hour "debugging" thinking it was the former :-( Attached is a simple doc patch to try to clarify this issue. ---------- assignee: docs@python components: Documentation files: set_tunnel_doc.diff keywords: patch messages: 130396 nosy: docs@python, rfk priority: normal severity: normal status: open title: docs for HTTPConnection.set_tunnel are ambiguous versions: Python 3.3 Added file: http://bugs.python.org/file21056/set_tunnel_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11448> _______________________________________

8 14

[issue12901] Nest class/methods directives in documentation
by Éric Araujo March 15, 2014

March 15, 2014

New submission from Éric Araujo <merwok(a)netwok.org>: I picked up a few files in Doc/library and updated their markup to use directives nesting. The attached patch is the result; it’s a lot of changes for small benefit. If we think it’s a good change anyway, I have two questions - Do you think it would be a good idea to have the -checkins emails ignore whitespace changes in some cases? (I’m thinking a magic string in the commit message) - A number of files have a class directive near the top of the file, in the list of all public names, and a later section “XX objects” with the methods and attributes. When this is changed to nested class/methods directives, sometimes the first class directive gets a noindex flag, but I think it should jsut be removed: the index in the sidebar is enough to let people jump to the doc. Do you agree? ---------- assignee: docs@python components: Documentation messages: 143552 nosy: benjamin.peterson, docs@python, eric.araujo, georg.brandl priority: normal severity: normal status: open title: Nest class/methods directives in documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12901> _______________________________________

3 5

[issue12354] packaging.pypi.simple docs use both client and crawler variable, which might be confusing
by Filip Gruszczyński March 13, 2014

March 13, 2014

New submission from Filip Gruszczyński <gruszczy(a)gmail.com>: In documentation for packaging.pypi.simple in first code snippet crawler variable is created on which further operations will be performed. However in all next snippets there is client variable, which is a little confusing on first sight. This could be consistent throughout the whole page. ---------- assignee: docs@python components: Distutils2, Documentation messages: 138538 nosy: alexis, docs@python, eric.araujo, gruszczy priority: normal severity: normal status: open title: packaging.pypi.simple docs use both client and crawler variable, which might be confusing versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12354> _______________________________________

4 9

[issue15231] update PyPI upload doc to say --no-raw passed to rst2html.py
by Chris Jerdonek March 12, 2014

March 12, 2014

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I had an issue whereby my reST long_description wasn't getting rendered as HTML when uploaded to PyPI. Following the instructions here did not work as-is: http://docs.python.org/dev/distutils/uploading.html#pypi-package-display It seems that PyPI passes --no-raw (no HTML allowed) to rst2html.py, in which case the guidance would be better updated to read-- $ python setup.py --long-description | rst2html.py --no-raw > output.html ---------- assignee: docs@python components: Documentation keywords: easy messages: 164445 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: update PyPI upload doc to say --no-raw passed to rst2html.py versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15231> _______________________________________

5 39

[issue13530] Docs for os.lseek neglect to mention what it returns
by Ned Batchelder March 11, 2014

March 11, 2014

New submission from Ned Batchelder <ned(a)nedbatchelder.com>: The docs for os.lseek don't make any mention of its return value. I believe it's the new offset in the file, but I'm not sure if there are other subtleties to be mentioned. ---------- assignee: docs@python components: Documentation messages: 148861 nosy: docs@python, nedbat priority: normal severity: normal status: open title: Docs for os.lseek neglect to mention what it returns versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13530> _______________________________________

9 10