Краткое руководство по библиотеке Python Requests
Быстрый старт в библиотеке Requests
Прежде чем начать, убедитесь, что установлена последняя версия Requests.
Для начала, давайте рассмотрим простые примеры.
Создание запроса
Импортируйте модуль Requests:
Попробуем получить веб-страницу. В этом примере давайте рассмотрим общий тайм-лайн GitHub:
Мы получили объект Response с именем r . С помощью этого объекта можно получить всю необходимую информацию.
Простой API Requests означает, что все формы HTTP запросов- очевидны. Ниже приведен пример того, как вы можете сделать запрос HTTP POST:
Другие типы HTTP запросов такие как : PUT, DELETE, HEAD и OPTIONS так же очень легко выполнить:
Передача параметров в URL
Часто вам может понадобится отправить какие-то данные в строке запроса URL. Если вы настраиваете URL вручную, эти данные будут представлены в нем в виде пар ключ/значение после знака вопроса. Например, httpbin.org/get?key=val. Requests позволяет передать эти аргументы в качестве словаря, используя аргумент params . Если вы хотите передать key1=value1 и key2=value2 ресурсу httpbin.org/get, вы должны использовать следующий код:
Как видно, URL был закодирован правильно:
Ключ словаря, значение которого None не будет добавлен в строке запроса URL.
Вы можете передать список параметров в качестве значения:
Содержимое ответа (response)
Мы можем прочитать содержимое ответа сервера. Рассмотрим снова тайм-лайн GitHub:
Requests будет автоматически декодировать содержимое ответа сервера. Большинство кодировок unicode декодируются без проблем.
Когда вы делаете запрос, Requests делает предположение о кодировке, основанное на заголовках HTTP. Эта же кодировка текста, используется при обращение к r.text . Можно узнать, какую кодировку использует Requests, и изменить её с помощью r.encoding :
Если вы измените кодировку, Requests будет использовать новое значение r.encoding всякий раз, когда вы будете использовать r.text . Вы можете сделать это в любой ситуации, где нужна более специализированная логика работы с кодировкой содержимого ответа. Например, в HTML и XML есть возможность задавать кодировку прямо в теле документа. В подобных ситуациях вы должны использовать r.content , чтобы найти кодировку, а затем установить r.encoding . Это позволит вам использовать r.text с правильной кодировкой.
Requests может также использовать пользовательские кодировки в случае, если в них есть потребность. Если вы создали свою собственную кодировку и зарегистрировали ее в модуле codecs, используйте имя кодека в качестве значения r.encoding .
Бинарное содержимое ответа
Вы можете также получить доступ к телу ответа в виде байтов для не текстовых ответов:
Передача со сжатием gzip и deflate автоматически декодируются для вас.
Например, чтобы создать изображение на основе бинарных данных, возвращаемых при ответе на запрос, используйте следующий код:
Содержимое ответа в JSON
Если вы работаете с данными в формате JSON, воспользуйтесь встроенным JSON декодером:
Если декодирование в JSON не удалось, r.json() вернет исключение. Например, если ответ с кодом 204 (No Content), или на случай если ответ содержит не валидный JSON, попытка обращения к r.json() будет возвращать ValueError: No JSON object could be decoded .
Следует отметить, что успешный вызов r.json() не указывает на успешный ответ сервера. Некоторые серверы могут возвращать объект JSON при неудачном ответе (например, сведения об ошибке HTTP 500). Такой JSON будет декодирован и возвращен. Для того, чтобы проверить успешен ли запрос, используйте r.raise_for_status() или проверьте какой r.status_code .
Необработанное содержимое ответа
В тех редких случаях, когда вы хотите получить доступ к “сырому” ответу сервера на уровне сокета, обратитесь к r.raw . Если вы хотите сделать это, убедитесь, что вы указали stream=True в вашем первом запросе. После этого вы уже можете проделать следующее:
Однако, можно использовать подобный код как шаблон, чтобы сохранить результат в файл:
Использование r.iter_content обработает многое из того, с чем бы вам пришлось иметь дело при использовании r.raw напрямую. Для извлечения содержимого при потоковой загрузке, используйте способ, описанный выше. Обратите внимание, что chunk_size можно свободно скорректировать до числа, которое лучше подходит в вашем случае.
Важное замечание об использовании Response.iter_content и Response.raw . Response.iter_content будет автоматически декодировать gzip и deflate . Response.raw — необработанный поток байтов, он не меняет содержимое ответа. Если вам действительно нужен доступ к байтам по мере их возврата, используйте Response.raw .
Пользовательские заголовки
Если вы хотите добавить HTTP заголовки в запрос, просто передайте соответствующий dict в параметре headers .
Например, мы не указали наш user-agent в предыдущем примере:
Заголовкам дается меньший приоритет, чем более конкретным источникам информации. Например:
- Заголовки авторизации, установленные с помощью headers= будут переопределены, если учетные данные указаны .netrc , которые, в свою очередь переопределены параметром auth= .
- Заголовки авторизации будут удалены при редиректе.
- Заголовки авторизации с прокси будут переопределены учетными данными прокси-сервера, которые указаны в вашем URL.
- Заголовки Content-Length будут переопределены, когда вы определите длину содержимого.
Кроме того, запросы не меняют свое поведение вообще, основываясь на указанных пользовательских заголовках.
Значения заголовка должны быть string, bytestring или unicode . Хотя это разрешено, рекомендуется избегать передачи значений заголовков unicode .
Более сложные POST запросы
Часто вы хотите послать некоторые form-encoded данные таким же образом, как это делается в HTML форме. Для этого просто передайте соответствующий словарь в аргументе data . Ваш словарь данных в таком случае будет автоматически закодирован как HTML форма, когда будет сделан запрос:
Аргумент data также может иметь несколько значений для каждого ключа. Это можно сделать, указав data в формате tuple , либо в виде словаря со списками в качестве значений. Особенно полезно, когда форма имеет несколько элементов, которые используют один и тот же ключ:
Бывают случаи, когда нужно отправить данные не закодированные методом form-encoded . Если вы передадите в запрос строку вместо словаря, эти данные отправятся в не измененном виде.
К примеру, GitHub API v3 принимает закодированные JSON POST/PATCH данные:
Вместо того, чтобы кодировать dict , вы можете передать его напрямую, используя параметр json (добавленный в версии 2.4.2), и он будет автоматически закодирован:
Обратите внимание, параметр json игнорируется, если передаются data или files .
Использование параметра json в запросе изменит заголовок Content-Type на application/json.
POST отправка Multipart-Encoded файла
Запросы упрощают загрузку файлов с многостраничным кодированием (Multipart-Encoded) :
Вы можете установить имя файла, content_type и заголовки в явном виде:
Можете отправить строки, которые будут приняты в виде файлов:
В случае, если вы отправляете очень большой файл как запрос multipart/form-data, возможно понадобиться отправить запрос потоком. По умолчанию, requests не поддерживает этого, но есть отдельный пакет, который это делает — requests-toolbelt . Ознакомьтесь с документацией toolbelt для получения более детальной информации о том, как им пользоваться.
Для отправки нескольких файлов в одном запросе, обратитесь к расширенной документации (EN).
Предупреждение!
Настоятельно рекомендуется открывать файлы в бинарном режиме. Это связано с тем, что запросы могут пытаться предоставить для вас заголовок Content-Length, и если это значение будет установлено на количество байтов в файле будут возникать ошибки, при открытии файла в текстовом режиме.
Коды состояния ответа
Мы можем проверить код состояния ответа:
У requests есть встроенный объект вывода кодов состояния:
Если мы сделали неудачный запрос (ошибка 4XX или 5XX), то можем вызвать исключение с помощью r.raise_for_status():
Но если status_code для r оказался 200, то когда мы вызываем raise_for_status() мы получаем:
Заголовки ответов
Мы можем просматривать заголовки ответа сервера, используя словарь Python:
Это словарь особого рода, он создан специально для HTTP заголовков. Согласно с RFC 7230, имена заголовков HTTP нечувствительны к регистру:
Теперь мы можем получить доступ к заголовкам с большми буквами или без, если захотим:
Cookies
Если в запросе есть cookies, вы сможете быстро получить к ним доступ:
Чтобы отправить собственные cookies на сервер, используйте параметр cookies:
Cookies возвращаются в RequestsCookieJar, который работает как dict, но также предлагает более полный интерфейс, подходящий для использования в нескольких доменах или путях. Cookie jars могут также передаваться в запросы:
Редиректы и история
По умолчанию Requests будет выполнять редиректы для всех HTTP глаголов, кроме HEAD.
Мы можем использовать свойство history объекта Response, чтобы отслеживать редиректы .
Список Response.history содержит объекты Response, которые были созданы для того, чтобы выполнить запрос. Список сортируется от более ранних, до более поздних ответов.
Например, GitHub перенаправляет все запросы HTTP на HTTPS:
Если вы используете GET, OPTIONS, POST, PUT, PATCH или DELETE, вы можете отключить обработку редиректа с помощью параметра allow_redirects :
Если вы используете HEAD, вы также можете включить редирект:
Тайм-ауты
Вы можете сделать так, чтобы Requests прекратил ожидание ответа после определенного количества секунд с помощью параметра timeout :
Почти весь производственный код должен использовать этот параметр почти во всех запросах. Несоблюдение этого требования может привести к зависанию вашей программы:
Timeout это не ограничение по времени полной загрузки ответа. Исключение возникает, если сервер не дал ответ за timeout секунд (точнее, если ни одного байта не было получено от основного сокета за timeout секунд).
Использование библиотеки Requests в Python
Для начала давайте разберемся, что же вообще такое библиотека Requests.
Requests — это HTTP-библиотека, написанная на Python (под лицензией Apache2). Она спроектирована для взаимодействия людей с эим языком. Это означает, что вам не нужно вручную добавлять строки запроса в URL-адреса или заносить данные в форму для POST -запроса. Если это кажется вам бессмысленным, не волнуйтесь. В нужное время все прояснится.
Что же делает библиотека Requests?
Библиотека Requests дает вам возможность посылать HTTP/1.1-запросы, используя Python. С ее помощью вы можете добавлять контент, например заголовки, формы, многокомпонентные файлы и параметры, используя только простые библиотеки Python. Также вы можете получать доступ к таким данным.
В программировании библиотека — это набор или, точнее сказать, предварительно настроенный набор подпрограмм, функций и операций, которые в дальнейшем может использовать ваша программа. Эти элементы часто называют модулями, которые хранятся в объектном формате.
Библиотеки очень важны, потому что вы можете загрузить модуль и использовать все, что он предлагает, без явной связи с вашей программой. Они действительно автономны, так что вы можете создавать свои собственные программы с ними, и все же они остаются отделенными от ваших программ.
Таким образом, о модулях можно думать как о неких шаблонах кода.
Повторимся еще раз, Requests — это библиотека языка Python.
Как установить Requests
Сразу сообщим вам хорошую новость: существует множество способов для установки Requests. С полным списком можно ознакомиться в официальной документации библиотеки Requests.
Вы можете использовать pip, easy_install или tarball.
Если вам нужен исходный код, вы можете найти его на GitHub.
Мы для установки библиотеки воспользуемся менеджером pip.
В интерпретаторе Python введите следующую команду:
Импортирование модуля Requests
Для работы с библиотекой Requests в Python вам необходимо импортировать соответствующий модуль. Вы можете это сделать, просто поместив следующий код в начало вашей программы:
Разумеется, предварительно этот модуль должен быть установлен и доступен для интерпретатора.
Делаем запрос
Когда вы пингуете веб-сайт или портал для получения информации, то это как раз и называется созданием запроса.
Для получения веб-страницы вам нужно написать что-то в таком духе:
Работаем с кодом ответа
Перед тем как вы будете что-то делать с веб-сайтом или URL, хорошей идеей будет проверить код ответа, который вернул вам сервер. Это можно сделать следующим образом:
Получаем содержимое страницы
После того как сервер вам ответил, вы можете получить нужный вам контент. Это также делается при помощи функции get библиотеки Requests.
Работаем с заголовками
Используя словари Python, вы можете просмотреть заголовки ответа сервера. Особенностью работы библиотеки Requests является то, что для получения доступа к заголовкам вы можете использовать в ключах словаря как заглавные, так и строчные буквы.
Если вызываемого заголовка нет, будет возвращено значение None .
Кодирование
Библиотека Requests автоматически декодирует любой контент, извлеченный из сервера. Хотя большинство наборов символов Unicode в любом случае легко декодируются.
Когда вы делаете запрос к серверу, библиотека Requests делает обоснованное предположение о кодировке ответа. Это делается на основании заголовков HTTP. Предполагаемая кодировка будет использоваться при доступе к файлу r.text .
С помощью этого файла вы можете определить, какую кодировку использует библиотека Requests, и при необходимости изменить ее. Это возможно благодаря атрибуту r.encoding , который вы найдете в файле.
Когда вы измените значение кодировки, в дальнейшем библиотека Requests при вызове вами r.text будет использовать новый тип кодировки.
Пользовательские заголовки
Если вы хотите добавить пользовательские заголовки в HTTP-запрос, вы должны передать их через словарь в параметр заголовков.
Переадресация и история
Библиотека Requests автоматически поддерживает переадресацию при выполнении команд GET и OPTION .
Например, GitHub из соображений безопасности автотоматически переадресует все HTTP -запросы на HTTPS .
Вы можете отслеживать статус переадресации при помощи метода history , который реализован для объекта response .
Осуществление POST-запроса HTTP
Также с помощью библиотеки Requests вы можете работать и с POST -запросами:
Но вы также можете выполнять и другие HTTP -запросы, такие как PUT , DELETE , HEAD , и OPTIONS .
При помощи этих методов можно сделать массу разных вещей. Например, при помощи следующего кода вы можете создать репозиторий GitHub:
Ошибки и исключения
Есть ряд ошибок и исколючений, с которыми вам надо ознакомиться при использовании библиотеки Requests.
- При проблемах с сетью, например с DNS , или отказе соединения, библиотека Requests вызовет исключение ConnectionError .
- При недопустимом ответе HTTP библиотека Requests вызвоет исключение HTTPError , но это довольно редкий случай.
- Если время запроса истекло, возникнет исключение Timeout .
- Когда при запросе будет превышено заранее заданное количество переадресаций, возникнет исключение TooManyRedirects .
Все исключения, вызываемые библиотекой Requests, наследуются от объекта requests.exceptions.RequestException .
Дополнительные материалы
Более подробно про билиотеку Requests вы можете почитать, пройдя по следующим ссылкам: