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:
Now, let’s try to get a webpage. For this example, let’s get GitHub’s public timeline:
Now, we have a Response object called r . We can get all the information we need from this object.
Requests’ simple API means that all forms of HTTP request are as obvious. For example, this is how you make an HTTP POST request:
Nice, right? What about the other HTTP request types: PUT, DELETE, HEAD and OPTIONS? These are all just as simple:
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. httpbin.org/get?key=val . Requests allows you to provide these arguments as a dictionary of strings, using the params keyword argument. As an example, if you wanted to pass key1=value1 and key2=value2 to httpbin.org/get , you would use the following code:
You can see that the URL has been correctly encoded by printing the URL:
Note that any dictionary key whose value is None will not be added to the URL’s query string.
You can also pass a list of items as a value:
Response Content¶
We can read the content of the server’s response. Consider the GitHub timeline again:
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.text . You can find out what encoding Requests is using, and change it, using the r.encoding property:
If you change the encoding, Requests will use the new value of r.encoding whenever you call r.text . You might want to do this in any situation where you can apply special logic to work out what the encoding of the content will be. For example, HTML and XML have the ability to specify their encoding in their body. In situations like this, you should use r.content to find the encoding, and then set r.encoding . This will let you use r.text with the correct encoding.
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 codecs module, you can simply use the codec name as the value of r.encoding and Requests will handle the decoding for you.
Binary Response Content¶
You can also access the response body as bytes, for non-text requests:
The gzip and deflate transfer-encodings are automatically decoded for you.
The br transfer-encoding is automatically decoded for you if a Brotli library like brotli or brotlicffi is installed.
For example, to create an image from binary data returned by a request, you can use the following code:
JSON Response Content¶
There’s also a builtin JSON decoder, in case you’re dealing with JSON data:
In case the JSON decoding fails, r.json() raises an exception. For example, if the response gets a 204 (No Content), or if the response contains invalid JSON, attempting r.json() raises requests.exceptions.JSONDecodeError . This wrapper exception provides interoperability for multiple exceptions that may be thrown by different python versions and json serialization libraries.
It should be noted that the success of the call to r.json() does not indicate the success of the response. Some servers may return a JSON object in a failed response (e.g. error details with HTTP 500). Such JSON will be decoded and returned. To check that a request is successful, use r.raise_for_status() or check r.status_code is what you expect.
Raw Response Content¶
In the rare case that you’d like to get the raw socket response from the server, you can access r.raw . If you want to do this, make sure you set stream=True in your initial request. Once you do, you can do this:
In general, however, you should use a pattern like this to save what is being streamed to a file:
Using Response.iter_content will handle a lot of what you would otherwise have to handle when using Response.raw directly. When streaming a download, the above is the preferred and recommended way to retrieve the content. Note that chunk_size can be freely adjusted to a number that may better fit your use cases.
An important note about using Response.iter_content versus Response.raw . Response.iter_content will automatically decode the gzip and deflate transfer-encodings. Response.raw is a raw stream of bytes – it does not transform the response content. If you really need access to the bytes as they were returned, use Response.raw .
Custom Headers¶
If you’d like to add HTTP headers to a request, simply pass in a dict to the headers parameter.
For example, we didn’t specify our user-agent in the previous example:
Note: Custom headers are given less precedence than more specific sources of information. For instance:
Authorization headers set with headers= will be overridden if credentials are specified in .netrc , which in turn will be overridden by the auth= parameter. Requests will search for the netrc file at
/_netrc , or at the path specified by the NETRC environment variable.
Authorization headers will be removed if you get redirected off-host.
Proxy-Authorization headers will be overridden by proxy credentials provided in the URL.
Content-Length headers will be overridden when we can determine the length of the content.
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 string , bytestring, or unicode. While permitted, it’s advised to avoid passing unicode header values.
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 data argument. Your dictionary of data will automatically be form-encoded when the request is made:
The data argument can also have multiple values for each key. This can be done by making data either a list of tuples or a dictionary with lists as values. This is particularly useful when the form has multiple elements that use the same key:
There are times that you may want to send data that is not form-encoded. If you pass in a string instead of a dict , that data will be posted directly.
For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:
Please note that the above code will NOT add the Content-Type header (so in particular it will NOT set it to application/json ).
If you need that header set and you don’t want to encode the dict yourself, you can also pass it directly using the json parameter (added in version 2.4.2) and it will be encoded automatically:
Note, the json parameter is ignored if either data or files is passed.
POST a Multipart-Encoded File¶
Requests makes it simple to upload Multipart-encoded files:
You can set the filename, content_type and headers explicitly:
If you want, you can send strings to be received as files:
In the event you are posting a very large file as a multipart/form-data request, you may want to stream the request. By default, requests does not support this, but there is a separate package which does — requests-toolbelt . You should read the toolbelt’s documentation for more details about how to use it.
For sending multiple files in one request refer to the advanced section.
It is strongly recommended that you open files in binary mode . This is because Requests may attempt to provide the Content-Length header for you, and if it does this value will be set to the number of bytes in the file. Errors may occur if you open the file in text mode.
Response Status Codes¶
We can check the response status code:
Requests also comes with a built-in status code lookup object for easy reference:
If we made a bad request (a 4XX client error or 5XX server error response), we can raise it with Response.raise_for_status() :
But, since our status_code for r was 200 , when we call raise_for_status() we get:
Response Headers¶
We can view the server’s response headers using a Python dictionary:
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:
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:
A recipient MAY combine multiple header fields with the same field name into one “field-name: field-value” pair, without changing the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by a comma.
Cookies¶
If a response contains some Cookies, you can quickly access them:
To send your own cookies to the server, you can use the cookies parameter:
Cookies are returned in a RequestsCookieJar , which acts like a dict but also offers a more complete interface, suitable for use over multiple domains or paths. Cookie jars can also be passed in to requests:
Redirection and History¶
By default Requests will perform location redirection for all verbs except HEAD.
We can use the history property of the Response object to track redirection.
The Response.history list contains the Response objects that were created in order to complete the request. The list is sorted from the oldest to the most recent response.
For example, GitHub redirects all HTTP requests to HTTPS:
If you’re using GET, OPTIONS, POST, PUT, PATCH or DELETE, you can disable redirection handling with the allow_redirects parameter:
If you’re using HEAD, you can enable redirection as well:
Timeouts¶
You can tell Requests to stop waiting for a response after a given number of seconds with the timeout parameter. Nearly all production code should use this parameter in nearly all requests. Failure to do so can cause your program to hang indefinitely:
timeout is not a time limit on the entire response download; rather, an exception is raised if the server has not issued a response for timeout seconds (more precisely, if no bytes have been received on the underlying socket for timeout seconds). If no timeout is specified explicitly, requests do not time out.
Errors and Exceptions¶
In the event of a network problem (e.g. DNS failure, refused connection, etc), Requests will raise a ConnectionError exception.
Response.raise_for_status() will raise an HTTPError if the HTTP request returned an unsuccessful status code.
If a request times out, a Timeout exception is raised.
If a request exceeds the configured number of maximum redirections, a TooManyRedirects exception is raised.
All exceptions that Requests explicitly raises inherit from requests.exceptions.RequestException .
Ready for more? Check out the advanced section.
If you’re on the job market, consider taking this programming quiz. A substantial donation will be made to this project, if you find a job through this platform.
Requests is an elegant and simple HTTP library for Python, built for human beings. You are currently looking at the documentation of the development release.
Python Requests Tutorial — GET and POST Requests in Python
In this Requests tutorial article, you will be learning all the basics of the requests module using Python to get you started with using Requests. We will be covering the following topics in this blog:
- What is the Requests module?
- Installing Requests module
- Making a GET Requests
- Downloading Image with Requests
- Making POST Requests
- Sending Cookies and Headers
- Session Objects
- Conclusion
Let us begin this “Requests Tutorial” blog by first checking out what the Requests Module actually is.
What Is Requests Module?
Requests is a Python module that you can use to send all kinds of HTTP requests. It is an easy-to-use library with a lot of features ranging from passing parameters in URLs to sending custom headers and SSL Verification. In this tutorial, you will learn how to use this library to send simple HTTP requests in Python.
Requests allow you to send HTTP/1.1 requests. You can add headers, form data, multi-part files, and parameters with simple Python dictionaries, and access the response data in the same way.
Installing The Requests module
To install requests, simply:
Or, if you absolutely must:
Making a GET Request
It is fairly straightforward to send an HTTP request using Requests. You start by importing the module and then making the request. Check out the example:
So, all the information is stored somewhere, correct?
Yes, it is stored in a Response object called as req.
Let’s say, for example, you want the encoding of a web-page so that you can verify it or use it somewhere else. This can be done using the req.encoding property.
An added plus is that you can also extract many features like the status code for example (of the request). This can be done using the req.status_code property.
We can also access the cookies that the server sent back. This is done using req.cookies, as straightforward as that! Similarly, you can get the response headers as well. This is done by making use of req.headers.
Do note that the req.headers property will return a case-insensitive dictionary of the response headers. So, what does this imply?
This means that req.headers[‘Content-Length’], req.headers[‘content-length’] and req.headers[‘CONTENT-LENGTH’] will all return the value of the just the ‘Content-Length’ response header.
We can also check if the response obtained is a well-formed HTTP redirect (or not) that could have been processed automatically using the req.is_redirect property. This will return True or False based on the response obtained.
You can also get the time elapsed between sending the request and getting back a response using another property. Take a guess? Yes, it is the req.elapsed property.
Remember the URL that you initially passed to the get() function? Well, it can be different than the final URL of the response for many reasons and this includes redirects as well.
And to see the actual response URL, you can use the req.url property.
Don’t you think that getting all this information about the webpage is nice? But, the thing is that you most probably want to access the actual content, correct?
If the content you are accessing is text, you can always use the req.text property to access it. Do note that the content is then parsed as Unicode only. You can pass this encoding with which to decode this text using the req.encoding property as we discussed earlier.
In the case of non-text responses, you can access them very easily. In fact it’s done in binary format when you use req.content. This module will automatically decode gzip and deflate transfer-encodings for us. This can be very helpful when you are dealing directly with media files. Also, you can access the JSON-encoded content of the response as well, that is if it exists, using the req.json() function.
Pretty simple and a lot of flexibility, right?
Also, if needed, you can also get the raw response from the server just by using req.raw. Do keep in mind that you will have to pass stream=True in the request to get the raw response as per need.
But, some files that you download from the internet using the Requests module may have a huge size, correct? Well, in such cases, it will not be wise to load the whole response or file in the memory at once. But, it is recommended that you download a file in pieces or chunks using the iter_content(chunk_size = 1, decode_unicode = False) method.
So, this method iterates over the response data in chunk_size number of bytes at once. And when the stream=True has been set on the request, this method will avoid reading the whole file into memory at once for just the large responses.
Do note that the chunk_size parameter can be either an integer or None. But, when set to an integer value, chunk_size determines the number of bytes that should be read into the memory at once.
When chunk_size is set to None and stream is set to True, the data will be read as it arrives in whatever size of chunks are received as and when they are. But, when chunk_size is set to None and stream is set to False, all the data will be returned as a single chunk of data only.
Downloading An Image Using Requests Module
So let’s download the following image of a forest on Pixabay using the Requests module we learned about. Here is the actual image:
This is the code that you will need to download the image:
Note that the ‘path/to/forest.jpg’ is the actual image URL. You can put the URL of any other image here to download something else as well. This is just an example showed here and the given image file is about 185kb in size and you have set chunk_size to 50,000 bytes.
This means that the “Received a Chunk” message should be printed four times in the terminal. The size of the last chunk will just be 39350 bytes because the part of the file that remains to be received after the first three iterations is 39350 bytes.
Requests also allow you to pass parameters in a URL. This is particularly helpful when you are searching for a webpage for some results like a tutorial or a specific image. You can provide these query strings as a dictionary of strings using the params keyword in the GET request. Check out this easy example:
Next up in this “Requests Tutorial” blog, let us look at how we can make a POST request!
Making a POST Request
Making a POST request is just as easy as making GET requests. You just use the post() function instead of get().
This can be useful when you are automatically submitting forms. For example, the following code will download the whole Wikipedia page on Nanotechnology and save it on your PC.
Sending Cookies and Headers
As previously mentioned, you can access the cookies and headers that the server sends back to you using req.cookies and req.headers. Requests also allow you to send your own custom cookies and headers with a request. This can be helpful when you want to, let’s say, set a custom user agent for your request.
To add HTTP headers to a request, you can simply pass them in a dict to the headers parameter. Similarly, you can also send your own cookies to a server using a dict passed to the cookies parameter.
Cookies can also be passed in a Cookie Jar. They provide a more complete interface to allow you to use those cookies over multiple paths.
Check out this example below:
Next up on this “Requests Tutorial” blog, let us look at session objects!
Session Objects
Sometimes it is useful to preserve certain parameters across multiple requests. The Session object does exactly that. For example, it will persist cookie data across all requests made using the same session.
The Session object uses urllib3’s connection pooling. This means that the underlying TCP connection will be reused for all the requests made to the same host.
This can significantly boost the performance. You can also use methods of the Requests object with the Session object.
Sessions are also helpful when you want to send the same data across all requests. For example, if you decide to send a cookie or a user-agent header with all the requests to a given domain, you can use Session objects.
Here is an example:
As you can see, the “visit-month” session cookie is sent with all three requests. However, the “visit-year” cookie is sent only during the second request. There is no mention of the “visit-year” cookie in the third request too. This confirms the fact that cookies or other data set on individual requests won’t be sent with other session requests.
Conclusion
The concepts discussed in this tutorial should help you make basic requests to a server by passing specific headers, cookies, or query strings.
This will be very handy when you are trying to scrape some web pages for information. Now, you should also be able to automatically download music files and wallpapers from different websites once you have figured out a pattern in the URLs.
I hope you have enjoyed this post on Requests Tutorial.If you wish to check out more articles on the market’s most trending technologies like Artificial Intelligence, DevOps, Ethical Hacking, then you can refer to Edureka’s official site.
Do look out for other articles in this series which will explain the various other aspects of Python and Data Science.
Requests в Python – Примеры выполнения HTTP запросов
Библиотека requests является стандартным инструментом для составления HTTP-запросов в Python. Простой и аккуратный API значительно облегчает трудоемкий процесс создания запросов. Таким образом, можно сосредоточиться на взаимодействии со службами и использовании данных в приложении.
Содержание статьи
В данной статье представлены наиболее полезные особенности requests. Показано, как изменить и приспособить requests к различным ситуациям, с которыми программисты сталкиваются чаще всего. Здесь также даются советы по эффективному использованию requests и предотвращению влияния сторонних служб, которые могут сильно замедлить работу используемого приложения. Мы использовали библиотек requests в уроке по парсингу html через библиотеку BeautifulSoup.
Ключевые аспекты инструкции:
- Создание запросов при помощи самых популярных HTTP методов;
- Редактирование заголовков запросов и данных при помощи строки запроса и содержимого сообщения;
- Анализ данных запросов и откликов;
- Создание авторизированных запросов;
- Настройка запросов для предотвращения сбоев и замедления работы приложения.
В статье собран оптимальный набор информации, необходимый для понимания данных примеров и особенностей их использования. Информация представлена в доступной в форме. Тем не менее, стоит иметь в виду, что для оптимального разбора инструкции потребуются хотя бы базовые знания HTTP.
Далее будут показаны наиболее эффективные методы использования requests в разрабатываемом приложении.
Python установка библиотеки requests
Для начала работы потребуется установить библиотеку requests . Для этого используется следующая команда.
Есть вопросы по Python?
На нашем форуме вы можете задать любой вопрос и получить ответ от всего нашего сообщества!
Использование модуля Requests в Python
Monty Shokeen Last updated Mar 9, 2017
Requests — это модуль Python, который вы можете использовать для отправки всех видов HTTP-запросов. Это простая в использовании библиотека с множеством функций, начиная от передачи параметров в URL-адресах до отправки пользовательских заголовков и проверки SSL. В этом уроке вы узнаете, как использовать эту библиотеку для отправки простых HTTP-запросов в Python.
Вы можете использовать Запросы с Python версии 2.6-2.7 и 3.3-3.6. Прежде чем продолжить, вы должны знать о том, что Requests является внешним модулем, поэтому сначала вам нужно будет установить его, прежде чем попробовать примеры из этого урока. Вы можете установить его, выполнив следующую команду в терминале:
После установки модуля вы можете проверить, был ли он успешно установлен, импортировав его с помощью этой команды:
Если установка прошла успешно, вы не увидите никаких сообщений об ошибках.
Создание запроса GET
Очень просто отправить HTTP-запрос с помощью Requests. Сначала вы импортируете модуль и затем выполните запрос. Вот пример:
Вся информация о нашем запросе теперь хранится в объекте Response, называемом req . Например, вы можете получить кодировку веб-страницы, используя свойство req.encoding . Вы также можете получить код состояния запроса, используя свойство req.status_code .
Вы можете получить доступ к файлам cookie, отправленным сервером с помощью req.cookies . Аналогично, вы можете получить заголовки ответов, используя req.headers . Свойство req.headers возвращает нечувствительный к регистру словарь заголовков ответов. Это означает, что req.headers[‘Content-Length’] , req.headers[‘content-length’] и req.headers[‘CONTENT-LENGTH’] вернут значение заголовка ответа Content-Length .
Вы можете проверить, является ли ответ корректным HTTP-перенаправлением, которое могло быть обработано автоматически с использованием свойства req.is_redirect . Он будет возвращать True или False на основе ответа. Вы также можете получить время, прошедшее между отправкой запроса и возвратом ответа с использованием свойства req.elapsed .
URL, который вы первоначально передали функции get() , может отличаться от конечного URL-адреса ответа по целому ряду причин, включая перенаправления. Чтобы увидеть окончательный URL-адрес ответа, вы можете использовать свойство req.url .
Получение всей этой информации о веб-странице, к которой вы обращаетесь, приятно, но вы, скорее всего, хотите получить доступ к фактическому контенту. Если контент, к которому вы обращаетесь, является текстом, вы можете использовать свойство req.text для доступа к нему. Затем содержимое анализируется как unicode. Вы можете передать кодировку, с помощью которой можно декодировать текст, используя свойство req.encoding .
В случае нетекстовых ответов вы можете получить к ним доступ в двоичной форме, используя req.content . Модуль автоматически расшифровывает gzip и deflate кодирование передачи. Это может быть полезно, когда вы имеете дело с медиафайлами. Аналогично, вы можете получить доступ к json-закодированному контенту ответа, если он существует, используя req.json() .
Вы также можете получить исходный ответ с сервера, используя req.raw . Имейте в виду, что вам придется передать stream=True в запросе, чтобы получить исходный ответ.
Некоторые файлы, которые вы загружаете из Интернета с помощью модуля Requests, могут иметь огромный размер. В таких случаях неразумно загружать весь ответ или файл в память сразу. Вы можете загрузить файл на куски или фрагменты, используя метод iter_content(chunk_size = 1, decode_unicode = False) .
Этот метод выполняет итерацию по данным ответа в chunk_size количество байтов одновременно. Когда в запросе задан stream = True , этот метод не позволит сразу считывать весь файл в память для больших ответов. Параметр chunk_size может быть integer или None . Когда установлено значение integer, chunk_size определяет количество байтов, которые должны быть прочитаны в памяти.
Если для параметра chunk_size установлено значение None , а для stream установлено значение True , данные будут считаны по мере того, как он достигнет любого размера кусков. Если для параметра chunk_size установлено значение None , а для stream установлено значение False , все данные будут возвращены как один кусок.
Давайте загрузим этот образ леса на Pixabay с помощью модуля Requests. Вот фактическое изображение:
Это код, который вам нужен:
‘path/to/forest.jpg’ — это фактический URL изображения; вы можете поместить URL-адрес любого другого изображения здесь, чтобы загрузить что-то еще. Данный файл изображения имеет размер 185kb, и вы установили chunk_size в 50 000 байт. Это означает, что сообщение «Получено сообщение» должно быть напечатано четыре раза в терминале. Размер последнего фрагмента будет всего 39350 байт, потому что часть файла, которая остается полученной после первых трех итераций, составляет 39350 байт.
Запросы также позволяют передавать параметры в URL-адресе. Это может быть полезно при поиске на веб-странице некоторых результатов, таких как конкретный образ или учебник. Вы можете предоставить эти строки запроса как словарь строк, используя ключевое слово params в запросе GET. Вот пример:
Выполнение запроса POST
Выполнение запроса POST так же просто, как создание запросов GET. Вы просто используете функцию post() вместо get() . Это может быть полезно, когда вы автоматически отправляете формы. Например, следующий код загрузит всю страницу Википедии по нанотехнологии и сохранит ее на вашем ПК.
Отправка файлов cookie и заголовков
Как уже упоминалось ранее, вы можете получить доступ к файлам cookie и заголовкам, которые сервер отправляет вам обратно с помощью req.cookies и req.headers . Запросы также позволяют отправлять свои собственные cookie-файлы и заголовки с запросом. Это может быть полезно, если вы хотите, скажем, установить пользовательский агента для вашего запроса.
Чтобы добавить HTTP-заголовки в запрос, вы можете просто передать их в dict для параметра headers . Аналогично, вы также можете отправлять свои собственные файлы cookie на сервер, используя dict , переданный в параметр cookie .
Cookies также может быть передано в Cookie Jar. Они предоставляют более полный интерфейс, позволяющий использовать эти файлы cookie на нескольких путях. Вот пример:
Объекты сеанса
Иногда полезно сохранять определенные параметры для нескольких запросов. Объект Session делает именно это. Например, он будет сохранять данные cookie во всех запросах, сделанных с использованием того же сеанса. Объект Session использует объединение соединений urllib3. Это означает, что базовое TCP-соединение будет повторно использоваться для всех запросов, сделанных на один и тот же хост. Это может значительно повысить производительность. Вы также можете использовать методы объекта Requests с объектом Session.
Ниже приведен пример нескольких запросов, отправленных с использованием и без использования сеансов:
Как вы можете видеть, cookie сеанса имеет другое значение в первом и втором запросах, но имеет такое же значение, когда мы использовали объект Session. При тестировании кода вы получите другое значение, но в вашем случае cookie для запросов, сделанных с использованием объекта сеанса, будет иметь такое же значение.
Сессии также полезны, если вы хотите отправлять одни и те же данные по всем запросам. Например, если вы решили отправить куки-файл или заголовок пользовательского агента со всеми запросами в данный домен, вы можете использовать объекты сеанса. Вот пример:
Как вы можете видеть, cookie сеанса «visit-month» отправляется со всеми тремя запросами. Однако cookie «visit-year» отправляется только во время второго запроса. В третьем запросе также не упоминается «vist-year» . Это подтверждает тот факт, что файлы cookie или другие данные, установленные по отдельным запросам, не будут отправляться с другими запросами сеанса.
Заключение
Концепции, обсуждаемые в этом руководстве, должны помочь вам сделать базовые запросы на сервер путем передачи определенных заголовков, куки или строк запроса. Это будет очень удобно, когда вы пытаетесь получить данные с некоторых веб-страниц. Теперь вы также сможете автоматически загружать музыкальные файлы и обои с разных сайтов, как только вы определили шаблон в URL-адресах.
Не стесняйтесь посмотреть то, что у нас есть для продажи и для изучения на рынке, и не стесняйтесь задавать любые вопросы и предоставлять ценную обратную связь, используя приведенный ниже канал.
Если у вас есть какие-либо вопросы относительно этого урока, пожалуйста, дайте мне знать в комментариях.