"This reflects the last call to :meth:setblocking or :meth:settimeout."

What abou the following case?

>>> import socket; socket.socket(type=socket.SOCK_STREAM | socket.SOCK_NONBLOCK).getblocking()
False

I suggest to remove the second sentence.

Sure

Very minor thing: moving if it to next line increases docstrict readability imho.

Hum, wait, what is this change? Timeouts > 0 now set the socket is blocking mode?

Would you mind to document this subtle behaviour change in settimeout() documentation?

Yes. I'm still working on it. Turns out sendfile currently tests test sendfile on non-blocking sockets, but at the same time the documentation says that it's not supported for non-blocking sockets at all. It's a mess.

I don't think there's any point in explaining this inside test_socket.

In this test it makes sense, because I use fcntl to check the blocking mode of the underlying FD. Usually comments don't hurt in tests.

Hmm, I'm sure that comment can be made much shorter :-)

Can you write your version?

Sure:

/* When a socket socket has a non-infinite timeout,
 * its underlying fd is internally set to non-blocking.
 * This table summarizes [etc.]
 */

Hm, that's too short :) But I'll trim down my version.

Pushed an update.

I'm wary of documenting internals here. It could be quite confusing to the reader, and doesn't seem to provide any useful information.

Yeah, but my confusion with this thing came from me trying to check if the FD is blocking/nonblocking with fcntl.fcntl(sock, fcntl.F_GETFL, os.O_NONBLOCK) & os.O_NONBLOCK, and from there it's was quite a painful experience to discover how socket objects really work in Python (probably because I was debugging a failing sendfile test after some changes, but whatever).

I agree that all this information might overwhelm an average Python user who just wants to read the documentation. On the other hand, socket module is usually used by more or less advanced Python users.

That said, I'd be OK to keep this detailed documentation piece in socketmodule.c if everyone thinks it's too much to have it here.

I think it would be best located in socketmodule.c indeed. Not sure where.

Let's keep it in sock_settimeout(), as it's the central place that triggers blocking/non-blocking modes.

It seems like you modified settimeout() behaviour. It must be documented here and in settimeout() doc.

I'm wrong, settimeout() is (no longer) modified by this PR.

My comment was for a previous version of the PR. The PR evolved too quickly, I was lost, sorry.

I'm wrong, settimeout() is (no longer) modified by this PR.

My comment was for a previous version of the PR. The PR evolved too quickly, I was lost, sorry.

Victor: "getblocking() should be a simple as: return True if the timeout is equal to zero, False otherwise."

Yury: "That's exactly what is in the PR."

Hum, this doc doesn't mention the timeout but refers to a "blocking mode" which is not well defined for timeout > 0.

The socket module mentions 3 modes: blocking, non-blocking and "timeout mode":
https://docs.python.org/dev/library/socket.html#notes-on-socket-timeouts

Replace "if socket is in blocking mode" with "if the timeout is equal to zero", or replace "is in blocking mode" with "is in blocking or timeout mode"?

By the way, there is already a note: "At the operating system level, sockets in timeout mode are internally set in non-blocking mode."

I think the docstring here should say "This is equivalent to gettimeout() == 0", just like the docstring for setblocking explains that it's equivalent to a certain settimeout call.

You may write an helper function which makes sure that timeout, blocking and SOCK_NONBLOCK flag are consistent.

Something like:

def check_timeout(sock, timeout):
  assert sock.gettimeout() == timeout
  assert sock.getblocking() == (timeout == 0.0)
  assert _is_fd_in_blocking_mode(sock) == (timeout != 0.0)

(I'm not sure of these assertions :-))

Since this is internal C docs, it might be helpful to add a column to the table for s->sock_timeout values – IIUC the rows would be < 0, 0.0, and > 0 respectively, but it took some grovelling through the source to figure that out.

You may add "This is equivalent to checking socket.gettimeout() == 0." here as well.