TopolearnCalling a web API or downloading a page is one line with Requests, and every later lesson builds on it.
Requests is a third-party package: install it with pip install requests (inside a virtual environment) and import it with import requests.
The module has one function per HTTP method: requests.get, post, put, patch, delete, head and options. Each takes a URL plus optional keyword arguments and returns a Response object once the whole response has arrived:
r = requests.get("https://api.github.com")The most important attributes of the response are:
r.status_code: the HTTP status as an int, like200or404.r.ok:Truewhen the status is below 400.r.text: the body decoded to astr.r.json(): the body parsed as JSON into dicts and lists.r.headers: the response headers.
A non-2xx status is not an exception in Requests. requests.get happily returns a 404 response, and you must check it (later lessons show raise_for_status). Exceptions are raised only for failures to get a response at all, such as DNS errors or refused connections.
Requests is synchronous: the call blocks until the response is complete. That makes it ideal for scripts, CLIs and simple back-end code. For thousands of concurrent requests or async frameworks, look at HTTPX or aiohttp, which share most of these ideas.
Always pass a timeout in real code; it is introduced properly in its own lesson, but the examples use it from the start.
Example
import requests
r = requests.get("https://httpbin.org/get", timeout=10)
print(r.status_code) # 200
print(r.ok) # True
print(r.headers["Content-Type"]) # application/json
data = r.json()
print(type(data).__name__) # dict
print(data["url"]) # https://httpbin.org/get
missing = requests.get("https://httpbin.org/status/404", timeout=10)
print(missing.status_code, missing.ok) # 404 False (no exception!)Remember
- requests.get/post/put/... return a Response
- status_code, ok, text, json() and headers are the essentials
- HTTP error statuses do not raise by default
Watch out for
- Assuming requests.get raises an exception on 404 or 500.