[issue16666] docs wrongly imply socket.getaddrinfo takes keyword arguments in 2.x
New submission from Mikel Ward: The docs for 2.6 and 2.7 say socket.getaddrinfo takes keyword arguments. http://docs.python.org/release/2.6.6/library/socket.html?highlight=socket#so...
socket.getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)
But that doesn't actually work in Python 2.7. $ ./python Python 2.7.3+ (2.7:ec4ea40be2f6, Dec 11 2012, 14:43:35) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information.
Looks like it was introduced in 61999:c963478b9092. ---------- assignee: docs@python components: Documentation messages: 177356 nosy: Mikel.Ward, docs@python priority: normal severity: normal status: open title: docs wrongly imply socket.getaddrinfo takes keyword arguments in 2.x versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: This might be a good place to use the newly-documented "positional-only" nomenclature: http://docs.python.org/2.7/glossary.html#term-parameter ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Éric Araujo added the comment: There are two or three issues on this tracker where we discuss the parameters notation conventions. I think I remember a proposal to add text explaining that the keyword notation does not imply that the function accepts keyword argument, only that there is a default value. Chris, does that ring a bell? ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: Is issue 13386 one of the issues you had in mind, Éric? I don't know the current best practices for all of the signature edge cases, but Ezio might. Personally, I think explicitly stating in the text that the parameters are positional-only can't hurt, especially since that's the rarer case, no? ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment:
OTOH it's an implementation detail that might be changed at some point. The other option is to use [] in the signature and document the default values in the text, and possibly fix it for 3.4 (or does it work there already?). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: This issue only applies to 2.7. Keyword arguments are accepted in 3.x. See the interactive example here, for example: http://docs.python.org/3.2/library/socket.html#socket.getaddrinfo ---------- versions: -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment: In that case I think it's OK to use the [] and mention the default values in the text. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Roundup Robot added the comment: New changeset 1e5e7064e872 by Ezio Melotti in branch '2.7': #16666: document default values for socket.getaddrinfo in the text to clarify that it doesn't accept keyword args. http://hg.python.org/cpython/rev/1e5e7064e872 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the report! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: -> committed/rejected status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: This might be a good place to use the newly-documented "positional-only" nomenclature: http://docs.python.org/2.7/glossary.html#term-parameter ---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Éric Araujo added the comment: There are two or three issues on this tracker where we discuss the parameters notation conventions. I think I remember a proposal to add text explaining that the keyword notation does not imply that the function accepts keyword argument, only that there is a default value. Chris, does that ring a bell? ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: Is issue 13386 one of the issues you had in mind, Éric? I don't know the current best practices for all of the signature edge cases, but Ezio might. Personally, I think explicitly stating in the text that the parameters are positional-only can't hurt, especially since that's the rarer case, no? ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment:
OTOH it's an implementation detail that might be changed at some point. The other option is to use [] in the signature and document the default values in the text, and possibly fix it for 3.4 (or does it work there already?). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Chris Jerdonek added the comment: This issue only applies to 2.7. Keyword arguments are accepted in 3.x. See the interactive example here, for example: http://docs.python.org/3.2/library/socket.html#socket.getaddrinfo ---------- versions: -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment: In that case I think it's OK to use the [] and mention the default values in the text. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Roundup Robot added the comment: New changeset 1e5e7064e872 by Ezio Melotti in branch '2.7': #16666: document default values for socket.getaddrinfo in the text to clarify that it doesn't accept keyword args. http://hg.python.org/cpython/rev/1e5e7064e872 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
Ezio Melotti added the comment: Fixed, thanks for the report! ---------- assignee: docs@python -> ezio.melotti resolution: -> fixed stage: -> committed/rejected status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16666> _______________________________________
participants (6)
-
Andrew Svetlov -
Chris Jerdonek
-
Ezio Melotti
-
Mikel Ward
-
Roundup Robot
-
Éric Araujo