classification
Title: docs wrongly imply socket.getaddrinfo takes keyword arguments in 2.x
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Mikel.Ward, asvetlov, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, python-dev
Priority: normal Keywords:

Created on 2012-12-11 23:00 by Mikel.Ward, last changed 2012-12-25 12:47 by ezio.melotti. This issue is now closed.

Messages (9)
msg177356 - (view) Author: Mikel Ward (Mikel.Ward) Date: 2012-12-11 23:00
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#socket.getaddrinfo

> 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.

>>> import socket
>>> s = socket.getaddrinfo('localhost', 999, family=socket.AF_INET)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: getaddrinfo() takes no keyword arguments

Looks like it was introduced in 61999:c963478b9092.
msg177362 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-12 03:25
This might be a good place to use the newly-documented "positional-only" nomenclature:

http://docs.python.org/2.7/glossary.html#term-parameter
msg177423 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-12-13 17:13
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?
msg177427 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-13 17:56
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?
msg177430 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-13 18:24
> 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?

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?).
msg177433 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-12-13 19:26
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
msg177435 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-13 20:13
In that case I think it's OK to use the [] and mention the default values in the text.
msg178121 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-12-25 12:46
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
msg178122 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-25 12:47
Fixed, thanks for the report!
History
Date User Action Args
2012-12-25 12:47:59ezio.melottisetstatus: open -> closed
type: enhancement
messages: + msg178122

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: resolved
2012-12-25 12:46:29python-devsetnosy: + python-dev
messages: + msg178121
2012-12-13 20:13:38ezio.melottisetmessages: + msg177435
2012-12-13 19:26:42chris.jerdoneksetmessages: + msg177433
versions: - Python 2.6
2012-12-13 18:24:53ezio.melottisetmessages: + msg177430
2012-12-13 17:56:06chris.jerdoneksetnosy: + ezio.melotti
messages: + msg177427
2012-12-13 17:13:40eric.araujosetnosy: + eric.araujo
messages: + msg177423
2012-12-13 16:40:05asvetlovsetnosy: + asvetlov
2012-12-12 03:25:11chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg177362
2012-12-11 23:00:09Mikel.Wardcreate