requests — cliente HTTP

O módulo requests fornece uma API de cliente HTTP/HTTPS mínima semelhante à biblioteca Python requests. Cada função de pedido devolve um objeto requests.Response.

Exemplo:

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())

Classe Response

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

Representa uma resposta HTTP. As instâncias são devolvidas por requests.request e pelos auxiliares por método.

status_code: int

Código de estado HTTP inteiro devolvido pelo servidor.

reason: str

Frase de razão devolvida pelo servidor (str descodificado).

encoding: str

Codificação de string usada para descodificar requests.Response.headers e requests.Response.content. Predefinição: "utf-8".

headers: str

Cabeçalhos de resposta descodificados com requests.Response.encoding e devolvidos como str.

content: str

Corpo da resposta descodificado com requests.Response.encoding e devolvido como str.

json() → dict

Analisa requests.Response.content como JSON e devolve o objeto resultante.

Funções

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

Envia um pedido HTTP para url e devolve um requests.Response.

  • method — método HTTP como str (por exemplo, "GET", "POST").

  • url — URL de destino. Deve começar com http:// ou https://.

  • data — Corpo do pedido em bruto. Se definido, Content-Length é adicionado automaticamente.

  • json — Objeto serializado em JSON e enviado como corpo. Define Content-Type: application/json.

  • files — Dicionário que mapeia o nome do campo para um tuplo (filename, fileobj). Enviado como multipart/form-data.

  • headers — Dicionário de cabeçalhos de pedido adicionais.

  • auth — Tuplo (username, password) para autenticação HTTP Basic.

  • stream — Aceite para compatibilidade de API; não utilizado.

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

Envia um pedido HTTP HEAD e devolve um Response.

HEAD é idêntico a GET exceto que o servidor responde apenas com a linha de estado e os cabeçalhos; o corpo está vazio. Use-o para verificar se um recurso existe, inspecionar Content-Length / Content-Type sem descarregar o payload, ou sondar um URL antes de emitir um GET mais pesado.

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais.

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

data / json / files / stream de request() são aceites por integridade mas raramente fazem sentido para HEAD.

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

Envia um pedido HTTP GET e devolve um Response.

GET é o verbo padrão para obter uma representação do recurso identificado por url. É seguro (não causa alteração de estado no servidor) e idempotente.

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais (por exemplo, Authorization ou Accept).

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

Um corpo de pedido via data / json é permitido pelo request() subjacente mas ignorado pela maioria dos servidores.

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

Envia um pedido HTTP POST e devolve um Response.

POST submete dados para url, tipicamente criando um novo recurso subordinado, desencadeando o envio de um formulário, ou invocando uma ação. Não é seguro nem idempotente: chamadas repetidas podem criar recursos duplicados.

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • data (kwarg) – corpo do pedido em bruto (semelhante a bytes). Envia automaticamente um cabeçalho Content-Length.

  • json (kwarg) – objeto serializado em JSON e enviado como corpo. Define Content-Type: application/json.

  • files (kwarg) – dicionário que mapeia um nome de campo para (filename, fileobj). Enviado como multipart/form-data.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais.

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

Passe no máximo um de data / json / files.

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

Envia um pedido HTTP PUT e devolve um Response.

PUT substitui o recurso em url pela representação fornecida, criando-o se não existir. É idempotente: repetir um PUT idêntico produz o mesmo estado final.

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • data (kwarg) – corpo de substituição em bruto (semelhante a bytes).

  • json (kwarg) – objeto serializado em JSON e enviado como corpo de substituição. Define Content-Type: application/json.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais.

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

Passe data ou json para transportar a nova representação.

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

Envia um pedido HTTP PATCH e devolve um Response.

PATCH aplica uma modificação parcial ao recurso em url – apenas os campos contidos no corpo do pedido são alterados. Ao contrário de PUT, não é obrigatoriamente idempotente (embora muitas APIs o tornem assim).

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • data (kwarg) – corpo delta em bruto (semelhante a bytes). O formato depende do servidor (por exemplo, JSON Patch, JSON Merge Patch).

  • json (kwarg) – objeto delta serializado em JSON. Define Content-Type: application/json.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais.

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

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

Envia um pedido HTTP DELETE e devolve um Response.

DELETE solicita a remoção do recurso em url. É idempotente: eliminar um recurso já eliminado não é um erro (o servidor normalmente devolve 404, mas o estado final é o mesmo).

Argumentos:

  • url – URL de destino; deve começar com http:// ou https://.

  • headers (kwarg) – dicionário de cabeçalhos de pedido adicionais.

  • auth (kwarg) – tuplo (username, password) para autenticação HTTP Basic.

Um corpo via data / json é permitido pelo request() subjacente mas raramente usado com DELETE.