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.
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,POSTposílá nová data,PUTaPATCHmění,DELETEmaž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áš.
GETho 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ód | Význam | Co s tím |
|---|---|---|
200 | v pořádku | zpracuj data |
201 | vytvořeno | hotovo, nový záznam existuje |
301, 302 | přesunuto jinam | requests přejde samo |
400 | špatný požadavek | oprav, co posíláš |
401, 403 | nejsi přihlášený, nemáš právo | zkontroluj klíč a oprávnění |
404 | nenalezeno | zkontroluj adresu |
429 | moc požadavků | zpomal |
500, 502, 503 | chyba na straně serveru | zkus to později |
Na svém počítači si knihovnu nainstaluješ jedním příkazem.
python -m pip install requestsSkutečné volání pak vypadá takhle:
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)
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)
application/json
b'{"kava": "espresso", "kusu": 2}'
application/x-www-form-urlencoded
kava=espresso&kusu=2Př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
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"])
<Response [200]>
200 True
application/json
b'{"mesto": '
{"mesto": "Brno"
pondělí 7.5status_codeje stavový kód.okjeTruepro všechno pod 400.headersje slovník, který nerozlišuje velikost písmen.contentjsou surové bajty, vhodné pro obrázky a soubory.textje 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)
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)
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"])
tělo není JSON, začíná: <html><body> typ obsahu: text/html
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"]
Co udělá requests.get(url), když server vrátí 404?
Server odpověděl, takže z pohledu knihovny komunikace proběhla. O tom, jestli je 404 chyba, rozhoduješ ty.
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))
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:
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())
>> 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)
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.
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)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
Který požadavek můžeš po výpadku spojení bez obav automaticky zopakovat?
GET nemá vedlejší účinky. U POST nevíš, jestli první pokus nedorazil. Bezpečné opakování tam vyžaduje podporu serveru, typicky takzvaný idempotency key.
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])
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í.
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.