Session Objects¶

The Session object allows you to persist certain parameters acrossrequests. It also persists cookies across all requests made from theSession instance, and will useurllib3’sconnection pooling. So ifyou’re making several requests to the same host, the underlying TCPconnection will be reused, which can result in a significant performanceincrease (seeHTTP persistent connection).

A Session object has all the methods of the main Requests API.

Let’s persist some cookies across requests:

s=requests.Session()s.get('https://httpbin.org/cookies/set/sessioncookie/123456789')r=s.get('https://httpbin.org/cookies')print(r.text)# '{"cookies": {"sessioncookie": "123456789"}}'

Sessions can also be used to provide default data to the request methods. Thisis done by providing data to the properties on a Session object:

s=requests.Session()s.auth=('user','pass')s.headers.update({'x-test':'true'})# both 'x-test' and 'x-test2' are sents.get('https://httpbin.org/headers',headers={'x-test2':'true'})

Any dictionaries that you pass to a request method will be merged with thesession-level values that are set. The method-level parameters override sessionparameters.

Note, however, that method-level parameters willnot be persisted acrossrequests, even if using a session. This example will only send the cookieswith the first request, but not the second:

s=requests.Session()r=s.get('https://httpbin.org/cookies',cookies={'from-my':'browser'})print(r.text)# '{"cookies": {"from-my": "browser"}}'r=s.get('https://httpbin.org/cookies')print(r.text)# '{"cookies": {}}'

If you want to manually add cookies to your session, use theCookie utility functions to manipulateSession.cookies.

Sessions can also be used as context managers:

withrequests.Session()ass:s.get('https://httpbin.org/cookies/set/sessioncookie/123456789')

This will make sure the session is closed as soon as thewith block isexited, even if unhandled exceptions occurred.

All values that are contained within a session are directly available to you.See theSession API Docs to learn more.

Request and Response Objects¶

Whenever a call is made torequests.get() and friends, you are doing twomajor things. First, you are constructing aRequest object which will besent off to a server to request or query some resource. Second, aResponseobject is generated once Requests gets a response back from the server.TheResponse object contains all of the information returned by the server andalso contains theRequest object you created originally. Here is a simplerequest to get some very important information from Wikipedia’s servers:

>>>r=requests.get('https://en.wikipedia.org/wiki/Monty_Python')

If we want to access the headers the server sent back to us, we do this:

>>>r.headers{'content-length': '56170', 'x-content-type-options': 'nosniff', 'x-cache':'HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet', 'content-encoding':'gzip', 'age': '3080', 'content-language': 'en', 'vary': 'Accept-Encoding,Cookie','server': 'Apache', 'last-modified': 'Wed, 13 Jun 2012 01:33:50 GMT','connection': 'close', 'cache-control': 'private, s-maxage=0, max-age=0,must-revalidate', 'date': 'Thu, 14 Jun 2012 12:59:39 GMT', 'content-type':'text/html; charset=UTF-8', 'x-cache-lookup': 'HIT from cp1006.eqiad.wmnet:3128,MISS from cp1010.eqiad.wmnet:80'}

However, if we want to get the headers we sent the server, we simply access therequest, and then the request’s headers:

>>>r.request.headers{'Accept-Encoding': 'identity, deflate, compress, gzip','Accept': '*/*', 'User-Agent': 'python-requests/1.2.0'}

Prepared Requests¶

Whenever you receive aResponse objectfrom an API call or a Session call, therequest attribute is actually thePreparedRequest that was used. In some cases you may wish to do some extrawork to the body or headers (or anything else really) before sending arequest. The simple recipe for this is the following:

fromrequestsimportRequest,Sessions=Session()req=Request('POST',url,data=data,headers=headers)prepped=req.prepare()# do something with prepped.bodyprepped.body='No, I want exactly this as the body.'# do something with prepped.headersdelprepped.headers['Content-Type']resp=s.send(prepped,stream=stream,verify=verify,proxies=proxies,cert=cert,timeout=timeout)print(resp.status_code)

Since you are not doing anything special with theRequest object, youprepare it immediately and modify thePreparedRequest object. You thensend that with the other parameters you would have sent torequests.* orSession.*.

However, the above code will lose some of the advantages of having a RequestsSession object. In particular,Session-level state such as cookies willnot get applied to your request. To get aPreparedRequest with that stateapplied, replace the call toRequest.prepare() with a call toSession.prepare_request(), like this:

fromrequestsimportRequest,Sessions=Session()req=Request('GET',url,data=data,headers=headers)prepped=s.prepare_request(req)# do something with prepped.bodyprepped.body='Seriously, send exactly these bytes.'# do something with prepped.headersprepped.headers['Keep-Dead']='parrot'resp=s.send(prepped,stream=stream,verify=verify,proxies=proxies,cert=cert,timeout=timeout)print(resp.status_code)

When you are using the prepared request flow, keep in mind that it does not take into account the environment.This can cause problems if you are using environment variables to change the behaviour of requests.For example: Self-signed SSL certificates specified inREQUESTS_CA_BUNDLE will not be taken into account.As a result anSSL:CERTIFICATE_VERIFY_FAILED is thrown.You can get around this behaviour by explicitly merging the environment settings into your session:

fromrequestsimportRequest,Sessions=Session()req=Request('GET',url)prepped=s.prepare_request(req)# Merge environment settings into sessionsettings=s.merge_environment_settings(prepped.url,{},None,None,None)resp=s.send(prepped,**settings)print(resp.status_code)

SSL Cert Verification¶

Requests verifies SSL certificates for HTTPS requests, just like a web browser.By default, SSL verification is enabled, and Requests will throw a SSLError ifit’s unable to verify the certificate:

>>>requests.get('https://requestb.in')requests.exceptions.SSLError: hostname 'requestb.in' doesn't match either of '*.herokuapp.com', 'herokuapp.com'

I don’t have SSL setup on this domain, so it throws an exception. Excellent. GitHub does though:

>>>requests.get('https://github.com')<Response [200]>

You can passverify the path to a CA_BUNDLE file or directory with certificates of trusted CAs:

>>>requests.get('https://github.com',verify='/path/to/certfile')

or persistent:

s=requests.Session()s.verify='/path/to/certfile'

This list of trusted CAs can also be specified through theREQUESTS_CA_BUNDLE environment variable.IfREQUESTS_CA_BUNDLE is not set,CURL_CA_BUNDLE will be used as fallback.

Requests can also ignore verifying the SSL certificate if you setverify to False:

>>>requests.get('https://kennethreitz.org',verify=False)<Response [200]>

Note that whenverify is set toFalse, requests will accept any TLScertificate presented by the server, and will ignore hostname mismatchesand/or expired certificates, which will make your application vulnerable toman-in-the-middle (MitM) attacks. Setting verify toFalse may be usefulduring local development or testing.

By default,verify is set to True. Optionverify only applies to host certs.

Client Side Certificates¶

You can also specify a local cert to use as client side certificate, as a singlefile (containing the private key and the certificate) or as a tuple of bothfiles’ paths:

>>>requests.get('https://kennethreitz.org',cert=('/path/client.cert','/path/client.key'))<Response [200]>

or persistent:

s=requests.Session()s.cert='/path/client.cert'

If you specify a wrong path or an invalid cert, you’ll get a SSLError:

>>>requests.get('https://kennethreitz.org',cert='/wrong_path/client.pem')SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib

CA Certificates¶

Requests uses certificates from the packagecertifi. This allows for usersto update their trusted certificates without changing the version of Requests.

Before version 2.16, Requests bundled a set of root CAs that it trusted,sourced from theMozilla trust store. The certificates were only updatedonce for each Requests version. Whencertifi was not installed, this led toextremely out-of-date certificate bundles when using significantly olderversions of Requests.

For the sake of security we recommend upgrading certifi frequently!

Body Content Workflow¶

By default, when you make a request, the body of the response is downloadedimmediately. You can override this behaviour and defer downloading the responsebody until you access theResponse.contentattribute with thestream parameter:

tarball_url='https://github.com/psf/requests/tarball/main'r=requests.get(tarball_url,stream=True)

At this point only the response headers have been downloaded and the connectionremains open, hence allowing us to make content retrieval conditional:

ifint(r.headers['content-length'])<TOO_LONG:content=r.content...

You can further control the workflow by use of theResponse.iter_content()andResponse.iter_lines() methods.Alternatively, you can read the undecoded body from the underlyingurllib3urllib3.HTTPResponse atResponse.raw.

If you setstream toTrue when making a request, Requests cannotrelease the connection back to the pool unless you consume all the data or callResponse.close. This can lead toinefficiency with connections. If you find yourself partially reading requestbodies (or not reading them at all) while usingstream=True, you shouldmake the request within awith statement to ensure it’s always closed:

withrequests.get('https://httpbin.org/get',stream=True)asr:# Do things with the response here.

Keep-Alive¶

Excellent news — thanks to urllib3, keep-alive is 100% automatic within a session!Any requests that you make within a session will automatically reuse the appropriateconnection!

Note that connections are only released back to the pool for reuse once all bodydata has been read; be sure to either setstream toFalse or read thecontent property of theResponse object.

Streaming Uploads¶

Requests supports streaming uploads, which allow you to send large streams orfiles without reading them into memory. To stream and upload, simply provide afile-like object for your body:

withopen('massive-body','rb')asf:requests.post('http://some.url/streamed',data=f)

Chunk-Encoded Requests¶

Requests also supports Chunked transfer encoding for outgoing and incoming requests.To send a chunk-encoded request, simply provide a generator (or any iterator withouta length) for your body:

defgen():yield'hi'yield'there'requests.post('http://some.url/chunked',data=gen())

For chunked encoded responses, it’s best to iterate over the data usingResponse.iter_content(). Inan ideal situation you’ll have setstream=True on the request, in whichcase you can iterate chunk-by-chunk by callingiter_content with achunk_sizeparameter ofNone. If you want to set a maximum size of the chunk,you can set achunk_size parameter to any integer.

POST Multiple Multipart-Encoded Files¶

You can send multiple files in one request. For example, suppose you want toupload image files to an HTML form with a multiple file field ‘images’:

<inputtype="file"name="images"multiple="true"required="true"/>

To do that, just set files to a list of tuples of(form_field_name,file_info):

>>>url='https://httpbin.org/post'>>>multiple_files=[...('images',('foo.png',open('foo.png','rb'),'image/png')),...('images',('bar.png',open('bar.png','rb'),'image/png'))]>>>r=requests.post(url,files=multiple_files)>>>r.text{  ...  'files': {'images': 'data:image/png;base64,iVBORw ....'}  'Content-Type': 'multipart/form-data; boundary=3131623adb2043caaeb5538cc7aa0b3a',  ...}

Event Hooks¶

Requests has a hook system that you can use to manipulate portions ofthe request process, or signal event handling.

Available hooks:

response:

The response generated from a Request.

You can assign a hook function on a per-request basis by passing a{hook_name:callback_function} dictionary to thehooks requestparameter:

hooks={'response':print_url}

Thatcallback_function will receive a chunk of data as its firstargument.

defprint_url(r,*args,**kwargs):print(r.url)

Your callback function must handle its own exceptions. Any unhandled exception won’t be passed silently and thus should be handled by the code calling Requests.

If the callback function returns a value, it is assumed that it is toreplace the data that was passed in. If the function doesn’t returnanything, nothing else is affected.

defrecord_hook(r,*args,**kwargs):r.hook_called=Truereturnr

Let’s print some request method arguments at runtime:

>>>requests.get('https://httpbin.org/',hooks={'response':print_url})https://httpbin.org/<Response [200]>

You can add multiple hooks to a single request. Let’s call two hooks at once:

>>>r=requests.get('https://httpbin.org/',hooks={'response':[print_url,record_hook]})>>>r.hook_calledTrue

You can also add hooks to aSession instance. Any hooks you add will thenbe called on every request made to the session. For example:

>>>s=requests.Session()>>>s.hooks['response'].append(print_url)>>>s.get('https://httpbin.org/') https://httpbin.org/ <Response [200]>

ASession can have multiple hooks, which will be called in the orderthey are added.

Custom Authentication¶

Requests allows you to specify your own authentication mechanism.

Any callable which is passed as theauth argument to a request method willhave the opportunity to modify the request before it is dispatched.

Authentication implementations are subclasses ofAuthBase,and are easy to define. Requests provides two common authentication schemeimplementations inrequests.auth:HTTPBasicAuth andHTTPDigestAuth.

Let’s pretend that we have a web service that will only respond if theX-Pizza header is set to a password value. Unlikely, but just go with it.

fromrequests.authimportAuthBaseclassPizzaAuth(AuthBase):"""Attaches HTTP Pizza Authentication to the given Request object."""def__init__(self,username):# setup any auth-related data hereself.username=usernamedef__call__(self,r):# modify and return the requestr.headers['X-Pizza']=self.usernamereturnr

Then, we can make a request using our Pizza Auth:

>>>requests.get('http://pizzabin.org/admin',auth=PizzaAuth('kenneth'))<Response [200]>

Streaming Requests¶

WithResponse.iter_lines() you can easilyiterate over streaming APIs such as theTwitter StreamingAPI. Simplysetstream toTrue and iterate over the response withiter_lines:

importjsonimportrequestsr=requests.get('https://httpbin.org/stream/20',stream=True)forlineinr.iter_lines():# filter out keep-alive new linesifline:decoded_line=line.decode('utf-8')print(json.loads(decoded_line))

When usingdecode_unicode=True withResponse.iter_lines() orResponse.iter_content(), you’ll wantto provide a fallback encoding in the event the server doesn’t provide one:

r=requests.get('https://httpbin.org/stream/20',stream=True)ifr.encodingisNone:r.encoding='utf-8'forlineinr.iter_lines(decode_unicode=True):ifline:print(json.loads(line))

lines=r.iter_lines()# Save the first line for later or just skip itfirst_line=next(lines)forlineinlines:print(line)

Proxies¶

If you need to use a proxy, you can configure individual requests with theproxies argument to any request method:

importrequestsproxies={'http':'http://10.10.1.10:3128','https':'http://10.10.1.10:1080',}requests.get('http://example.org',proxies=proxies)

Alternatively you can configure it once for an entireSession:

importrequestsproxies={'http':'http://10.10.1.10:3128','https':'http://10.10.1.10:1080',}session=requests.Session()session.proxies.update(proxies)session.get('http://example.org')

When the proxies configuration is not overridden per request as shown above,Requests relies on the proxy configuration defined by standardenvironment variableshttp_proxy,https_proxy,no_proxy,andall_proxy. Uppercase variants of these variables are also supported.You can therefore set them to configure Requests (only set the ones relevantto your needs):

$ export HTTP_PROXY="http://10.10.1.10:3128"$ export HTTPS_PROXY="http://10.10.1.10:1080"$ export ALL_PROXY="socks5://10.10.1.10:3434"$ python>>> import requests>>> requests.get('http://example.org')

To use HTTP Basic Auth with your proxy, use thehttp://user:password@host/syntax in any of the above configuration entries:

$ export HTTPS_PROXY="http://user:pass@10.10.1.10:1080"$ python>>> proxies = {'http': 'http://user:pass@10.10.1.10:3128/'}

To give a proxy for a specific scheme and host, use thescheme://hostname form for the key. This will match forany request to the given scheme and exact hostname.

proxies={'http://10.20.1.128':'http://10.10.1.10:5323'}

Note that proxy URLs must include the scheme.

Finally, note that using a proxy for https connections typically requires yourlocal machine to trust the proxy’s root certificate. By default the list ofcertificates trusted by Requests can be found with:

fromrequests.utilsimportDEFAULT_CA_BUNDLE_PATHprint(DEFAULT_CA_BUNDLE_PATH)

You override this default certificate bundle by setting theREQUESTS_CA_BUNDLE(orCURL_CA_BUNDLE) environment variable to another file path:

$ export REQUESTS_CA_BUNDLE="/usr/local/myproxy_info/cacert.pem"$ export https_proxy="http://10.10.1.10:1080"$ python>>> import requests>>> requests.get('https://example.org')

$python-mpipinstall'requests[socks]'

proxies={'http':'socks5://user:pass@host:port','https':'socks5://user:pass@host:port'}

Compliance¶

Requests is intended to be compliant with all relevant specifications andRFCs where that compliance will not cause difficulties for users. Thisattention to the specification can lead to some behaviour that may seemunusual to those not familiar with the relevant specification.

HTTP Verbs¶

Requests provides access to almost the full range of HTTP verbs: GET, OPTIONS,HEAD, POST, PUT, PATCH and DELETE. The following provides detailed examples ofusing these various verbs in Requests, using the GitHub API.

We will begin with the verb most commonly used: GET. HTTP GET is an idempotentmethod that returns a resource from a given URL. As a result, it is the verbyou ought to use when attempting to retrieve data from a web location. Anexample usage would be attempting to get information about a specific commitfrom GitHub. Suppose we wanted commita050faf on Requests. We would get itlike so:

>>>importrequests>>>r=requests.get('https://api.github.com/repos/psf/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad')

We should confirm that GitHub responded correctly. If it has, we want to workout what type of content it is. Do this like so:

>>>ifr.status_code==requests.codes.ok:...print(r.headers['content-type'])...application/json; charset=utf-8

So, GitHub returns JSON. That’s great, we can use ther.json method to parse it into Python objects.

>>>commit_data=r.json()>>>print(commit_data.keys())['committer', 'author', 'url', 'tree', 'sha', 'parents', 'message']>>>print(commit_data['committer']){'date': '2012-05-10T11:10:50-07:00', 'email': 'me@kennethreitz.com', 'name': 'Kenneth Reitz'}>>>print(commit_data['message'])makin' history

So far, so simple. Well, let’s investigate the GitHub API a little bit. Now,we could look at the documentation, but we might have a little more fun if weuse Requests instead. We can take advantage of the Requests OPTIONS verb tosee what kinds of HTTP methods are supported on the url we just used.

>>>verbs=requests.options(r.url)>>>verbs.status_code500

Uh, what? That’s unhelpful! Turns out GitHub, like many API providers, don’tactually implement the OPTIONS method. This is an annoying oversight, but it’sOK, we can just use the boring documentation. If GitHub had correctlyimplemented OPTIONS, however, they should return the allowed methods in theheaders, e.g.

>>>verbs=requests.options('http://a-good-website.com/api/cats')>>>print(verbs.headers['allow'])GET,HEAD,POST,OPTIONS

Turning to the documentation, we see that the only other method allowed forcommits is POST, which creates a new commit. As we’re using the Requests repo,we should probably avoid making ham-handed POSTS to it. Instead, let’s playwith the Issues feature of GitHub.

This documentation was added in response toIssue #482. Given thatthis issue already exists, we will use it as an example. Let’s start by getting it.

>>>r=requests.get('https://api.github.com/repos/psf/requests/issues/482')>>>r.status_code200>>>issue=json.loads(r.text)>>>print(issue['title'])Feature any http verb in docs>>>print(issue['comments'])3

Cool, we have three comments. Let’s take a look at the last of them.

>>>r=requests.get(r.url+'/comments')>>>r.status_code200>>>comments=r.json()>>>print(comments[0].keys())['body', 'url', 'created_at', 'updated_at', 'user', 'id']>>>print(comments[2]['body'])Probably in the "advanced" section

Well, that seems like a silly place. Let’s post a comment telling the posterthat he’s silly. Who is the poster, anyway?

>>>print(comments[2]['user']['login'])kennethreitz

OK, so let’s tell this Kenneth guy that we think this example should go in thequickstart guide instead. According to the GitHub API doc, the way to do thisis to POST to the thread. Let’s do it.

>>>body=json.dumps({u"body":u"Sounds great! I'll get right on it!"})>>>url=u"https://api.github.com/repos/psf/requests/issues/482/comments">>>r=requests.post(url=url,data=body)>>>r.status_code404

Huh, that’s weird. We probably need to authenticate. That’ll be a pain, right?Wrong. Requests makes it easy to use many forms of authentication, includingthe very common Basic Auth.

>>>fromrequests.authimportHTTPBasicAuth>>>auth=HTTPBasicAuth('fake@example.com','not_a_real_password')>>>r=requests.post(url=url,data=body,auth=auth)>>>r.status_code201>>>content=r.json()>>>print(content['body'])Sounds great! I'll get right on it.

Brilliant. Oh, wait, no! I meant to add that it would take me a while, becauseI had to go feed my cat. If only I could edit this comment! Happily, GitHuballows us to use another HTTP verb, PATCH, to edit this comment. Let’s dothat.

>>>print(content[u"id"])5804413>>>body=json.dumps({u"body":u"Sounds great! I'll get right on it once I feed my cat."})>>>url=u"https://api.github.com/repos/psf/requests/issues/comments/5804413">>>r=requests.patch(url=url,data=body,auth=auth)>>>r.status_code200

Excellent. Now, just to torture this Kenneth guy, I’ve decided to let himsweat and not tell him that I’m working on this. That means I want to deletethis comment. GitHub lets us delete comments using the incredibly aptly namedDELETE method. Let’s get rid of it.

>>>r=requests.delete(url=url,auth=auth)>>>r.status_code204>>>r.headers['status']'204 No Content'

Excellent. All gone. The last thing I want to know is how much of my ratelimitI’ve used. Let’s find out. GitHub sends that information in the headers, sorather than download the whole page I’ll send a HEAD request to get theheaders.

>>>r=requests.head(url=url,auth=auth)>>>print(r.headers)...'x-ratelimit-remaining': '4995''x-ratelimit-limit': '5000'...

Excellent. Time to write a Python program that abuses the GitHub API in allkinds of exciting ways, 4995 more times.

Custom Verbs¶

From time to time you may be working with a server that, for whatever reason,allows use or even requires use of HTTP verbs not covered above. One example ofthis would be the MKCOL method some WEBDAV servers use. Do not fret, these canstill be used with Requests. These make use of the built-in.requestmethod. For example:

>>>r=requests.request('MKCOL',url,data=data)>>>r.status_code200 # Assuming your call was correct

Utilising this, you can make use of any method verb that your server allows.

Link Headers¶

Many HTTP APIs feature Link headers. They make APIs more self describing anddiscoverable.

GitHub uses these forpaginationin their API, for example:

>>>url='https://api.github.com/users/kennethreitz/repos?page=1&per_page=10'>>>r=requests.head(url=url)>>>r.headers['link']'<https://api.github.com/users/kennethreitz/repos?page=2&per_page=10>; rel="next", <https://api.github.com/users/kennethreitz/repos?page=6&per_page=10>; rel="last"'

Requests will automatically parse these link headers and make them easily consumable:

>>>r.links["next"]{'url': 'https://api.github.com/users/kennethreitz/repos?page=2&per_page=10', 'rel': 'next'}>>>r.links["last"]{'url': 'https://api.github.com/users/kennethreitz/repos?page=7&per_page=10', 'rel': 'last'}

Transport Adapters¶

As of v1.0.0, Requests has moved to a modular internal design using TransportAdapters. These objects provide a mechanism to define interaction methods for anHTTP service. In particular, they allow you to apply per-service configuration.

Requests ships with a single Transport Adapter, theHTTPAdapter. This adapter provides the default Requestsinteraction with HTTP and HTTPS using the powerfulurllib3 library. Whenevera RequestsSession is initialized, one of these isattached to theSession object for HTTP, and onefor HTTPS.

Requests enables users to create and use their own Transport Adapters thatprovide specific functionality. Once created, a Transport Adapter can bemounted to a Session object, along with an indication of which web servicesit should apply to.

>>>s=requests.Session()>>>s.mount('https://github.com/',MyAdapter())

The mount call registers a specific instance of a Transport Adapter to aprefix. Once mounted, any HTTP request made using that session whose URL startswith the given prefix will use the given Transport Adapter.

Many of the details of implementing a Transport Adapter are beyond the scope ofthis documentation, but take a look at the next example for a simple SSL use-case. For more than that, you might look at subclassing theBaseAdapter.

importsslfromurllib3.poolmanagerimportPoolManagerfromrequests.adaptersimportHTTPAdapterclassSsl3HttpAdapter(HTTPAdapter):""""Transport adapter" that allows us to use SSLv3."""definit_poolmanager(self,connections,maxsize,block=False):self.poolmanager=PoolManager(num_pools=connections,maxsize=maxsize,block=block,ssl_version=ssl.PROTOCOL_SSLv3)

fromurllib3.utilimportRetryfromrequestsimportSessionfromrequests.adaptersimportHTTPAdapters=Session()retries=Retry(total=3,backoff_factor=0.1,status_forcelist=[502,503,504],allowed_methods={'POST'},)s.mount('https://',HTTPAdapter(max_retries=retries))

Blocking Or Non-Blocking?¶

With the default Transport Adapter in place, Requests does not provide any kindof non-blocking IO. TheResponse.contentproperty will block until the entire response has been downloaded. Ifyou require more granularity, the streaming features of the library (seeStreaming Requests) allow you to retrieve smaller quantities of theresponse at a time. However, these calls will still block.

If you are concerned about the use of blocking IO, there are lots of projectsout there that combine Requests with one of Python’s asynchronicity frameworks.Some excellent examples arerequests-threads,grequests,requests-futures, andhttpx.

Header Ordering¶

In unusual circumstances you may want to provide headers in an ordered manner. If you pass anOrderedDict to theheaders keyword argument, that will provide the headers with an ordering.However, the ordering of the default headers used by Requests will be preferred, which means that if you override default headers in theheaders keyword argument, they may appear out of order compared to other headers in that keyword argument.

If this is problematic, users should consider setting the default headers on aSession object, by settingSession.headers to a customOrderedDict. That ordering will always be preferred.

Timeouts¶

Most requests to external servers should have a timeout attached, in case theserver is not responding in a timely manner. By default, requests do not timeout unless a timeout value is set explicitly. Without a timeout, your code mayhang for minutes or more.

Theconnect timeout is the number of seconds Requests will wait for yourclient to establish a connection to a remote machine (corresponding to theconnect()) call on the socket. It’s a good practice to set connect timeoutsto slightly larger than a multiple of 3, which is the defaultTCP packetretransmission window.

Once your client has connected to the server and sent the HTTP request, theread timeout is the number of seconds the client will wait for the serverto send a response. (Specifically, it’s the number of seconds that the clientwill waitbetween bytes sent from the server. In 99.9% of cases, this is thetime before the server sends the first byte).

If you specify a single value for the timeout, like this:

r=requests.get('https://github.com',timeout=5)

The timeout value will be applied to both theconnect and thereadtimeouts. Specify a tuple if you would like to set the values separately:

r=requests.get('https://github.com',timeout=(3.05,27))

If the remote server is very slow, you can tell Requests to wait forever fora response, by passing None as a timeout value and then retrieving a cup ofcoffee.

r=requests.get('https://github.com',timeout=None)