GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing requests.readthedocs.io — Quickstart — Requests 2.34.2 documentation Quickstart¶Eager to get started? This page gives a good introduction in how to get started with Requests. First, make sure that:
Let’s get started with some simple examples. Make a Request¶Making a request with Requests is very simple. Begin by importing the Requests module: >>> import requests Now, let’s try to get a webpage. For this example, let’s get GitHub’s public timeline: >>> r = requests.get('https://api.github.com/events') Now, we have a Requests’ simple API means that all forms of HTTP request are as obvious. For example, this is how you make an HTTP POST request: >>> r = requests.post('https://httpbin.org/post', data={'key': 'value'}) Nice, right? What about the other HTTP request types: PUT, DELETE, HEAD and OPTIONS? These are all just as simple: >>> r = requests.put('https://httpbin.org/put', data={'key': 'value'}) >>> r = requests.delete('https://httpbin.org/delete') >>> r = requests.head('https://httpbin.org/get') >>> r = requests.options('https://httpbin.org/get') That’s all well and good, but it’s also only the start of what Requests can do. Passing Parameters In URLs¶You often want to send some sort of data in the URL’s query string. If
you were constructing the URL by hand, this data would be given as key/value
pairs in the URL after a question mark, e.g. >>> payload = {'key1': 'value1', 'key2': 'value2'} >>> r = requests.get('https://httpbin.org/get', params=payload) You can see that the URL has been correctly encoded by printing the URL: >>> print(r.url) https://httpbin.org/get?key2=value2&key1=value1 Note that any dictionary key whose value is You can also pass a list of items as a value: >>> payload = {'key1': 'value1', 'key2': ['value2', 'value3']} >>> r = requests.get('https://httpbin.org/get', params=payload) >>> print(r.url) https://httpbin.org/get?key1=value1&key2=value2&key2=value3 Response Content¶We can read the content of the server’s response. Consider the GitHub timeline again: >>> import requests >>> r = requests.get('https://api.github.com/events') >>> r.text '[{"repository":{"open_issues":0,"url":"https://github.com/... Requests will automatically decode content from the server. Most unicode charsets are seamlessly decoded. When you make a request, Requests makes educated guesses about the encoding of
the response based on the HTTP headers. The text encoding guessed by Requests
is used when you access >>> r.encoding 'utf-8' >>> r.encoding = 'ISO-8859-1' If you change the encoding, Requests will use the new value of Requests will also use custom encodings in the event that you need them. If
you have created your own encoding and registered it with the Binary Response Content¶You can also access the response body as bytes, for non-text requests: >>> r.content b'[{"repository":{"open_issues":0,"url":"https://github.com/... The The For example, to create an image from binary data returned by a request, you can use the following code: >>> from PIL import Image >>> from io import BytesIO >>> i = Image.open(BytesIO(r.content)) JSON Response Content¶There’s also a builtin JSON decoder, in case you’re dealing with JSON data: >>> import requests >>> r = requests.get('https://api.github.com/events') >>> r.json() [{'repository': {'open_issues': 0, 'url': 'https://github.com/... In case the JSON decoding fails, It should be noted that the success of the call to Raw Response Content¶In the rare case that you’d like to get the raw socket response from the
server, you can access >>> r = requests.get('https://api.github.com/events', stream=True) >>> r.raw <urllib3.response.HTTPResponse object at 0x101194810> >>> r.raw.read(10) b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' In general, however, you should use a pattern like this to save what is being streamed to a file: with open(filename, 'wb') as fd: for chunk in r.iter_content(chunk_size=128): fd.write(chunk) Using Note An important note about using Custom Headers¶If you’d like to add HTTP headers to a request, simply pass in a For example, we didn’t specify our user-agent in the previous example: >>> url = 'https://api.github.com/some/endpoint' >>> headers = {'user-agent': 'my-app/0.0.1'} >>> r = requests.get(url, headers=headers) Note: Custom headers are given less precedence than more specific sources of information. For instance:
Furthermore, Requests does not change its behavior at all based on which custom headers are specified. The headers are simply passed on into the final request. Note: All header values must be a More complicated POST requests¶Typically, you want to send some form-encoded data — much like an HTML form.
To do this, simply pass a dictionary to the >>> payload = {'key1': 'value1', 'key2': 'value2'} >>> r = requests.post('https://httpbin.org/post', data=payload) >>> print(r.text) { ... "form": { "key2": "value2", "key1": "value1" }, ... } The >>> payload_tuples = [('key1', 'value1'), ('key1', 'value2')] >>> r1 = requests.post('https://httpbin.org/post', data=payload_tuples) >>> payload_dict = {'key1': ['value1', 'value2']} >>> r2 = requests.post('https://httpbin.org/post', data=payload_dict) >>> print(r1.text) { ... "form": { "key1": [ "value1", "value2" ] }, ... } >>> # httpbin may embed non-deterministic metadata, >>> # so we only compare our submitted data here. >>> r1.json()['form'] == r2.json()['form'] True There are times that you may want to send data that is not form-encoded. If
you pass in a For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data: >>> import json >>> url = 'https://api.github.com/some/endpoint' >>> payload = {'some': 'data'} >>> r = requests.post(url, data=json.dumps(payload)) Please note that the above code will NOT add the If you need that header set and you don’t want to encode the >>> url = 'https://api.github.com/some/endpoint' >>> payload = {'some': 'data'} >>> r = requests.post(url, json=payload) Note, the POST a Multipart-Encoded File¶Requests makes it simple to upload Multipart-encoded files: >>> url = 'https://httpbin.org/post' >>> files = {'file': open('report.xls', 'rb')} >>> r = requests.post(url, files=files) >>> r.text { ... "files": { "file": "<censored...binary...data>" }, ... } You can set the filename, content_type and headers explicitly: >>> url = 'https://httpbin.org/post' >>> files = {'file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel', {'Expires': '0'})} >>> r = requests.post(url, files=files) >>> r.text { ... "files": { "file": "<censored...binary...data>" }, ... } If you want, you can send strings to be received as files: >>> url = 'https://httpbin.org/post' >>> files = {'file': ('report.csv', 'some,data,to,send\nanother,row,to,send\n')} >>> r = requests.post(url, files=files) >>> r.text { ... "files": { "file": "some,data,to,send\\nanother,row,to,send\\n" }, ... } In the event you are posting a very large file as a For sending multiple files in one request refer to the advanced section. Warning It is strongly recommended that you open files in binary
mode. This is because Requests may attempt to provide
the Response Status Codes¶We can check the response status code: >>> r = requests.get('https://httpbin.org/get') >>> r.status_code 200 Requests also comes with a built-in status code lookup object for easy reference: >>> r.status_code == requests.codes.ok True If we made a bad request (a 4XX client error or 5XX server error response), we
can raise it with
>>> bad_r = requests.get('https://httpbin.org/status/404') >>> bad_r.status_code 404 >>> bad_r.raise_for_status() Traceback (most recent call last): File "requests/models.py", line 832, in raise_for_status raise http_error requests.exceptions.HTTPError: 404 Client Error But, since our >>> r.raise_for_status() None All is well. Response Headers¶We can view the server’s response headers using a Python dictionary: >>> r.headers { 'content-encoding': 'gzip', 'transfer-encoding': 'chunked', 'connection': 'close', 'server': 'nginx/1.0.4', 'x-runtime': '148ms', 'etag': '"e1ca502697e5c9317743dc078f67693f"', 'content-type': 'application/json' } The dictionary is special, though: it’s made just for HTTP headers. According to RFC 7230, HTTP Header names are case-insensitive. So, we can access the headers using any capitalization we want: >>> r.headers['Content-Type'] 'application/json' >>> r.headers.get('content-type') 'application/json' It is also special in that the server could have sent the same header multiple times with different values, but requests combines them so they can be represented in the dictionary within a single mapping, as per RFC 7230:
Cookies¶If a response contains some Cookies, you can quickly access them: >>> url = 'http://example.com/some/cookie/setting/url' >>> r = requests.get(url) >>> r.cookies['example_cookie_name'] 'example_cookie_value' To send your own cookies to the server, you can use the >>> url = 'https://httpbin.org/cookies' >>> cookies = dict(cookies_are='working') >>> r = requests.get(url, cookies=cookies) >>> r.text '{"cookies": {"cookies_are": "working"}}' Cookies are returned in a >>> jar = requests.cookies.RequestsCookieJar() >>> jar.set('tasty_cookie', 'yum', domain='httpbin.org', path='/cookies') >>> jar.set('gross_cookie', 'blech', domain='httpbin.org', path='/elsewhere') >>> url = 'https://httpbin.org/cookies' >>> r = requests.get(url, cookies=jar) >>> r.text '{"cookies": {"tasty_cookie": "yum"}}' Redirection and History¶By default Requests will perform location redirection for all verbs except HEAD. We can use the The For example, GitHub redirects all HTTP requests to HTTPS: >>> r = requests.get('http://github.com/') >>> r.url 'https://github.com/' >>> r.status_code 200 >>> r.history [<Response [301]>] If you’re using GET, OPTIONS, POST, PUT, PATCH or DELETE, you can disable
redirection handling with the >>> r = requests.get('http://github.com/', allow_redirects=False) >>> r.status_code 301 >>> r.history [] If you’re using HEAD, you can enable redirection as well: >>> r = requests.head('http://github.com/', allow_redirects=True) >>> r.url 'https://github.com/' >>> r.history [<Response [301]>] Timeouts¶You can tell Requests to stop waiting for a response after a given number of
seconds with the >>> requests.get('https://github.com/', timeout=0.001) Traceback (most recent call last): File "<stdin>", line 1, in <module> requests.exceptions.Timeout: HTTPConnectionPool(host='github.com', port=80): Request timed out. (timeout=0.001) Note
Errors and Exceptions¶In the event of a network problem (e.g. DNS failure, refused connection, etc),
Requests will raise a
If a request times out, a If a request exceeds the configured number of maximum redirections, a
All exceptions that Requests explicitly raises inherit from
Ready for more? Check out the advanced section.
©Kenneth Reitz and contributors.
|
| You are visitor 01402605 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |