Интерфейс разработчика

Основной интерфейс

Ко всем функциям Requests можно получить доступ через эти 7 методов. Все они возвращают экземпляр объекта Response.

requests.request(method, url, **kwargs)[source]

Создаёт и отправляет Request.

Параметры

• method – метод для нового объекта Request: GET, OPTIONS, HEAD, POST, PUT, PATCH, или DELETE.
• url – URL для нового объекта Request объекта.
• params – (необязательно) Словарь, список кортежей или байты для отправки в строке запроса для Request.
• data – (необязательно) Словарь, список кортежей, байты или объект типа file-like для отправки в теле Request.
• json – (необязательно) Объект Python, сериализуемый в JSON, для отправки в теле Request.
• headers – (необязательно) Словарь HTTP-заголовков для отправки с Request.
• cookies – (необязательно) Объект Dict или CookieJar для отправки с Request.
• files – (необязательно) Словарь 'name': file-like-objects (или {'name': file-tuple}) для загрузки с помощью multipart-кодирования. file-tuple может быть кортежем из 2-х ('filename', fileobj), 3-х ('filename', fileobj, 'content_type') элементов или 4-х ('filename', fileobj, 'content_type', custom_headers), где 'content-type' — строка, определяющая тип содержимого заданного файла, а custom_headers — объект типа dict, содержащий дополнительные заголовки для добавления для файла.
• auth – (необязательно) Кортеж авторизации для включения Basic/Digest/Custom HTTP Auth.
• timeout (float или кортеж) – (необязательно) Сколько секунд ждать ответа от сервера, как число с плавающей точкой или кортеж (время ожидания подключения, время ожидания чтения).
• allow_redirects (bool) – (необязательно) Булево значение. Включить/выключить переадресацию GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD. По умолчанию True.
• proxies – (необязательно) Словарь, сопоставляющий протокол с URL прокси.
• verify – (необязательно) Булево значение, контролирует проверку сертификата сервера TLS, или строка — путь к файлу CA bundle для использования. По умолчанию True.
• stream – (необязательно) если False, содержимое ответа будет загружено немедленно.
• cert – (необязательно) если Строка, путь к файлу ssl клиентского сертификата (.pem). Если Кортеж, пара (‘cert’, ‘key’).

Возвращает

Объект Response.

Тип возвращаемого значения

requests.Response

Использование:

>>> import requests
>>> req = requests.request('GET', 'https://httpbin.org/get')
>>> req
<Response [200]>

requests.head(url, **kwargs)[source]

Отправляет запрос HEAD.

Параметры

• url – URL для нового объекта Request.
• **kwargs – Необязательные аргументы, которые request принимает. Если allow_redirects не указано, оно будет установлено в False (в отличие от поведения по умолчанию request).

Возвращает

Объект Response.

Тип возвращаемого значения

requests.Response

requests.get(url, params=None, **kwargs)[source]

Отправляет запрос GET.

Параметры

• url – URL для нового объекта Request.
• params – (необязательно) Словарь, список кортежей или байты для отправки в строке запроса для Request.
• **kwargs – Необязательные аргументы, которые request принимает.

Возвращает

Объект Response.

Тип возвращаемого значения

requests.Response

requests.post(url, data=None, json=None, **kwargs)[source]

Отправляет запрос POST.

Параметры

• url – URL для нового объекта Request.
• data – (необязательно) Словарь, список кортежей, байты или объект типа file-like для отправки в теле Request.
• json – (необязательно) json данные для отправки в теле Request.
• **kwargs – Необязательные аргументы, которые request принимает.

Возвращает

Объект Response.

Тип возвращаемого значения

requests.Response

requests.put(url, data=None, **kwargs)[source]

Отправляет запрос PUT.

Параметры

• url – URL для нового объекта Request.
• data – (необязательно) Словарь, список кортежей, байты или подобный файлу объект для отправки в теле Request.
• json – (необязательно) данные JSON для отправки в теле Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Возвращает

Объект Response

Тип возвращаемого значения

requests.Response

requests.patch(url, data=None, **kwargs)[source]

Отправляет запрос PATCH.

Параметры

• url – URL для нового объекта Request объекта.
• data – (необязательно) Словарь, список кортежей, байты или подобный файлу объект для отправки в теле Request.
• json – (необязательно) данные JSON для отправки в теле Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Возвращает

Объект Response

Тип возвращаемого значения

requests.Response

requests.delete(url, **kwargs)[source]

Отправляет запрос DELETE.

Параметры

• url – URL для нового объекта Request объекта.
• **kwargs – Необязательные аргументы, которые принимает request.

Возвращает

Объект Response

Тип возвращаемого значения

requests.Response

Исключения

исключение requests.RequestException(*args, **kwargs)[source]

Произошло неявное исключение при обработке запроса.

исключение requests.ConnectionError(*args, **kwargs)[source]

Произошла ошибка соединения.

исключение requests.HTTPError(*args, **kwargs)[source]

Произошла ошибка HTTP.

исключение requests.URLRequired(*args, **kwargs)[source]

Для выполнения запроса требуется корректный URL.

исключение requests.TooManyRedirects(*args, **kwargs)[source]

Слишком много редиректов.

исключение requests.ConnectTimeout(*args, **kwargs)[source]

Запрос завис во время попытки соединения с удалённым сервером.

Запросы, которые породили эту ошибку, можно безопасно повторить.

исключение requests.ReadTimeout(*args, **kwargs)[source]

Сервер не передал данные за отведённое время.

исключение requests.Timeout(*args, **kwargs)[source]

Запрос завис.

Перехватив эту ошибку, вы перехватите как ConnectTimeout, так и ReadTimeout ошибки.

Сеансы запросов

классrequests.Session[source]

Сеанс запросов Requests.

Обеспечивает сохранение куки, пул соединений и конфигурацию.

Базовое использование:

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

Или как менеджер контекста:

>>> with requests.Session() as s:
...     s.get('https://httpbin.org/get')
<Response [200]>

auth

Кортеж или объект аутентификации по умолчанию, который следует прикрепить к Request.

cert

Сертификат клиента SSL по умолчанию, если строка, путь к файлу сертификата клиента ssl (.pem). Если кортеж, пара (‘cert’, ‘key’).

close()[source]

Закрывает все адаптеры и, таким образом, сеанс

cookies

CookieJar, содержащий все текущие куки, установленные в этом сеансе. По умолчанию это RequestsCookieJar, но может быть любым другим cookielib.CookieJar совместимым объектом.

delete(url, **kwargs)[source]

Отправляет запрос DELETE. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Тип возвращаемого значения

requests.Response

get(url, **kwargs)[source]

Отправляет GET запрос. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Тип возвращаемого значения

requests.Response

get_adapter(url)[source]

Возвращает соответствующий адаптер соединения для данного URL.

Тип возвращаемого значения

requests.adapters.BaseAdapter

get_redirect_target(resp)

Принимает Response. Возвращает URI перенаправления или None

head(url, **kwargs)[source]

Отправляет запрос HEAD. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Тип возвращаемого значения

requests.Response

headers

Нечувствительный к регистру словарь заголовков, которые будут отправляться с каждым Request отправленным от этого Session.

hooks

Обработчики событий.

max_redirects

Максимальное количество перенаправлений. Если запрос превысит это ограничение, возникает исключение TooManyRedirects. По умолчанию requests.models.DEFAULT_REDIRECT_LIMIT, которое равно 30.

merge_environment_settings(url, proxies, stream, verify, cert)[source]

Проверяет среду и объединяет её с некоторыми настройками.

Тип возвращаемого значения

dict

mount(prefix, adapter)[source]

Регистрирует адаптер соединения с префиксом.

Адаптеры упорядочены в порядке убывания длины префикса.

options(url, **kwargs)[source]

Отправляет запрос OPTIONS. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• **kwargs – Необязательные аргументы, которые принимает request.

Тип возвращаемого значения

requests.Response

params

Словарь данных строки запроса, которые следует прикрепить к каждому Request. Значения словаря могут быть списками для представления параметров запроса с несколькими значениями.

patch(url, data=None, **kwargs)[source]

Отправляет запрос PATCH. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• data – (необязательно) Словарь, список кортежей, байты или объект типа «поток» для отправки в теле объекта Request.
• **kwargs – Необязательные аргументы, которые request принимает.

Тип возвращаемого значения

requests.Response

post(url, data=None, json=None, **kwargs)[source]

Отправляет запрос POST. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• data – (необязательно) Словарь, список кортежей, байты или объект типа «поток» для отправки в теле объекта Request.
• json – (необязательно) json для отправки в теле объекта Request.
• **kwargs – Необязательные аргументы, которые request принимает.

Тип возвращаемого значения

requests.Response

prepare_request(request)[source]

Создаёт объект PreparedRequest для передачи и возвращает его. У объекта PreparedRequest настройки объединяются из объекта Request и настроек объекта Session.

Параметры

request – Экземпляр Request для подготовки с настройками этого сеанса.

Тип возвращаемого значения

requests.PreparedRequest

proxies

Словарь, сопоставляющий протокол или протокол и хост с URL прокси-сервера (например, {‘http’: ‘foo.bar:3128’, ‘http://host.name’: ‘foo.bar:4012’}), который будет использоваться для каждого объекта Request.

put(url, data=None, **kwargs)[source]

Отправляет запрос PUT. Возвращает объект Response.

Параметры

• url – URL для нового объекта Request.
• data – (необязательно) Словарь, список кортежей, байты или объект типа «поток» для отправки в теле объекта Request.
• **kwargs – Необязательные аргументы, которые request принимает.

Тип возвращаемого значения

requests.Response

rebuild_auth(prepared_request, response)

При перенаправлении мы можем захотеть удалить аутентификацию из запроса, чтобы избежать утечки учетных данных. Этот метод интеллектуально удаляет и повторно применяет аутентификацию, где это возможно, чтобы избежать потери учетных данных.

rebuild_method(prepared_request, response)

При перенаправлении мы можем захотеть изменить метод запроса в зависимости от определённых спецификаций или поведения браузера.

rebuild_proxies(prepared_request, proxies)

Этот метод повторно оценивает конфигурацию прокси, учитывая переменные окружения. Если мы перенаправлены на URL, охваченный NO_PROXY, мы удаляем конфигурацию прокси. В противном случае мы устанавливаем недостающие ключи прокси для этого URL (в случае, если они были удалены предыдущим перенаправлением).

Этот метод также заменяет заголовок Proxy-Authorization при необходимости.

Тип возвращаемого значения

dict

request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)[source]

Создаёт Request, подготавливает его и отправляет. Возвращает объект Response.

Параметры

• method – метод для нового объекта Request.
• url – URL для нового объекта Request.
• params – (необязательно) Словарь или байты, которые необходимо отправить в строке запроса для Request.
• data – (необязательно) Словарь, список кортежей, байты или файл-подобный объект для отправки в теле Request.
• json – (необязательно) json для отправки в теле Request.
• headers – (необязательно) Словарь HTTP-заголовков для отправки с Request.
• cookies – (необязательно) Объект Dict или CookieJar для отправки с Request.
• files – (необязательно) Словарь 'filename': file-like-objects для загрузки с помощью многочастной кодировки.
• auth – (необязательно) Кортеж или вызываемая функция для включения Basic/Digest/Custom HTTP Auth.
• timeout (float или tuple) – (необязательно) Сколько времени ожидать ответа от сервера, как число с плавающей точкой или кортеж (connect timeout, read timeout).
• allow_redirects (bool) – (необязательно) По умолчанию значение True.
• proxies – (необязательно) Словарь, сопоставляющий протокол или протокол и имя хоста с URL прокси-сервера.
• stream – (необязательно) нужно ли немедленно загружать содержимое ответа. По умолчанию False.
• verify – (необязательно) Булево значение, определяющее, нужно ли проверять сертификат TLS сервера, или строка, представляющая путь к файлу с набором доверенных сертификатов. По умолчанию True. Если verify установлено в False, запросы примут любой представленный сервером сертификат TLS и проигнорируют несоответствия имён хостов и/или истекшие сертификаты, что сделает ваше приложение уязвимым к атакам «человек посередине» (MitM). Установка verify в False может быть полезна во время локального тестирования.
• cert – (необязательно) если Строка, путь к файлу ssl клиентского сертификата (.pem). Если Кортеж, пара (‘cert’, ‘key’).

Тип возвращаемого значения

requests.Response

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)

Принимает ответ. Возвращает генератор ответов или запросов.

send(request, **kwargs)[source]

Отправка заданного PreparedRequest.

Тип возвращаемого значения

requests.Response

should_strip_auth(old_url, new_url)

Определяет, следует ли удалить заголовок Authorization при перенаправлении.

stream

Значение по умолчанию для потоковой передачи содержимого ответа.

trust_env

Доверять настройкам среды для конфигурации прокси, аутентификации и т. п.

verify

Значение по умолчанию для проверки SSL. По умолчанию True, что требует проверки сертификата TLS на удалённом конце. Если verify установлено в False, запросы примут любой представленный сервером сертификат TLS и проигнорируют несоответствия имён хостов и/или истекшие сертификаты, что сделает ваше приложение уязвимым к атакам «человек посередине» (MitM). Устанавливайте это значение только в False для тестирования.

Классы нижнего уровня

class requests.Request(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)[source]

Созданный пользователем объект Request.

Используется для подготовки объекта PreparedRequest, который отправляется на сервер.

Параметры

• method – HTTP-метод для использования.
• url – URL для отправки.
• headers – словарь заголовков для отправки.
• files – словарь {имя_файла: файл_объект} для многоадресной загрузки файлов.
• data – тело для добавления к запросу. Если предоставлен словарь или список кортежей [(key, value)] , будет выполнено кодирование формы.
• json – json для тела, добавляемого к запросу (если не указаны файлы или данные).
• params – параметры URL для добавления к URL. Если предоставлен словарь или список кортежей [(key, value)] , будет выполнено кодирование формы.
• auth – обработчик авторизации или кортеж (пользователь, пароль).
• cookies – словарь или CookieJar cookie для добавления к этому запросу.
• hooks – словарь обратных вызовов, для внутреннего использования.

Использование:

>>> import requests
>>> req = requests.Request('GET', 'https://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>

deregister_hook(event, hook)

Дерегистрация ранее зарегистрированного обработчика. Возвращает True, если обработчик существовал, False — если нет.

prepare()[source]

Создает объект PreparedRequest для передачи и возвращает его.

register_hook(event, hook)

Правильная регистрация обработчика.

класс requests.Response[source]

Объект Response, содержащий ответ сервера на HTTP-запрос.

свойство apparent_encoding

Явное кодирование, предоставленное библиотеками charset_normalizer или chardet.

close()[source]

Возвращает соединение обратно в пул. После вызова этого метода к базовому объекту raw больше нельзя обращаться.

Примечание: обычно вызывать явно не нужно.

свойство content

Содержание ответа в байтах.

cookies

Объект CookieJar с куками, отправленными сервером.

elapsed

Время, затраченное между отправкой запроса и получением ответа (как timedelta). Это свойство измеряет время, прошедшее между отправкой первого байта запроса и завершением обработки заголовков. Поэтому оно не зависит от потребления содержимого ответа или значения ключевого аргумента stream.

encoding

Кодировка для декодирования при доступе к r.text.

headers

Словарь заголовков ответа (регистронезависимый). Например, headers['content-encoding'] вернёт значение заголовка ответа 'Content-Encoding'.

history

Список объектов Response из истории запроса. Все ответы перенаправлений будут здесь. Список отсортирован от старых к новым.

свойство is_permanent_redirect

True, если этот ответ — одно из постоянных перенаправлений.

свойство is_redirect

True, если этот ответ — корректное HTTP-перенаправление, которое можно было обработать автоматически (методом Session.resolve_redirects).

iter_content(chunk_size=1, decode_unicode=False)[source]

Итерируется по данным ответа. Когда stream=True установлено для запроса, это позволяет избежать чтения всего содержимого в память для больших ответов. Размер блока - количество байтов, которые должны быть считаны в память. Это не обязательно длина каждого возвращаемого элемента, так как может происходить декодирование.

chunk_size должен быть типа int или None. Значение None будет работать по-разному в зависимости от значения stream. stream=True будет считывать данные по мере их поступления в любом размере блоков. Если stream=False, данные возвращаются как единый блок.

Если decode_unicode равно True, содержимое будет декодировано с использованием наилучшей доступной кодировки на основе ответа.

iter_lines(chunk_size=512, decode_unicode=False, delimiter=None)[source]

Итерируется по данным ответа, по одной строке за раз. Когда stream=True установлено для запроса, это позволяет избежать чтения всего содержимого в память для больших ответов.

Примечание

Этот метод не является потокобезопасным.

json(**kwargs)[source]

Возвращает закодированное в формате JSON содержимое ответа, если таковое имеется.

Параметры

**kwargs – Дополнительные аргументы, которые json.loads принимает.

Исключения

requests.exceptions.JSONDecodeError – Если тело ответа не содержит корректного JSON.

свойство links

Возвращает разобранные ссылки из заголовка ответа, если таковые имеются.

свойство next

Возвращает PreparedRequest для следующего запроса в цепочке перенаправлений, если таковой имеется.

свойство ok

Возвращает True, если status_code меньше 400, False — в противном случае.

Это свойство проверяет, находится ли код статуса ответа между 400 и 600, чтобы определить, произошла ли ошибка клиента или сервера. Если код статуса находится между 200 и 400, возвращается True. Это не проверка, является ли код ответа 200 OK.

raise_for_status()[source]

Вызывает исключение HTTPError, если оно произошло.

raw

Представление ответа в виде объекта-подобного файлу (для расширенного использования). Использование raw требует, чтобы stream=True был установлен в запросе. Это требование не применяется для внутреннего использования в Requests.

reason

Текстовое описание кода статуса HTTP ответа, например, “Не найдено” или “ОК”.

request

Объект PreparedRequest, для которого этот объект является ответом.

status_code

Целочисленный код статуса HTTP ответа, например, 404 или 200.

свойство text

Содержание ответа в unicode.

Если Response.encoding равно None, кодировка будет угадана с помощью charset_normalizer или chardet.

Кодировка содержимого ответа определяется исключительно на основе заголовков HTTP, в точном соответствии с RFC 2616. Если вы можете использовать не-HTTP информацию, чтобы лучше угадать кодировку, вы должны установить r.encoding соответствующим образом перед доступом к этому свойству.

url

Конечный URL местоположение ответа.

Классы нижнего уровня

класс requests.PreparedRequest[source]

Полностью изменяемый PreparedRequest объект, содержащий точные байты, которые будут отправлены на сервер.

Экземпляры генерируются из объекта Request и не должны создаваться вручную; это может привести к нежелательным последствиям.

Использование:

>>> import requests
>>> req = requests.Request('GET', 'https://httpbin.org/get')
>>> r = req.prepare()
>>> r
<PreparedRequest [GET]>

>>> s = requests.Session()
>>> s.send(r)
<Response [200]>

body

Тело запроса для отправки на сервер.

deregister_hook(event, hook)

Отменить регистрацию ранее зарегистрированного обработчика. Возвращает True, если обработчик существовал, False — если нет.

headers

словарь HTTP-заголовков.

hooks

словарь обработчиков обратного вызова, для внутреннего использования.

method

HTTP-глагол для отправки на сервер.

свойство path_url

Создать URL пути для использования.

prepare(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)[source]

Подготавливает весь запрос с заданными параметрами.

prepare_auth(auth, url='')[source]

Подготавливает предоставленные данные HTTP-аутентификации.

класс requests.adapters.BaseAdapter[source]

Базовый адаптер транспорта

close()[source]

Очистка элементов, специфичных для адаптера.

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)[source]

Отправка объекта PreparedRequest. Возвращает объект Response.

Параметры

• request – Отправляемый PreparedRequest.
• stream – (необязательно) Нужно ли передавать контент запроса в виде потока.
• timeout (float или кортеж) – (необязательно) Время ожидания получения данных от сервера, как число с плавающей точкой, или кортеж (время ожидания подключения, время ожидания чтения).
• verify – (необязательно) Булево значение, определяющее, нужно ли проверять TLS-сертификат сервера, или строка, в этом случае должна указывать путь к файлу CA-сертификатов.
• cert – (необязательно) Любой предоставленный пользователем SSL-сертификат для проверки.
• proxies – (необязательно) Словарь прокси-серверов для применения к запросу.

класс requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)[source]

Встроенный адаптер HTTP для urllib3.

Предоставляет общий интерфейс для сеансов Requests для подключения к HTTP и HTTPS-ссылкам, реализуя интерфейс адаптера транспорта. Этот класс, как правило, создается классом Session в скрытом режиме.

Параметры

• pool_connections – Количество кэшируемых пулов соединений urllib3.
• pool_maxsize – Максимальное количество соединений для сохранения в пуле.
• max_retries – Максимальное количество попыток повторной отправки для каждого соединения. Обратите внимание, что это относится только к ошибкам поиска DNS, сокетов и таймаутам соединения, но не к запросам, данные которых дошли до сервера. По умолчанию Requests не повторяет запросы при ошибках соединения. Если вам нужен точный контроль над условиями повторной отправки запроса, импортируйте класс Retry из urllib3 и передайте его вместо этого.
• pool_block – Нужно ли блокировать пул соединений при отсутствии свободных соединений.

Использование:

>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)

add_headers(request, **kwargs)[source]

Добавление необходимых заголовков для подключения. Начиная с версии 2.0, по умолчанию это не выполняется, но оставляется для переопределения пользователями, которые создают подклассы HTTPAdapter.

Это не должно вызываться из пользовательского кода и доступно только для использования при создании подклассов HTTPAdapter.

Параметры

• request – PreparedRequest для добавления заголовков.
• kwargs – Аргументы ключевых слов из вызова send().

build_response(req, resp)[source]

Построение объекта Response из ответа urllib3. Это не должно вызываться из пользовательского кода и доступно только для использования при создании подклассов HTTPAdapter.

Параметры

• req – PreparedRequest, используемый для получения ответа.
• resp – Объект ответа urllib3.

Тип возвращаемого значения

requests.Response

cert_verify(conn, url, verify, cert)[source]

Проверка SSL-сертификата. Этот метод не должен вызываться из пользовательского кода и доступен только для использования при создании подклассов HTTPAdapter.

Параметры

• conn – Объект соединения urllib3, связанный с сертификатом.
• url – Запрашиваемый URL.
• verify – Булево значение, контролирующее проверку TLS-сертификата сервера, или строка, представляющая путь к файлу с набором доверенных сертификатов CA.
• cert – SSL-сертификат для проверки.

close()[source]

Удаляет все внутреннее состояние.

В настоящее время это закрывает PoolManager и любой активный ProxyManager, что закрывает все подключенные соединения.

get_connection(url, proxies=None)[source]

Возвращает объект подключения urllib3 для заданного URL. Этот метод не должен вызываться из пользовательского кода, и доступен только для использования при создании подклассов HTTPAdapter.

Параметры

• url – URL для подключения.
• proxies – (необязательно) Словарь прокси в формате Requests, используемый в этом запросе.

Тип возвращаемого значения

urllib3.ConnectionPool

init_poolmanager(connections, maxsize, block=False, **pool_kwargs)[source]

Инициализация urllib3 PoolManager.

Этот метод не должен вызываться из пользовательского кода, и доступен только для использования при создании подклассов HTTPAdapter.

Параметры

• connections – Количество кэшируемых пулов соединений urllib3.
• maxsize – Максимальное количество соединений для сохранения в пуле.
• block – Блокировать при отсутствии свободных соединений.
• pool_kwargs – Дополнительные аргументы ключевых слов, используемые для инициализации PoolManager.

proxy_headers(proxy)[source]

Возвращает словарь заголовков, которые нужно добавить к любому запросу, отправленному через прокси. Это работает с магией urllib3, чтобы гарантировать, что они отправляются прокси, а не в туннелированном запросе, если используется CONNECT.

Этот метод не должен вызываться из пользовательского кода и доступен только для использования при создании подклассов HTTPAdapter.

Параметры

proxy – URL прокси, используемого для этого запроса.

Тип возвращаемого значения

dict

proxy_manager_for(proxy, **proxy_kwargs)[source]

Возвращает urllib3 ProxyManager для данного прокси.

Этот метод не должен вызываться из пользовательского кода и доступен только для использования при создании подклассов HTTPAdapter.

Параметры

• proxy – Прокси, для которого нужно вернуть urllib3 ProxyManager.
• proxy_kwargs – Дополнительные аргументы ключевых слов для настройки ProxyManager.

Возвращаемое значение

ProxyManager

Тип возвращаемого значения

urllib3.ProxyManager

request_url(request, proxies)[source]

Получение URL для отправки конечного запроса.

Если сообщение отправляется через HTTP-прокси, необходимо использовать полный URL. В противном случае следует использовать только путь URL.

Этот метод не предназначен для вызова из пользовательского кода и доступен только для использования при наследовании от HTTPAdapter.

Параметры

• request – Отправляемый PreparedRequest.
• proxies – Словарь схем или схем и хостов для прокси-серверов URL.

Тип возвращаемого значения

str

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)[source]

Отправка объекта PreparedRequest. Возвращает объект Response.

Параметры

• request – Отправляемый PreparedRequest.
• stream – (необязательно) Потоковая передача содержимого запроса.
• timeout (float или tuple или объект Timeout urllib3) – (необязательно) Время ожидания отправки данных сервером, как число с плавающей точкой или кортеж (время ожидания подключения, время ожидания чтения).
• verify – (необязательно) Булево значение, определяющее проверку сертификата TLS сервера, или строка, представляющая путь к файлу сертификата CA.
• cert – (необязательно) Любой предоставленный пользователем SSL-сертификат для проверки.
• proxies – (необязательно) Словарь прокси для применения к запросу.

Тип возвращаемого значения

requests.Response

Аутентификация

class requests.auth.AuthBase[source]

Базовый класс, от которого наследуются все реализации аутентификации

class requests.auth.HTTPBasicAuth(username, password)[source]

Присоединяет HTTP Basic аутентификацию к заданному объекту Request.

class requests.auth.HTTPProxyAuth(username, password)[source]

Присоединяет HTTP Proxy аутентификацию к заданному объекту Request.

class requests.auth.HTTPDigestAuth(username, password)[source]

Присоединяет HTTP Digest аутентификацию к заданному объекту Request.

Кодировки

requests.utils.get_encodings_from_content(content)[source]

Возвращает кодировки из заданной строки контента.

Параметры

content – байтовая строка для извлечения кодировок.

requests.utils.get_encoding_from_headers(headers)[source]

Возвращает кодировки из заданного словаря HTTP заголовков.

Параметры

headers – словарь для извлечения кодировки.

Тип возвращаемого значения

str

requests.utils.get_unicode_from_response(r)[source]

Возвращает запрашиваемое содержимое в кодировке Unicode.

Параметры

r – Объект Response для получения кодированного содержимого.

Попытки:

1. получить charset из content-type
2. fallback и замена всех символов unicode

Тип возвращаемого значения

str

Cookies

requests.utils.dict_from_cookiejar(cj)[source]

Возвращает словарь ключ/значение из CookieJar.

Параметры

cj – Объект CookieJar для извлечения куки.

Тип возвращаемого значения

dict

requests.utils.add_dict_to_cookiejar(cj, cookie_dict)[source]

Возвращает CookieJar из словаря ключ/значение.

Параметры

• cj – CookieJar для вставки куки.
• cookie_dict – Словарь ключ/значение для вставки в CookieJar.

Тип возвращаемого значения

CookieJar

requests.cookies.cookiejar_from_dict(cookie_dict, cookiejar=None, overwrite=True)[source]

Возвращает CookieJar из словаря ключ/значение.

Параметры

• cookie_dict – Словарь ключ/значение для вставки в CookieJar.
• cookiejar – (необязательно) Cookiejar для добавления куки.
• overwrite – (необязательно) Если False, не будет заменять уже имеющиеся куки в jar новыми.

Тип возвращаемого значения

CookieJar

class requests.cookies.RequestsCookieJar(policy=None)[source]

Класс совместимости; является экземпляром cookielib.CookieJar, но предоставляет интерфейс словаря.

Это CookieJar, который мы создаём по умолчанию для запросов и сессий, не указав свой собственный, так как некоторые клиенты могут ожидать, что response.cookies и session.cookies будут поддерживать операции со словарями.

Requests не использует интерфейс словаря внутренне; он предназначен только для совместимости с внешним кодом клиента. Весь код Requests должен работать прямо из коробки с внешними экземплярами CookieJar, например LWPCookieJar и FileCookieJar.

В отличие от обычного CookieJar, этот класс можно сериализовать с помощью pickle.

Предупреждение

операции со словарем, которые обычно имеют сложность O(1), могут иметь сложность O(n).

add_cookie_header(request)

Добавляет заголовок Cookie: в запрос (объект urllib.request.Request).

Заголовок Cookie2 также добавляется, если policy.hide_cookie2 не равно True.

clear(domain=None, path=None, name=None)

Очищает некоторые cookie.

Вызов этого метода без аргументов очистит все cookie. Если задан один аргумент, будут удалены только cookie, относящиеся к этому домену. Если заданы два аргумента, будут удалены cookie, относящиеся к указанному пути внутри этого домена. Если заданы три аргумента, будет удалено cookie с указанным именем, путём и доменом.

Возбуждает исключение KeyError, если соответствующего cookie не существует.

clear_expired_cookies()

Удаляет все просроченные cookie.

Вероятно, вам не нужно вызывать этот метод: просроченные cookie никогда не отправляются обратно серверу (при условии, что вы используете DefaultCookiePolicy), этот метод вызывается CookieJar периодически, и метод .save() не сохранит просроченные cookie (если вы не укажете иначе, передав параметр ignore_expires со значением True).

clear_session_cookies()

Удаляет все сессионные cookie.

Обратите внимание, что метод .save() не сохранит сессионные cookie, если вы не укажете иначе, передав параметр ignore_discard со значением True.

copy()[source]

Возвращает копию этого RequestsCookieJar.

extract_cookies(response, request)

Извлекает cookie из ответа, в соответствии с разрешённым для запроса.

get(name, default=None, domain=None, path=None)[source]

Метод get() по аналогии со словарем, также поддерживает необязательные аргументы domain и path, чтобы разрешать конфликты имён при использовании одного cookie-хранилища для нескольких доменов.

Предупреждение

операция имеет сложность O(n), а не O(1).

get_dict(domain=None, path=None)[source]

Принимает в качестве аргументов необязательный домен и путь и возвращает обычный словарь Python с парами «имя-значение» cookie, соответствующими требованиям.

Return type

dict

get_policy()[source]

Возвращает используемый экземпляр CookiePolicy.

items()[source]

Метод items() по аналогии со словарем, возвращающий список кортежей «имя-значение» из хранилища cookie. Позволяет коду клиента вызвать dict(RequestsCookieJar) и получить обычный словарь Python с парами ключ-значение.

См. также

keys() и values().

iteritems()[source]

Метод iteritems() по аналогии со словарем, возвращающий итератор кортежей «имя-значение» из хранилища cookie.

См. также

iterkeys() и itervalues().

iterkeys()[source]

Метод iterkeys() по аналогии со словарем, возвращающий итератор имён cookie из хранилища cookie.

См. также

itervalues() и iteritems().

itervalues()[source]

Метод itervalues() по аналогии со словарем, возвращающий итератор значений cookie из хранилища cookie.

См. также

iterkeys() и iteritems().

keys()[source]

Метод keys() по аналогии со словарем, возвращающий список имён cookie из хранилища cookie.

См. также

values() и items().

list_domains()[source]

Вспомогательный метод для перечисления всех доменов в хранилище.

list_paths()[source]

Вспомогательный метод для перечисления всех путей в хранилище.

make_cookies(response, request)

Возвращает последовательность объектов Cookie, извлечённых из объекта ответа.

multiple_domains()[source]

Возвращает True, если в хранилище присутствуют несколько доменов. В противном случае возвращает False.

Тип возвращаемого значения

bool

pop(k[, d]) → v, удаляет указанный ключ и возвращает соответствующее значение.

Если ключ не найден, возвращается значение d, если оно задано, в противном случае генерируется исключение KeyError.

popitem() → (k, v), удаляет и возвращает пару (ключ, значение)

как кортеж из двух элементов; но генерирует исключение KeyError, если хранилище пусто.

set(name, value, **kwargs)[source]

Метод set(), аналогичный работе словаря, поддерживает необязательные аргументы domain и path, чтобы разрешать коллизии имён при использовании одного хранилища cookie для нескольких доменов.

set_cookie(cookie, *args, **kwargs)[source]

Устанавливает cookie без проверки, нужно ли его устанавливать.

set_cookie_if_ok(cookie, request)

Устанавливает cookie, если политика разрешает это.

setdefault(k[, d]) → D.get(k,d), также устанавливает D[k]=d, если k не в D

update(other)[source]

Обновляет это хранилище с помощью cookie из другого CookieJar или словаря.

values()[source]

Метод values(), аналогичный работе словаря, возвращает список значений cookie из хранилища.

См. также

keys() и items().

class requests.cookies.CookieConflictError[source]

Существует две cookie, соответствующие критериям, указанным в хранилище cookie. Используйте .get и .set, а также аргументы domain и path, чтобы быть более конкретным.

with_traceback()

Exception.with_traceback(tb) – задаёт self.__traceback__ на tb и возвращает self.

Поиск кодов состояния

requests.codes

псевдоним для <поискового словаря ‘status_codes’>

Объект codes определяет отображение распространённых имён HTTP-состояний на их числовые коды, к которым можно получить доступ как к атрибутам, так и как к элементам словаря.

Пример:

>>> import requests
>>> requests.codes['temporary_redirect']
307
>>> requests.codes.teapot
418
>>> requests.codes['\o/']
200

Некоторые коды имеют несколько имён, и допускаются как прописные, так и строчные версии имён. Например, codes.ok, codes.OK, и codes.okay все соответствуют коду HTTP-состояния 200.

• 100: continue
• 101: switching_protocols
• 102: processing
• 103: checkpoint
• 122: uri_too_long, request_uri_too_long
• 200: ok, okay, all_ok, all_okay, all_good, \o/, ✓
• 201: created
• 202: accepted
• 203: non_authoritative_info, non_authoritative_information
• 204: no_content
• 205: reset_content, reset
• 206: partial_content, partial
• 207: multi_status, multiple_status, multi_stati, multiple_stati
• 208: already_reported
• 226: im_used
• 300: multiple_choices
• 301: moved_permanently, moved, \o-
• 302: found
• 303: see_other, other
• 304: not_modified
• 305: use_proxy
• 306: switch_proxy
• 307: temporary_redirect, temporary_moved, temporary
• 308: permanent_redirect, resume_incomplete, resume
• 400: bad_request, bad
• 401: unauthorized
• 402: payment_required, payment
• 403: forbidden
• 404: not_found, -o-
• 405: method_not_allowed, not_allowed
• 406: not_acceptable
• 407: proxy_authentication_required, proxy_auth, proxy_authentication
• 408: request_timeout, timeout
• 409: conflict
• 410: gone
• 411: length_required
• 412: precondition_failed, precondition
• 413: request_entity_too_large
• 414: request_uri_too_large
• 415: unsupported_media_type, unsupported_media, media_type
• 416: requested_range_not_satisfiable, requested_range, range_not_satisfiable
• 417: expectation_failed
• 418: im_a_teapot, teapot, i_am_a_teapot
• 421: misdirected_request
• 422: unprocessable_entity, unprocessable
• 423: locked
• 424: failed_dependency, dependency
• 425: unordered_collection, unordered
• 426: upgrade_required, upgrade
• 428: precondition_required, precondition
• 429: too_many_requests, too_many
• 431: header_fields_too_large, fields_too_large
• 444: no_response, none
• 449: retry_with, retry
• 450: blocked_by_windows_parental_controls, parental_controls
• 451: unavailable_for_legal_reasons, legal_reasons
• 499: client_closed_request
• 500: internal_server_error, server_error, /o\, ✗
• 501: not_implemented
• 502: bad_gateway
• 503: service_unavailable, unavailable
• 504: gateway_timeout
• 505: http_version_not_supported, http_version
• 506: variant_also_negotiates
• 507: insufficient_storage
• 509: bandwidth_limit_exceeded, bandwidth
• 510: not_extended
• 511: network_authentication_required, network_auth, network_authentication

Миграция на 1.x

В этом разделе подробно описаны основные различия между версиями 0.x и 1.x, чтобы облегчить процесс обновления.

Миграция на 2.x

По сравнению с релизом 1.0, несовместимых с прошлыми версиями изменений было относительно мало, но с этим крупным релизом всё же стоит учитывать несколько моментов.

Для получения более подробной информации об изменениях в этом релизе, включая новые API, ссылки на соответствующие проблемы на GitHub и некоторые исправления ошибок, прочитайте блог Кори на эту тему.