Heads up: socket.connect() breakage ahead
Someone noticed that socket.connect() and a few related functions (connect_ex() and bind()) take either a single (host, port) tuple or two separate arguments, but that only the tuple is documented. 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... --Guido van Rossum (home page: http://www.python.org/~guido/)
"GvR" == Guido van Rossum <guido@python.org> 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
"GvR" == Guido van Rossum <guido@python.org> 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))
You probably meant: sock.connect(addr) sock.connect(host, port) sock.connect((host, port)) since (host, port) is equivalent to (addr).
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!
Fred typically directs latex2html to break all sections apart. It's in the previous section: Socket addresses are represented as a single string for the AF_UNIX address family and as a pair (host, port) for the AF_INET address family, where host is a string representing either a hostname in Internet domain notation like 'daring.cwi.nl' or an IP address like '100.50.200.5', and port is an integral port number. Other address families are currently not supported. The address format required by a particular socket object is automatically selected based on the address family specified when the socket object was created. This also explains the reason for requiring a single argument: when using AF_UNIX, the second argument makes no sense! Frankly, I'm not sure what do here -- it's more correct to require a single address argument always, but it's more convenient to allow two sometimes. Note that sendto(data, addr) only accepts the tuple form: you cannot write sendto(data, host, port). --Guido van Rossum (home page: http://www.python.org/~guido/)
"GvR" == Guido van Rossum <guido@python.org> writes:
GvR> You probably meant: | sock.connect(addr) | sock.connect(host, port) | sock.connect((host, port)) GvR> since (host, port) is equivalent to (addr). Doh, yes. :) GvR> Fred typically directs latex2html to break all sections GvR> apart. It's in the previous section: 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. GvR> This also explains the reason for requiring a single GvR> argument: when using AF_UNIX, the second argument makes no GvR> sense! GvR> Frankly, I'm not sure what do here -- it's more correct to GvR> require a single address argument always, but it's more GvR> convenient to allow two sometimes. GvR> Note that sendto(data, addr) only accepts the tuple form: you GvR> cannot write sendto(data, host, port). 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. :) -Barry
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/)
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
[Guido]
Someone noticed that socket.connect() and a few related functions (connect_ex() and bind()) take either a single (host, port) tuple or two separate arguments, but that only the tuple is documented.
Similar to append(), I'd like to close this gap, and I've made the necessary changes. This will probably break lots of code.
This will indeed cause great wailing and gnashing of teeth. I've been criticized for using the tuple form in the Sockets HOWTO (in fact I foolishly changed it to demonstrate both forms).
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...
I say give 'em something to whine about. put-sand-in-the-vaseline-ly y'rs - Gordon
Guido van Rossum <guido@python.org> 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>
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...)
Oops. Sigh. While we're pretending that this change goes in, could you point me to those five modules? Also, we need to add test cases to the standard test suite that would have found these! --Guido van Rossum (home page: http://www.python.org/~guido/)
[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>.
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.
No more foolish than passing a point as an (x, y) tuple instead of separate x and y arguments. There are good reasons for passing it as a tuple, such as being able to store and recall it as a single entity.
So offer to back off on this one, in return for making 1/2 yield 0.5 <wink>.
Unfortunately, I think I will have to. And it will have to be documented. The problem is that I can't document it as connect(host, port) -- there are Unix domain sockets that only take a single string argument (a filename). Also, sendto() takes a (host, port) tuple only. It has other arguments so that's the only form. 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. Still torn, --Guido van Rossum (home page: http://www.python.org/~guido/)
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
Fred> If you *must* support the two-arg flavor (which I've never Fred> actually seen outside this discussion), I'd suggest not Fred> documenting it as a backward compatibility, only that it will Fred> disappear in 1.7. Having surprisingly little opportunity to call socket.connect directly in my work (considering the bulk of my programming is for the web), I'll note for the record that the direct calls I've made to socket.connect all have two 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? Skip
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. ;) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives
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>
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/)
participants (8)
-
Barry A. Warsaw -
bwarsaw＠cnri.reston.va.us
-
Fred L. Drake, Jr. -
Fredrik Lundh -
Gordon McMillan -
Guido van Rossum -
Skip Montanaro -
Tim Peters