requests — HTTP-клиент

Модуль requests предоставляет минимальный API HTTP/HTTPS-клиента, аналогичный библиотеке Python requests. Каждая функция запроса возвращает объект requests.Response.

Пример:

import requests

# GET a JSON resource.
r = requests.get("https://httpbin.org/get")
print(r.status_code, r.reason)
print(r.json())

# POST JSON.
r = requests.post(
    "https://httpbin.org/post",
    json={"id": 1, "value": 42},
    headers={"X-Source": "openmv"},
)
print(r.json())

Класс Response

class requests.Response(code: int, reason: str, headers: bytes = None, content: bytes = None)

Представляет HTTP-ответ. Экземпляры возвращаются requests.request и вспомогательными функциями для отдельных методов.

status_code: int

Целочисленный код состояния HTTP, возвращённый сервером.

reason: str

Фраза причины, возвращённая сервером (декодированная как str).

encoding: str

Строковая кодировка, используемая для декодирования requests.Response.headers и requests.Response.content. По умолчанию "utf-8".

headers: str

Заголовки ответа, декодированные с помощью requests.Response.encoding и возвращаемые как str.

content: str

Тело ответа, декодированное с помощью requests.Response.encoding и возвращаемое как str.

json() → dict

Разбирает requests.Response.content как JSON и возвращает полученный объект.

Функции

requests.request(method: str, url: str, data: bytes | None = None, json: Any | None = None, files: dict | None = None, headers: dict = {}, auth: tuple | None = None, stream: Any | None = None) → Response

Отправляет HTTP-запрос на url и возвращает requests.Response.

  • method — HTTP-метод в виде str (например, "GET", "POST").

  • url — целевой URL. Должен начинаться с http:// или https://.

  • data — необработанное тело запроса. Если задано, Content-Length добавляется автоматически.

  • json — объект, сериализуемый в JSON и отправляемый в качестве тела. Устанавливает Content-Type: application/json.

  • files — словарь, сопоставляющий имя поля с кортежем (filename, fileobj). Отправляется как multipart/form-data.

  • headers — словарь дополнительных заголовков запроса.

  • auth — кортеж (username, password) для базовой HTTP-аутентификации.

  • stream — принимается для совместимости API; не используется.

requests.head(url: str, **kw: Any) → Response

Отправляет HTTP-запрос HEAD и возвращает Response.

HEAD идентичен GET, за исключением того, что сервер отвечает только строкой состояния и заголовками; тело пустое. Используйте его, чтобы проверить, существует ли ресурс, изучить Content-Length / Content-Type без загрузки полезной нагрузки или предварительно опросить URL перед более тяжёлым GET.

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • headers (kwarg) – словарь дополнительных заголовков запроса.

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

data / json / files / stream из request() принимаются для полноты, но редко имеют смысл для HEAD.

requests.get(url: str, **kw: Any) → Response

Отправляет HTTP-запрос GET и возвращает Response.

GET — стандартный метод для получения представления ресурса, идентифицируемого url. Он безопасен (не вызывает изменений состояния на стороне сервера) и идемпотентен.

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • headers (kwarg) – словарь дополнительных заголовков запроса (например, Authorization или Accept).

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

Тело запроса через data / json допускается базовой функцией request(), но игнорируется большинством серверов.

requests.post(url: str, **kw: Any) → Response

Отправляет HTTP-запрос POST и возвращает Response.

POST отправляет данные на url, обычно создавая новый подчинённый ресурс, инициируя отправку формы или вызывая действие. Он не является ни безопасным, ни идемпотентным: повторные вызовы могут создавать дублирующиеся ресурсы.

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • data (kwarg) – необработанное тело запроса (bytes-подобное). Автоматически отправляет заголовок Content-Length.

  • json (kwarg) – объект, сериализуемый в JSON и отправляемый в качестве тела. Устанавливает Content-Type: application/json.

  • files (kwarg) – словарь, сопоставляющий имя поля с (filename, fileobj). Отправляется как multipart/form-data.

  • headers (kwarg) – словарь дополнительных заголовков запроса.

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

Передавайте не более одного из data / json / files.

requests.put(url: str, **kw: Any) → Response

Отправляет HTTP-запрос PUT и возвращает Response.

PUT заменяет ресурс по адресу url предоставленным представлением, создавая его, если он не существует. Он идемпотентен: повторение идентичного PUT даёт одно и то же конечное состояние.

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • data (kwarg) – необработанное тело замены (bytes-подобное).

  • json (kwarg) – объект, сериализуемый в JSON и отправляемый в качестве тела замены. Устанавливает Content-Type: application/json.

  • headers (kwarg) – словарь дополнительных заголовков запроса.

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

Передайте либо data, либо json для передачи нового представления.

requests.patch(url: str, **kw: Any) → Response

Отправляет HTTP-запрос PATCH и возвращает Response.

PATCH применяет частичное изменение к ресурсу по адресу url – меняются только поля, содержащиеся в теле запроса. В отличие от PUT, он не обязан быть идемпотентным (хотя многие API делают его таковым).

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • data (kwarg) – необработанное тело дельты (bytes-подобное). Формат зависит от сервера (например, JSON Patch, JSON Merge Patch).

  • json (kwarg) – объект дельты, сериализуемый в JSON. Устанавливает Content-Type: application/json.

  • headers (kwarg) – словарь дополнительных заголовков запроса.

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

requests.delete(url: str, **kw: Any) → Response

Отправляет HTTP-запрос DELETE и возвращает Response.

DELETE запрашивает удаление ресурса по адресу url. Он идемпотентен: удаление уже удалённого ресурса не является ошибкой (сервер обычно возвращает 404, но конечное состояние то же самое).

Аргументы:

  • url – целевой URL; должен начинаться с http:// или https://.

  • headers (kwarg) – словарь дополнительных заголовков запроса.

  • auth (kwarg) – кортеж (username, password) для базовой HTTP-аутентификации.

Тело через data / json допускается базовой функцией request(), но редко используется с DELETE.