For example, I have some programs which are HTTP servers that implement WebSockets.  For regular web page requests, it is acceptable if the connection is closed after the page is sent.  But for a WebSocket it isn't: the whole point of that protocol is to allow the server to send unsolicited messages to the browser.  If the connection is closed, it cannot do that.  The documentation currently suggests that the only way to avoid handle() closing the connection is to not return.  That means that the only way to do other things is by using multi-processing or (shiver) multi-threading.

My suggestion is to add a short explanation about how connections can be kept open after handle() returns, so that a single threaded event loop can be used.  Of course the socket must then be manually closed when the program is done with it.

If I understand you correctly, overriding process_request would allow handle() to return without closing the socket.  That does sound better than overriding shutdown_request.

In the current documentation (same link as before, now for version 3.5.1), there is no mention at all about close() or shutdown() of the accepted sockets.  The only information on the subject is that if you want asynchronous handling of data, you must start a new thread or process.  This is not true, and in many cases it is not what I would recommend.  I think event loops are much easier to maintain and debug than multi-process applications, and infinitely easier than multi-threading applications.  I don't mind that other people disagree, and I'm not suggesting that those ways of handling should be removed (multi-process has its place, and I can't convince everyone that multi-threading is evil).  What I'm saying is that the ability to use an event loop to handle asynchronous data with this class deserves to be mentioned as well.

Obviously, it does then need to have the explanation about what to override to make it work.  My suggestion is simply what I ended up with after seeing it fail and reading the code.  If what you describe is the recommended way, please say that instead.  My point is that the scenario should presented as an option, I don't have an opinion on what it should say.