0 dní v řadě · 0 bodů

Užitečné knihovny · 28 min

requests: data z internetu

Jak funguje HTTP, jak sestavit požadavek, přečíst odpověď, přežít výpadek sítě a otestovat to všechno bez připojení k internetu.

Hloubka
Úkoly
Lidsky řečeno

Internet funguje jako výdejní okénko. Přijdeš, řekneš, co chceš, a dostaneš balíček s lístkem, na kterém stojí, jak to dopadlo. Někdy je to „tady to máte“, jindy „to nevedeme“ nebo „máme zavřeno“. Knihovna requests za tebe chodí k okénku a ty řešíš jen to, co objednat a co s balíčkem udělat.

Rozhovor s webem

Počítače na webu si povídají jazykem HTTP. Tvůj program pošle požadavek a server vrátí odpověď. Celé to je obyčejný text.

http
GET /v1/pocasi?mesto=Brno HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{"mesto": "Brno", "teplota": 7.5}

Požadavek říká čtyři věci:

  • Metoda: co chceš udělat. GET čte, POST posílá nová data, PUT a PATCH mění, DELETE maže.
  • Adresa (URL): kde to je. Za otazníkem jsou parametry.
  • Hlavičky: doplňující údaje, třeba jaký formát přijmeš nebo kdo jsi.
  • Tělo: data, která posíláš. GET ho obvykle nemá.

Odpověď má stavový kód, hlavičky a tělo. Tělo je často ve formátu JSON, který už znáš z lekce JSON a CSV. Webové službě, která takhle vrací data pro programy, se říká API.

KódVýznamCo s tím
200v pořádkuzpracuj data
201vytvořenohotovo, nový záznam existuje
301, 302přesunuto jinamrequests přejde samo
400špatný požadavekoprav, co posíláš
401, 403nejsi přihlášený, nemáš právozkontroluj klíč a oprávnění
404nenalezenozkontroluj adresu
429moc požadavkůzpomal
500, 502, 503chyba na straně serveruzkus to později

Na svém počítači si knihovnu nainstaluješ jedním příkazem.

bash
python -m pip install requests

Skutečné volání pak vypadá takhle:

python
import requests

odpoved = requests.get(
    "https://api.github.com/repos/python/cpython",
    timeout=10,
)
odpoved.raise_for_status()

data = odpoved.json()
print(data["full_name"], data["stargazers_count"])

Ukázky v kurzu běží v prohlížeči a na internet nechodí. To je výhoda: nezávisí na cizím serveru a vždy dají stejný výsledek. Požadavky budeme skládat bez odeslání a odpovědi si vyrobíme sami. Přesně tak se síťový kód testuje i v praxi.

Sestav požadavek

requests.get(...) dělá dvě věci: požadavek připraví a odešle. Přípravu jde spustit samostatně přes Request(...).prepare() a prohlédnout si, co by odešlo.

import requests

pozadavek = requests.Request(
    "GET",
    "https://api.example.com/hledej",
    params={"q": "káva a čaj", "strana": 2, "stitek": ["bio", "fair"], "filtr": None},
    headers={"Accept": "application/json"},
).prepare()

print(pozadavek.method)
print(pozadavek.url)
print(pozadavek.headers["Accept"])
print(pozadavek.body)
Výstup
GET
https://api.example.com/hledej?q=k%C3%A1va+a+%C4%8Daj&strana=2&stitek=bio&stitek=fair
application/json
None

Nikdy neskládej adresu ručně přes f-string. params zařídí správné kódování diakritiky a mezer, seznam rozepíše na opakovaný parametr a hodnotu None vynechá.

Když data posíláš, záleží na tom, jak je zabalíš. Moderní API chtějí většinou JSON, klasické webové formuláře data.

import requests

url = "https://api.example.com/objednavky"

jako_json = requests.Request("POST", url, json={"kava": "espresso", "kusu": 2}).prepare()
print(jako_json.headers["Content-Type"])
print(jako_json.body)

jako_formular = requests.Request("POST", url, data={"kava": "espresso", "kusu": 2}).prepare()
print(jako_formular.headers["Content-Type"])
print(jako_formular.body)
Výstup
application/json
b'{"kava": "espresso", "kusu": 2}'
application/x-www-form-urlencoded
kava=espresso&kusu=2
Úkol

Připrav hledání

Napiš funkci priprav_hledani(dotaz, token, strana=1), která vrátí připravený požadavek GET na https://api.example.com/search. Parametry adresy jsou q a page. Hlavička Authorization má hodnotu Bearer a za ní token.

import requests

def priprav_hledani(dotaz, token, strana=1):
    return None
Výstup

Přečti odpověď

Odpověď je objekt Response. Tady si ji vyrobíme ručně, aby ukázka nepotřebovala síť. Podtržítko u _content značí vnitřní atribut. V běžném programu ho nastavuje sama knihovna a ty jen čteš.

import requests

odpoved = requests.Response()
odpoved.status_code = 200
odpoved.url = "https://api.example.com/v1/pocasi?mesto=Brno"
odpoved.encoding = "utf-8"
odpoved.headers["Content-Type"] = "application/json"
odpoved._content = '{"mesto": "Brno", "dny": [{"den": "pondělí", "teplota": 7.5}]}'.encode("utf-8")

print(odpoved)
print(odpoved.status_code, odpoved.ok)
print(odpoved.headers["content-type"])
print(odpoved.content[:10])
print(odpoved.text[:16])

data = odpoved.json()
print(data["dny"][0]["den"], data["dny"][0]["teplota"])
Výstup
<Response [200]>
200 True
application/json
b'{"mesto": '
{"mesto": "Brno"
pondělí 7.5
  • status_code je stavový kód. ok je True pro všechno pod 400.
  • headers je slovník, který nerozlišuje velikost písmen.
  • content jsou surové bajty, vhodné pro obrázky a soubory.
  • text je tělo převedené na text.
  • json() tělo rovnou převede na slovníky a seznamy.

Chyba 404 není v requests výjimka. Program klidně běží dál s prázdnýma rukama. Chceš-li, aby se chyba projevila, zavolej raise_for_status().

import requests

odpoved = requests.Response()
odpoved.status_code = 404
odpoved.reason = "Not Found"
odpoved.url = "https://api.example.com/v1/mesta/atlantida"

print(odpoved.ok)
print(bool(odpoved))

try:
    odpoved.raise_for_status()
except requests.HTTPError as chyba:
    print("chyba:", chyba)
    print("kód:", chyba.response.status_code)
Výstup
False
False
chyba: 404 Client Error: Not Found for url: https://api.example.com/v1/mesta/atlantida
kód: 404
import requests
from requests.utils import get_encoding_from_headers

odpoved = requests.Response()
odpoved.status_code = 200
odpoved.headers["Content-Type"] = "text/html"
odpoved._content = "Malá káva".encode("utf-8")
odpoved.encoding = get_encoding_from_headers(odpoved.headers)

print(odpoved.encoding)
print(odpoved.text)

odpoved.encoding = "utf-8"
print(odpoved.text)
Výstup
ISO-8859-1
Malá káva
Malá káva

Ani kód 200 nezaručuje, že dostaneš JSON. Proxy nebo přihlašovací brána ráda vrátí HTML stránku. json() pak vyhodí výjimku.

import requests

odpoved = requests.Response()
odpoved.status_code = 200
odpoved.encoding = "utf-8"
odpoved.headers["Content-Type"] = "text/html"
odpoved._content = b"<html><body>Prihlaste se</body></html>"

try:
    odpoved.json()
except requests.JSONDecodeError:
    print("tělo není JSON, začíná:", odpoved.text[:12])
    print("typ obsahu:", odpoved.headers["Content-Type"])
Výstup
tělo není JSON, začíná: <html><body>
typ obsahu: text/html
Úkol

Opatrné čtení

Napiš funkci precti_teplotu(odpoved), která z JSON odpovědi ve tvaru {"current": {"temp": 7.5}} vrátí teplotu. Pokud odpověď není v pořádku (ok je False), tělo není JSON nebo v něm hodnota chybí, vrať None.

def precti_teplotu(odpoved):
    return odpoved.json()["current"]["temp"]
Výstup
Kvíz

Co udělá requests.get(url), když server vrátí 404?

Když se síť pokazí

Síť selhává běžně. Server neodpovídá, Wi-Fi vypadne, DNS nefunguje. Všechny tyhle chyby mají společného předka RequestException.

import requests

for trida in (requests.ConnectTimeout, requests.ReadTimeout, requests.HTTPError):
    print(trida.__name__, "->", [t.__name__ for t in trida.__mro__[1:-3]])

print(issubclass(requests.ConnectTimeout, requests.ConnectionError))
print(issubclass(requests.ReadTimeout, requests.ConnectionError))
print(issubclass(requests.RequestException, OSError))
Výstup
ConnectTimeout -> ['ConnectionError', 'Timeout', 'RequestException', 'OSError']
ReadTimeout -> ['Timeout', 'RequestException', 'OSError']
HTTPError -> ['RequestException', 'OSError']
True
False
True

Běžná kostra pro práci se sítí vypadá takhle:

python
import requests

try:
    odpoved = requests.get(url, timeout=(3.05, 10))
    odpoved.raise_for_status()
    data = odpoved.json()
except requests.Timeout:
    print("Server neodpověděl včas.")
except requests.ConnectionError:
    print("Nepodařilo se spojit.")
except requests.HTTPError as chyba:
    print("Server vrátil chybu:", chyba.response.status_code)
except requests.JSONDecodeError:
    print("Odpověď není platný JSON.")

Session a cvičný server

Když voláš stejný server opakovaně, použij Session. Pamatuje si hlavičky a cookies a znovu využívá otevřené spojení, takže je rychlejší.

Session má ještě jednu šikovnou vlastnost. Odesílání dělá vyměnitelný díl zvaný adaptér. Když místo něj zapojíš vlastní, který odpovědi jen vymýšlí, dostaneš cvičný server bez sítě. Celý zbytek knihovny běží doopravdy.

import json
import requests
from requests.adapters import BaseAdapter

class CvicnyServer(BaseAdapter):
    def send(self, request, **volby):
        print(">>", request.method, request.url)
        print("   klient:", request.headers["X-Klient"], "| timeout:", volby["timeout"])
        odpoved = requests.Response()
        odpoved.status_code = 200
        odpoved.url = request.url
        odpoved.request = request
        odpoved.encoding = "utf-8"
        odpoved._content = json.dumps({"ok": True}).encode("utf-8")
        return odpoved

    def close(self):
        pass

with requests.Session() as session:
    session.mount("https://", CvicnyServer())
    session.headers["X-Klient"] = "sudo_uceni"

    print(session.get("https://api.example.com/a", params={"id": 1}, timeout=5).json())
    print(session.get("https://api.example.com/b").json())
Výstup
>> GET https://api.example.com/a?id=1
   klient: sudo_uceni | timeout: 5
{'ok': True}
>> GET https://api.example.com/b
   klient: sudo_uceni | timeout: None
{'ok': True}

Hlavička nastavená na Session odešla s oběma požadavky. A druhý řádek ukazuje skutečnost, na kterou se snadno zapomene: bez parametru je timeout opravdu None.

Stejný trik poslouží k vyzkoušení opakování. Server dvakrát spadne a napotřetí odpoví. Mezi pokusy se čeká stále déle, aby se přetížený server stihl vzpamatovat. Takovému čekání se říká exponenciální backoff.

import requests
from requests.adapters import BaseAdapter

class NespolehlivyServer(BaseAdapter):
    def __init__(self, vypadku):
        super().__init__()
        self.vypadku = vypadku

    def send(self, request, **volby):
        if self.vypadku > 0:
            self.vypadku -= 1
            raise requests.ConnectionError("spojení spadlo")
        odpoved = requests.Response()
        odpoved.status_code = 200
        odpoved._content = b"hotovo"
        odpoved.encoding = "utf-8"
        return odpoved

    def close(self):
        pass

def stahni_s_opakovanim(session, url, pokusu=4):
    for pokus in range(pokusu):
        try:
            return session.get(url, timeout=5)
        except (requests.ConnectionError, requests.Timeout) as chyba:
            if pokus == pokusu - 1:
                raise
            pauza = 0.5 * 2 ** pokus
            print(f"pokus {pokus + 1}: {chyba}, čekám {pauza} s")
            # time.sleep(pauza)

session = requests.Session()
session.mount("https://", NespolehlivyServer(vypadku=2))
print(stahni_s_opakovanim(session, "https://api.example.com/data").text)
Výstup
pokus 1: spojení spadlo, čekám 0.5 s
pokus 2: spojení spadlo, čekám 1.0 s
hotovo

V reálném programu nemusíš smyčku psát. Opakování umí adaptér sám a stejně se dá stáhnout i velký soubor bez načtení do paměti.

python
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

opakovani = Retry(
    total=3,
    backoff_factor=0.5,
    status_forcelist=[429, 502, 503, 504],
    allowed_methods=["GET", "HEAD"],
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=opakovani))
session.headers["User-Agent"] = "muj-nastroj/1.0"

with session.get(url, stream=True, timeout=(3.05, 30)) as odpoved:
    odpoved.raise_for_status()
    with open("data.zip", "wb") as soubor:
        for kus in odpoved.iter_content(chunk_size=65536):
            soubor.write(kus)
Úkol

Stáhni všechny stránky

API vrací data po stránkách ve tvaru {"items": [...], "next": "adresa další stránky"}. Na poslední stránce je next rovno null, v Pythonu None. Napiš funkci stahni_vse(session, url), která projde všechny stránky a vrátí jeden seznam položek. U každého volání nastav timeout a při chybovém kódu nech vyletět výjimku přes raise_for_status().

def stahni_vse(session, url):
    polozky = []
    # doplň
    return polozky
Výstup
Kvíz

Který požadavek můžeš po výpadku spojení bez obav automaticky zopakovat?

Přesměrování a tajné klíče

Server může klienta poslat na jinou adresu. requests přesměrování sleduje samo a chová se při tom způsobem, který občas překvapí. Tady POST míří na starou adresu a server odpoví kódem 302.

import requests
from requests.adapters import BaseAdapter

class Presmerovani(BaseAdapter):
    def send(self, request, **volby):
        print(request.method, request.url,
              "| tělo:", request.body,
              "| Authorization:", request.headers.get("Authorization"))
        odpoved = requests.Response()
        odpoved.url = request.url
        odpoved.request = request
        odpoved._content = b""
        odpoved._content_consumed = True
        if request.url.endswith("/stara"):
            odpoved.status_code = 302
            odpoved.headers["Location"] = "https://cdn.example.net/nova"
        else:
            odpoved.status_code = 200
        return odpoved

    def close(self):
        pass

session = requests.Session()
session.trust_env = False
session.mount("https://", Presmerovani())

vysledek = session.post(
    "https://api.example.com/stara",
    json={"kusu": 1},
    headers={"Authorization": "Bearer tajne"},
    timeout=5,
)
print(vysledek.status_code, [r.status_code for r in vysledek.history])
Výstup
POST https://api.example.com/stara | tělo: b'{"kusu": 1}' | Authorization: Bearer tajne
GET https://cdn.example.net/nova | tělo: None | Authorization: None
200 [302]

Staly se dvě věci. POST se změnil na GET a tělo zmizelo, takže data serveru vůbec nedorazila. Hlavička Authorization se na cizí server neposlala, což je správně: klíč nemá odcházet na jinou doménu.

Klíče k API do kódu nepatří. Skončily by v Gitu a odtud je dostane každý. Načti je z proměnné prostředí.

python
import os
import requests

klic = os.environ["POCASI_API_KEY"]
odpoved = requests.get(
    "https://api.example.com/v1/pocasi",
    params={"mesto": "Brno"},
    headers={"Authorization": f"Bearer {klic}"},
    timeout=10,
)

Klíč patří do hlavičky, ne do adresy. Adresy se ukládají do logů serverů i historie a výjimka HTTPError celou adresu vypíše. A buď slušný host: dodržuj limity z dokumentace, při kódu 429 respektuj hlavičku Retry-After a posílej srozumitelný User-Agent.

Pod kapotou · časové limity, přesměrování a past v prostředí

Timeout není deadline. Hodnota čtení je maximální prodleva mezi dvěma přijatými kusy dat. Server, který posílá bajt za devět vteřin, limit 10 s nikdy neporuší. Celkový limit musíš hlídat sám, například přes stream=True a kontrolu času. DNS je další slepé místo: getaddrinfo běží mimo socket timeout, takže se může zdržet déle, než čekáš.

Přesměrování. U 301, 302 a 303 requests změní POST na GET, což kopíruje chování prohlížečů. Metodu a tělo zachovají jen 307 a 308. Authorization se při změně hostitele maže v should_strip_auth; výjimkou je přechod z http na https na výchozích portech. Vlastní hlavičky jako X-Api-Key se ale nemažou a uniknou na cílový host. U citlivých volání nastav allow_redirects=False. Pozor i na Basic autentizaci: auth=("anna", "heslo") je jen Base64, tedy kódování, ne šifra.

trust_env. Session ve výchozím stavu čte prostředí. HTTP_PROXY přesměruje provoz, .netrc přepíše hlavičku Authorization nastavenou přes headers= a REQUESTS_CA_BUNDLE má přednost před session.verify, pokud verify nepředáš přímo do volání. To jsou klasické „lokálně to funguje“ chyby. trust_env = False je vypne všechny.

Pool. HTTPAdapter drží pool_connections=10 hostitelů a pool_maxsize=10 spojení na hostitele. Při větší souběžnosti se spojení navíc vytvoří a pak zahodí s varováním Connection pool is full. Nastav pool_maxsize podle počtu vláken. S vlákny ale opatrně: dokumentace thread-safety Session výslovně neslibuje, bezpečnější je jedna session na vlákno.

Backoff v praxi. Bez náhodného rozptylu (jitter) se klienti po výpadku trefí do stejného okamžiku a server znovu položí. urllib3.Retry má od verze 2 backoff_jitter. Retry standardně neopakuje POST, a po vyčerpání pokusů u status_forcelist vyhodí RetryError, pokud nenastavíš raise_on_status=False.

Kdy jinam. requests je synchronní a neumí HTTP/2. Pro asyncio nebo HTTP/2 je tu httpx s podobným API. Na testy jsou hotové responses a requests-mock, které stojí na stejném principu výměny adaptéru jako naše ukázky.