requests — Cliente HTTP

O módulo requests fornece uma API mínima de cliente HTTP/HTTPS semelhante à biblioteca Python requests. Cada função de requisição retorna 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 retornadas por requests.request e pelos auxiliares por método.

status_code: int

Código de status HTTP inteiro retornado pelo servidor.

reason: str

Frase de motivo retornada pelo servidor (str decodificada).

encoding: str

Codificação de string usada para decodificar requests.Response.headers e requests.Response.content. O padrão é "utf-8".

headers: str

Cabeçalhos da resposta decodificados com requests.Response.encoding e retornados como uma str.

content: str

Corpo da resposta decodificado com requests.Response.encoding e retornado como uma str.

json() → dict

Analisa requests.Response.content como JSON e retorna 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 uma requisição HTTP para url e retorna um requests.Response.

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

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

  • data — corpo bruto da requisição. Se definido, Content-Length é adicionado automaticamente.

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

  • files — dicionário mapeando o nome do campo para uma tupla (filename, fileobj). Enviado como multipart/form-data.

  • headers — dicionário de cabeçalhos de requisição adicionais.

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

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

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

Envia uma requisição HTTP HEAD e retorna um Response.

HEAD é idêntico a GET, exceto que o servidor responde apenas com a linha de status e os cabeçalhos; o corpo fica vazio. Use-o para verificar se um recurso existe, inspecionar Content-Length / Content-Type sem baixar o payload, ou sondar uma 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 requisição adicionais.

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

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

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

Envia uma requisição HTTP GET e retorna um Response.

GET é o verbo padrão para recuperar uma representação do recurso identificado por url. É seguro (não causa nenhuma mudança 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 requisição adicionais (por exemplo, Authorization ou Accept).

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

Um corpo de requisição via data / json é permitido pelo request() subjacente, mas ignorado pela maioria dos servidores.

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

Envia uma requisição HTTP POST e retorna um Response.

POST submete dados a url, normalmente criando um novo recurso subordinado, acionando 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 bruto da requisição (do tipo bytes). Envia um cabeçalho Content-Length automaticamente.

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

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

  • headers (kwarg) – dicionário de cabeçalhos de requisição adicionais.

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

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

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

Envia uma requisição HTTP PUT e retorna um Response.

PUT substitui o recurso em url pela representação fornecida, criando-o caso não exista. É 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 bruto de substituição (do tipo 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 requisição adicionais.

  • auth (kwarg) – tupla (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 uma requisição HTTP PATCH e retorna um Response.

PATCH aplica uma modificação parcial ao recurso em url – apenas os campos contidos no corpo da requisição são alterados. Diferentemente de PUT, não é obrigado a ser idempotente (embora muitas APIs o tornem assim).

Argumentos:

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

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

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

  • headers (kwarg) – dicionário de cabeçalhos de requisição adicionais.

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

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

Envia uma requisição HTTP DELETE e retorna um Response.

DELETE solicita a remoção do recurso em url. É idempotente: excluir um recurso já excluído não é um erro (o servidor normalmente retorna um 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 requisição adicionais.

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

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