cat /dev/brain

requests-toolbelt 0.4.0 released

It is my distinct pleasure to announce the 0.4.0 release of the requests toolbelt. This version comes almost a year after the release of 0.3.1.

A lot of work was put into the toolbelt in those 10 months though. We reorganized the documentation to make it easier to find the information you need. We also added a lot (10 in total) of new features and fixed a couple of bugs.

New Transport Adapters

The toolbelt now ships with five transport adapters that Cory and I realized an increasing number of people needed. Previously, we only had the SourceAddressAdapter and the SSLAdapter, but it became apparent that we needed to provide more.

A growing number of users were demonstrating a need to

  • specify the fingerprint of a certificate to verify against (FingerprintAdapter)
  • set a specific socket options for each connection made from a session (SocketOptionsAdapter)
  • configure TCP Keep-Alive for each connection made by a session (TCPKeepAliveAdapter)


In 0.3.0 we added GuessAuth which was contributed by Markus Unterwaditzer, but it was clear we needed to add a few more ways of handling authentication. requests (the project) received a number of requests for an authentication handler that used Digest Authentication to authenticate to a proxy (HTTPProxyDigestAuth). If you've used requests frequently, you've probably also realized that you can only set up authentication in a very naive way on a session, but sessions do not need to only ever speak to a single server (or host). So we created a mechanism that will pick the right authentication for the right host (based on how you define the mapping).

Saving the Contents of Responses

I noticed that a number of people were downloading files and ignoring data that is returned by most servers about the name of the file. For this reason, I introduced a new module containing download utilities. The only function it contains thus far will allow you a lot of flexibility in streaming a response to a file (or file-like object). If you do not provide a filename or a file-like object, it will instead attempt to discern the filename from the Content-Disposition header and save the contents to a file with the same name.


We also noticed that a number of people are using requests in threaded situations. Without specific tests that ensure thread-safety, Cory and I have begun to doubt exactly how threadsafe a Session object really is.

To provide an alternative way to use threading with requests, I've implemented a naive session thread pool. The API is still a bit rough, but the implementation is extremely fast. If you run the example in the repository you'll notice that there's a noticeable delay in its completion. If you comment out these lines, however, you'll notice that it returns immediately.

Better APIs for this functionality are still being discussed, so please feel free to experiment with it and propose better APIs.

Miscellaneous Utilities

Finally, requests has decided to deprecate a number of functions that currently live in requests.utils when we release version 3.0.0. Since many people rely on those functions, we've moved them to the toolbelt where they can continue to be maintained, updated, and improved.


We hope everyone who pip install requests_toolbelt will enjoy these new features and appreciate the bug fixes we've made over the last year.

If you find bugs, please report them on our issue tracker. Or, if you'd like to contribute, check out our new Contributor Code of Conduct and send a pull request.