Mailman 3 August 2013 - docs

[issue16278] os.rename documentation slightly inaccurate
by David Benjamin April 14, 2014

April 14, 2014

New submission from David Benjamin: This is somewhat of a nitpick. os.rename's documentation says "If dst is a directory, OSError will be raised". On Unix, this isn't completely true. If the source is a directory and the destination is an empty directory, it'll overwrite the former with the latter. (Actually if the source is a directory the inverse is true; if dst is a file, OSError will be raised.) In [1]: import os In [2]: os.mkdir("aaa") In [3]: open("aaa/blah", "w").close() In [4]: os.mkdir("bbb") In [5]: os.rename("aaa", "bbb") In [6]: os.listdir("bbb") Out[6]: ['blah'] ---------- assignee: docs@python components: Documentation messages: 173285 nosy: David.Benjamin, docs@python priority: normal severity: normal status: open title: os.rename documentation slightly inaccurate type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16278> _______________________________________

9 44

[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

[issue18456] Documentation for PyDict_Update is incorrect
by Nick Coghlan March 25, 2014

March 25, 2014

New submission from Nick Coghlan: The docs from PyDict_Update (http://docs.python.org/3/c-api/dict.html#PyDict_Update) claim it is equivalent to the Python level dict.update (http://docs.python.org/3/library/stdtypes#dict.update) This isn't accurate - unlike dict.update, PyDict_Update doesn't fall back to the iterating over a sequence of key value pairs if the second argument has no "keys" attribute. ---------- assignee: docs@python components: Documentation messages: 193070 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Documentation for PyDict_Update is incorrect type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18456> _______________________________________

6 6

[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

[issue16665] doc for builtin hex() is poor
by rurpy the second March 16, 2014

March 16, 2014

New submission from rurpy the second: The documentation of the hex() builtin function is poor. Specifically it does not say (directly) that: 1. The resulting string is prefixed with "0x". 2. Any a-f characters used are lower case. 3. Negative integers are converted by prefixing a minus sign to hex() of the absolute value of the argument. 4. It should have a cross reference to the %x format of the "%" operator with a note that it is more veratile than the hex() builtin. 5. It should have a cross reference to the way of performing the inverse operation: hex->int I am not a good writer but here is an attempt at improving it: -------- Convert an integer number to a hexadecimal string. The resulting string is prefixed with "0x" and any alpha characters a-f are lowercase ascii. Negative integers are converted to hex(abs(x)) prefixed with "-". In all cases the result is a valid Python expression. If x is not a Python int object, it has to define an __index__() method that returns an integer. Note: For another more flexible way of converting an integer to hexadecimal see the "x" and "X" conversion types in link:[4.7.2 - printf-style String Formatting] and link:[6.1.3.1 - Format Specification Mini-Language] Note: To convert a hexadecimal string to an integer, use link:[int()] with a radix argument of 16. Note: To obtain a hexadecimal string representation for a float, use the link:[float.hex()] method. -------- ---------- assignee: docs@python components: Documentation messages: 177352 nosy: docs@python, rurpy2 priority: normal severity: normal status: open title: doc for builtin hex() is poor versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16665> _______________________________________

11 16

[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