Mailman 3 March 2014 - docs

[issue20199] status of module_for_loader and utils._module_to_load
by R. David Murray 17 Mar '14

17 Mar '14

New submission from R. David Murray: The whatsnew currently says that module_for_loader is pending deprecation in favor of utils.module_to_load, but there is no such function. Instead there is a private function utils._module_to_load...even though there is a news entry that claimed that the non-private name was added (but there are no docs for it, nor any associated issue number). So, importlib experts, can you clean up the docs and/or code please? :) ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 207723 nosy: brett.cannon, docs@python, eric.snow, r.david.murray priority: normal severity: normal stage: needs patch status: open title: status of module_for_loader and utils._module_to_load type: behavior versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20199> _______________________________________

5 12

[issue14332] Better explain "junk" concept in difflib doc
by Alba Magallanes 17 Mar '14

17 Mar '14

Alba Magallanes added the comment: I would like to help with this issue. I'm attaching a patch for it. ---------- keywords: +patch nosy: +albamagallanes Added file: http://bugs.python.org/file34451/issue14332.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14332> _______________________________________

1 0

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous
by Ryan Kelly 16 Mar '14

16 Mar '14

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

[issue20950] asyncio.docs : asyncio.subprocess.Process.wait() method typo
by Alexandre JABORSKA 16 Mar '14

16 Mar '14

New submission from Alexandre JABORSKA: The asyncio.subprocess.Process.wait() documentation mention "self" parameter (typo ?) and don't tell it's a coroutine. ---------- assignee: docs@python components: Documentation messages: 213753 nosy: ajaborsk, docs@python priority: normal severity: normal status: open title: asyncio.docs : asyncio.subprocess.Process.wait() method typo type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20950> _______________________________________

3 2

[issue4744] asynchat documentation needs to be more precise
by Nitika Agarwal 16 Mar '14

16 Mar '14

Nitika Agarwal added the comment: Hi, Please review my patch attached.Any comments and feedback are welcome. ---------- keywords: +patch Added file: http://bugs.python.org/file34442/issue4744_2.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4744> _______________________________________

1 0

[issue4744] asynchat documentation needs to be more precise
by Nitika Agarwal 16 Mar '14

16 Mar '14

Nitika Agarwal added the comment: Hi, I would like to propose a patch for this issue. ---------- nosy: +nitika _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue4744> _______________________________________

1 0

[issue20931] Confusing section title "New Expected Features for Python Implementations" in 3.4 What's New doc
by Ned Deily 16 Mar '14

16 Mar '14

New submission from Ned Deily: The 3.4 What's New document has a section entitled "New expected features for Python implementations", a title not found in previous releases. I believe that the intention is to document features expected to be implemented by all Python implementations, including non CPython ones, when they claim to support 3.4. However, I think the wording is likely to be misunderstood by most readers as meaning "features expected to be in the 3.4 release (including CPython)", leaving a question in their minds as to whether all of the described features are actually in the 3.4 release. On the other hand, AFAIK, the standard documentation set has never attempted to document all of the deviations from CPython for each particular non-CPython implementation; if the wording is understood as intended, it could be construed as implying something that isn't true. So, under either reading, the wording can be misleading. I think it should just be removed or reworded as "New Features". http://docs.python.org/3.4/whatsnew/3.4.html#summary-release-highlights http://docs.python.org/3.4/whatsnew/3.4.html#new-expected-features-for-pyth… ---------- assignee: docs@python components: Documentation messages: 213617 nosy: docs@python, larry, ncoghlan, ned.deily priority: normal severity: normal status: open title: Confusing section title "New Expected Features for Python Implementations" in 3.4 What's New doc versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20931> _______________________________________

5 10

[issue16665] doc for builtin hex() is poor
by rurpy the second 16 Mar '14

16 Mar '14

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

[issue20902] Which operand is preferred by set operations? Missing information in the documentation
by Giacomo Alzetta 15 Mar '14

15 Mar '14

New submission from Giacomo Alzetta: Currently the documentation for set (at: http://docs.python.org/2/library/stdtypes.html#set) does not mention which operand is preferred when performing the usual binary operations. For example the following sample code doesn't have a defined result according to the documentation: class MyObj: def __init__(self, key, value): self.key = key self.value = value def __key(self): return self.key def __hash__(self): return hash(self.__key()) def __eq__(self, other): return type(self) is type(other) and self.__key() == other.__key() a = {MyObj(1, 'a')} b = {MyObj(1, 'b')} print((a & b).pop().value) # 'a' or 'b'? As far as I can tell currently there is no rule about this. Intersection prefers the second operand, while union prefers the first. These are the only operations where this is important since they include common elements. I believe that this kind of information ought to be included explicitly near such operations. At the very least, if the behaviour should really be somehow undefined, it should be stated there so that people don't rely on such behaviour. The same should be stated for |= and &=, since the first will not modify common elements while the latter will. PS: I can't find any resource about the formatting of issues (e.g. if and which syntax is used for code blocks. Sorry for that. ---------- assignee: docs@python components: Documentation messages: 213305 nosy: Giacomo.Alzetta, docs@python priority: normal severity: normal status: open title: Which operand is preferred by set operations? Missing information in the documentation type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20902> _______________________________________

8 12

[issue20938] Broken link to editors page in General FAQ
by Ben W. 15 Mar '14

15 Mar '14

New submission from Ben W.: The link to http://www.python.org/editors/ at the bottom of the answer to "Is Python a good language for beginning programmers?" in the General Python FAQ is broken. ---------- assignee: docs@python components: Documentation messages: 213671 nosy: docs@python, lopsided98 priority: normal severity: normal status: open title: Broken link to editors page in General FAQ type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20938> _______________________________________

4 3