requests — Klient HTTP

Moduł requests udostępnia minimalne API klienta HTTP/HTTPS podobne do biblioteki Python requests. Każda funkcja żądania zwraca obiekt requests.Response.

Przykład:

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

Klasa Response

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

Reprezentuje odpowiedź HTTP. Instancje są zwracane przez requests.request oraz pomocnicze funkcje poszczególnych metod.

status_code: int

Całkowita liczba kodu statusu HTTP zwrócona przez serwer.

reason: str

Fraza opisu zwrócona przez serwer (zdekodowany str).

encoding: str

Kodowanie znaków używane do dekodowania requests.Response.headers i requests.Response.content. Domyślnie "utf-8".

headers: str

Nagłówki odpowiedzi zdekodowane przy użyciu requests.Response.encoding i zwrócone jako str.

content: str

Treść odpowiedzi zdekodowana przy użyciu requests.Response.encoding i zwrócona jako str.

json() → dict

Parsuje requests.Response.content jako JSON i zwraca powstały obiekt.

Funkcje

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

Wysyła żądanie HTTP do url i zwraca requests.Response.

  • method — metoda HTTP jako str (np. "GET", "POST").

  • url — docelowy adres URL. Musi zaczynać się od http:// lub https://.

  • data — surowa treść żądania. Jeśli ustawione, Content-Length jest dodawany automatycznie.

  • json — obiekt serializowany do JSON i wysyłany jako treść. Ustawia Content-Type: application/json.

  • files — słownik mapujący nazwę pola na krotkę (filename, fileobj). Wysyłane jako multipart/form-data.

  • headers — słownik dodatkowych nagłówków żądania.

  • auth — krotka (username, password) dla uwierzytelniania HTTP Basic.

  • stream — akceptowane dla zgodności API; nieużywane.

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

Wysyła żądanie HTTP HEAD i zwraca Response.

HEAD jest identyczne z GET, z tą różnicą, że serwer odpowiada tylko linią statusu i nagłówkami; treść jest pusta. Użyj go, aby sprawdzić, czy zasób istnieje, sprawdzić Content-Length / Content-Type bez pobierania ładunku lub przetestować adres URL przed wykonaniem cięższego GET.

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania.

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

data / json / files / stream z request() są akceptowane dla kompletności, ale rzadko mają sens w przypadku HEAD.

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

Wysyła żądanie HTTP GET i zwraca Response.

GET to standardowy czasownik służący do pobierania reprezentacji zasobu wskazanego przez url. Jest bezpieczny (nie powoduje zmiany stanu po stronie serwera) i idempotentny.

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania (na przykład Authorization lub Accept).

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

Treść żądania przez data / json jest dozwolona przez leżące u podstaw request(), ale ignorowana przez większość serwerów.

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

Wysyła żądanie HTTP POST i zwraca Response.

POST przesyła dane do url, zazwyczaj tworząc nowy podrzędny zasób, wyzwalając przesłanie formularza lub wywołując akcję. Nie jest ani bezpieczny, ani idempotentny: powtarzane wywołania mogą tworzyć zduplikowane zasoby.

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • data (kwarg) – surowa treść żądania (typu bytes). Automatycznie wysyła nagłówek Content-Length.

  • json (kwarg) – obiekt serializowany do JSON i wysyłany jako treść. Ustawia Content-Type: application/json.

  • files (kwarg) – słownik mapujący nazwę pola na (filename, fileobj). Wysyłane jako multipart/form-data.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania.

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

Przekaż co najwyżej jedno z data / json / files.

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

Wysyła żądanie HTTP PUT i zwraca Response.

PUT zastępuje zasób pod url dostarczoną reprezentacją, tworząc go, jeśli nie istnieje. Jest idempotentny: powtórzenie identycznego PUT daje ten sam stan końcowy.

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • data (kwarg) – surowa treść zastępująca (typu bytes).

  • json (kwarg) – obiekt serializowany do JSON i wysyłany jako treść zastępująca. Ustawia Content-Type: application/json.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania.

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

Przekaż data lub json, aby przenieść nową reprezentację.

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

Wysyła żądanie HTTP PATCH i zwraca Response.

PATCH stosuje częściową modyfikację zasobu pod url – zmieniają się tylko pola zawarte w treści żądania. W przeciwieństwie do PUT nie musi być idempotentny (choć wiele API czyni go takim).

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • data (kwarg) – surowa treść różnicowa (typu bytes). Format zależy od serwera (np. JSON Patch, JSON Merge Patch).

  • json (kwarg) – obiekt różnicowy serializowany do JSON. Ustawia Content-Type: application/json.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania.

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

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

Wysyła żądanie HTTP DELETE i zwraca Response.

DELETE żąda usunięcia zasobu pod url. Jest idempotentny: usunięcie już usuniętego zasobu nie jest błędem (serwer zazwyczaj zwraca 404, ale stan końcowy jest taki sam).

Argumenty:

  • url – docelowy adres URL; musi zaczynać się od http:// lub https://.

  • headers (kwarg) – słownik dodatkowych nagłówków żądania.

  • auth (kwarg) – krotka (username, password) dla uwierzytelniania HTTP Basic.

Treść przez data / json jest dozwolona przez leżące u podstaw request(), ale rzadko używana z DELETE.