...

...

...

...

"GvR" == Guido van Rossum writes:

GvR> Someone noticed that socket.connect() and a few related GvR> functions (connect_ex() and bind()) take either a single GvR> (host, port) tuple or two separate arguments, but that only GvR> the tuple is documented. GvR> Similar to append(), I'd like to close this gap, and I've GvR> made the necessary changes. This will probably break lots of GvR> code. I don't agree that socket.connect() and friends need this fix. Yes, obviously append() needed fixing because of the application of Tim's Twelfth Enlightenment to the semantic ambiguity. But socket.connect() has no such ambiguity; you may spell it differently, but you know exactly what you mean. My suggestion would be to not break any code, but extend connect's interface to allow an optional second argument. Thus all of these calls would be legal: sock.connect(addr) sock.connect(addr, port) sock.connect((addr, port)) One nit on the documentation of the socket module. The second entry says: bind (address) Bind the socket to address. The socket must not already be bound. (The format of address depends on the address family -- see above.) Huh? What "above" part should I see? Note that I'm reading this doc off the web! -Barry

Barry A. Warsaw writes:

I don't agree that socket.connect() and friends need this fix. Yes, obviously append() needed fixing because of the application of Tim's Twelfth Enlightenment to the semantic ambiguity. But socket.connect() has no such ambiguity; you may spell it differently, but you know exactly what you mean.

Crock. The address representations have been fairly well defined for quite a while. Be explicit.

sock.connect(addr)

This is the only legal signature. (host, port) is simply the form of addr for a particular address family.

One nit on the documentation of the socket module. The second entry says:

bind (address) Bind the socket to address. The socket must not already be bound. (The format of address depends on the address family -- see above.)

Huh? What "above" part should I see? Note that I'm reading this doc off the web!

Definately written for the paper document! Remind me about this again in a month and I'll fix it, but I don't want to play games with this little stuff until the 1.5.2p2 and 1.6 trees have been merged. Harrumph. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

bwarsaw@cnri.reston.va.us writes:

I know, I was being purposefully dense for effect :) Fred, is there some way to make the html contain a link to the previous section for the "see above" text? That would solve the problem I think.

No. I expect this to no longer be a problem when we push to SGML/XML, so I won't waste any time hacking around it. On the other hand, lots of places in the documentation refer to "above" and "below" in the traditional sense used in paper documents, and that doesn't work well for hypertext, even in the strongly traditional book-derivation way the Python manuals are done. As soon as it's not in the same HTML file, "above" and "below" break for a lot of people. So it still should be adjusted at an appropriate time.

Hmm, that /does/ complicate things -- it makes explaining the API more difficult. Still, in this case I think I'd lean toward liberal acceptance of input parameters. :)

No -- all the more reason to be strict and keep the descriptions as simple as reasonable. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

bwarsaw@cnri.reston.va.us writes:

...

I know, I was being purposefully dense for effect :) Fred, is there some way to make the html contain a link to the previous section for the "see above" text? That would solve the problem I think.

[Fred]

No. I expect this to no longer be a problem when we push to SGML/XML, so I won't waste any time hacking around it. On the other hand, lots of places in the documentation refer to "above" and "below" in the traditional sense used in paper documents, and that doesn't work well for hypertext, even in the strongly traditional book-derivation way the Python manuals are done. As soon as it's not in the same HTML file, "above" and "below" break for a lot of people. So it still should be adjusted at an appropriate time.

My approach to this: put more stuff on the same page! I personally favor putting an entire chapter on one page; even if you split the top-level subsections this wouldn't have happened. --Guido van Rossum (home page: http://www.python.org/~guido/)

Guido van Rossum wrote:

Similar to append(), I'd like to close this gap, and I've made the necessary changes. This will probably break lots of code.

Similar to append(), I'd like people to fix their code rather than whine -- two-arg connect() has never been documented, although it's found in much code (even the socket module test code :-( ).

Similar to append(), I may revert the change if it is shown to cause too much pain during beta testing...

proposal: if anyone changes the API for a fundamental module, and fails to update the standard library, the change is automatically "minus one'd" for each major module that no longer works :-) (in this case, that would be -5 or so...) </F>

[Guido, on changing socket.connect() to require a single arg]

... Similar to append(), I may revert the change if it is shown to cause too much pain during beta testing...

I think this one already caused too much pain: it appears virtually everyone uses the two-argument form routinely, and the reason for getting rid of that seems pretty weak. As Tres Seaver just wrote on c.l.py, Constructing a spurious "address" object (which has no behavior, and exists only to be torn apart inside the implementation) seems a foolish consistency, beyond doubt. So offer to back off on this one, in return for making 1/2 yield 0.5 <wink>.

Guido van Rossum writes:

Maybe I'll have to document it as connect(address) with a backwards compatible syntax connect(a, b) being equivalent to connect((a, b)). At least that sets the record straight without breaking old code.

If you *must* support the two-arg flavor (which I've never actually seen outside this discussion), I'd suggest not documenting it as a backward compatibility, only that it will disappear in 1.7. This can be done fairly easily and cleanly in the library reference. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

If you *must* support the two-arg flavor (which I've never actually seen outside this discussion), I'd suggest not documenting it as a backward compatibility, only that it will disappear in 1.7. This can be done fairly easily and cleanly in the library reference.

Yes, I must. Can you fix up the docs? --Guido van Rossum (home page: http://www.python.org/~guido/)

Fred L. Drake wrote:

Skip Montanaro writes:

...

arguments: host and port. It never occurred to me that there would even be a one-argument version. After all, why look at the docs for help if what you're doing already works?

And it never occurred to me that there would be two args; I vaguely recall the C API having one argument (a structure). Ah, well. I've patched up the documents to warn those who expect intuitive APIs. ;)

while you're at it, and when you find the time, could you perhaps grep for "pair" and change places which use "pair" to mean a tuple with two elements to actually say "tuple" or "2-tuple"... after all, numerous people have claimed that stuff like "a pair (host, port)" isn't enough to make them understand that "pair" actually means "tuple". unless pair refers to a return value, of course. and only if the function doesn't use the optional argument syntax, of course. etc. (I suspect they're making it up as they go, but that's another story...) </F>