I had a bad time understanding what happens in Mac OS X after a shutdown
call: after calling shutdown(SH_WR) on side A, a corresponding
shutdown(SH_RD) on side B would raise a socket.error: socket is not
connected.
It is quite surprising when you are used to sockets in Linux, which
expect you to shut one end, and then the other one.

It turns out that under Mac OS X, a shutdown call closes the connection
on the other half. And the only mention I could find of this behavior
was here, r68611 :
http://svn.python.org/view/python/trunk/Lib/test/test_socket.py?r1=64125&r2=68611&pathrev=68611

I think that the documentation should specify that (surprising)
behavior: I attached a patch explaining that detail.


Thanks!

Thanks, applied in r82798.

I was scared by the note in the documentation and wondered if the socket Python API was completely incapable of handling half-closed connections cross platform. pitrou helped me on IRC to track the note down to this issue.


IMO the bug report should have been rejected and the documentation patch should be removed. It shouldn't be that surprising that shutting something down that already has been shutdown (by the peer) will fail.

I don't see any indication that a "shutdown call closes the connection on the other half". It makes it half-closed as it should - and if it did anything else (which the note indicates) then it would be a big violation of BSD TCP API.

Ok, it might be slightly surprising that the next shutdown on the other end fails, but that is fully covered by "Note Some behavior may be platform dependent, since calls are made to the operating system socket APIs." It is not specific to Python in any way, AFAICT.

If anything it could just say something like "Note that shutdown of a socket that already has been shut down by the peer is platform dependent and might fail."

> I was scared by the note in the documentation and wondered if the
> socket Python API was completely incapable of handling half-closed
> connections cross platform.
[...]
> It makes it half-closed as it should

Indeed. Calling shutdown(SHUT_WR) doesn't close the other end (which doesn't make much sense), it just sends a FIN (or RST depending on the context). It's the other end which decides to return ENOTCONN upon shutdown(SHUT_RD) on OS X, which is questionable (not sure it's against the BSD socket API, since shutdown(SHUT_RD) doesn't have any counterpart in the TCP layer).

I also find this note confusing and scary for no good reason, and since I don't think we should document every OS idiosyncrasies, it would probably be better to revert it.

I'll leave this open for a couple days to see if anyone objects, otherwise I'll revert it.

> It's the other end which decides to return ENOTCONN upon shutdown(SHUT_RD) on OS X, which is questionable
> (not sure it's against the BSD socket API, since shutdown(SHUT_RD) doesn't have any counterpart in the TCP layer).

Exactly. The same code raises a socket.error in one platform (mac os) and not on another (linux). Why not document this questionable behavior?

I'm sorry, I realize that my original patch was imprecise. I'm not an expert here, and I simply read http://svn.python.org/view/python/trunk/Lib/test/test_socket.py?r1=64125&r2=68611&pathrev=68611 . Ok, fine -- it doesn't close the other end per se, but shutdown(SH_RD) after a FIN on MacOS raises a socket.error . This is questionable, unexpected, and should be documented.


If possible, I'd like to push for a rewording instead of a revert.

> This is questionable, unexpected, and should be documented.

There's already this note at the top of the socket module documentation:
"""
Note

Some behavior may be platform dependent, since calls are made to the
operating system socket APIs.
"""

There are other such subtleties with the socket API, e.g. SO_REUSEADDR
which doesn't have the same semantics on Windows. As I said earlier, I
don't think we should document every platform quirks: it will make
users worry for no reason, and as time passes, there's a chance that
the documentation doesn't match the actual behavior.
For example, this specific behavior might very well be a bug, and it's
not our responsibility to document this.

New changeset 9be82f458b79 by Charles-François Natali in branch 'default':
Issue #6774: Back out c8b77efe8b56, which only brings confusion.
http://hg.python.org/cpython/rev/9be82f458b79

I've reverted the commit.