Document threading contract for Session class

Right now, it’s quite difficult to figure out if the Session class is threadsafe or not. The docs don’t say, apart from a “thread-safe” bullet on the home page. Google led me to http://stackoverflow.com/questions/18188044/is-the-session-object-from-pythons-requests-library-thread-safe, whose first answer boils down to “be very careful”.

Inspired by that SO author, I’ve been auditing the code myself, and have come to the conclusion that Session is probably not threadsafe. (The use of self.redirect_cache set off red flags for me.) Reading through other requests bug reports, I see maintainers recommending one Session per thread, which implies that it’s not threadsafe.

The documentation should clarify this and recommend how to use Session in multithreaded programs. Possible text:

Session is not threadsafe. If you are using requests with an explicit Session
object in a multithreaded program, you should create one Session per thread.

If that’s accurate, let me know and I’ll submit a PR.

Also, I think the “thread-safe” bullet should be removed from the home page, or maybe replaced by “thread-safe in certain circumstances”.

[mmerickel]

What is the motivation for the “thread-safety” bullet point on the main page? I can’t find the word “thread” almost anywhere in the documentation and definitely nothing about thread safety. This issue alongside several others indicate that the session is not actually thread-safe. The bullet point really should be removed as it seems unfounded right now.

[Lukasa]

I’d go further: I think the redirect cache is a bad idea. I still think that.

I think re-adding thread-safety would be a good idea. We can get away with it, I think, by locking around the CookieJar (which should be the only other thing that is a risk here). That’s a cheap-and-easy way to get something approximating thread safety, even if it doesn’t necessarily get great performance.