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.

This might be a good place to use the newly-documented "positional-only" nomenclature:

http://docs.python.org/2.7/glossary.html#term-parameter

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?

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?

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

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

In that case I think it's OK to use the [] and mention the default values in the text.

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

Fixed, thanks for the report!