Working with APIs in Python

The Story That Explains APIs 🍽️APIs समझाने वाली कहानी 🍽️一个讲清 API 的故事 🍽️

Every modern app talks to APIs — weather, payments, maps, AI models, stock prices, social feeds. In Python the standard tool is the requests library: one line to send an HTTP call, one line to parse the JSON. This tutorial goes from "what is an API" to "I can build a reliable client for a real service".

हर आधुनिक app APIs से बात करता है — मौसम, payments, maps, AI models, शेयर के भाव, social feeds। Python में मानक औज़ार requests library है: HTTP call भेजने के लिए एक line, JSON parse करने के लिए एक line। यह tutorial "API क्या है" से "मैं असली service के लिए भरोसेमंद client बना सकता हूँ" तक ले जाता है।

每个现代应用都在调用 API — 天气、支付、地图、AI 模型、股价、社交动态。在 Python 中，标准工具是 requests 库：一行代码发送 HTTP 请求，一行代码解析 JSON。本教程带你从"什么是 API"走到"我能为真实服务写出可靠的客户端"。

Visual Diagram — The HTTP Request / Response Cycle 🔄चित्र — HTTP Request / Response चक्र 🔄图解 — HTTP 请求 / 响应循环 🔄

Every API call — however fancy — is one arrow going right and one arrow coming back. Everything else in this tutorial is a variation on that pattern.

हर API call — चाहे कितनी भी जटिल हो — एक तीर दाईं ओर जाता है और एक वापस आता है। इस tutorial में बाक़ी सब इसी pattern के रूप हैं।

每次 API 调用 — 无论多复杂 — 都是一支箭头向右发出，一支箭头返回。本教程的其余内容都是这个模式的变化。

The Three Building Blocks of an API Call 🧱API Call की तीन ईंटें 🧱API 调用的三块基石 🧱

Your First API Callआपकी पहली API Call你的第一次 API 调用

# pip install requests
import requests

# Public API - no auth required
r = requests.get("https://api.github.com/users/torvalds", timeout=5)

print(r.status_code)                 # 200 = success
print(r.headers["Content-Type"])     # what kind of data came back

data = r.json()                      # parse JSON -> Python dict
print(data["name"])
print(data["public_repos"])
print(data["bio"])                   # JSON null -> Python None

r.json() turned the JSON text into a normal Python dict. JSON null became Python None — that is why bio printed None.

r.json() ने JSON text को सामान्य Python dict में बदला। JSON का null Python का None बन गया — इसीलिए bio ने None print किया।

r.json() 把 JSON 文本变成了普通的 Python dict。JSON 的 null 变成了 Python 的 None — 所以 bio 打印出 None。

The HTTP Methods — What They Mean, When to Use Each 🚦HTTP Methods — मतलब, और कब कौन-सा 🚦HTTP 方法 — 含义与使用时机 🚦

Idempotent means: sending the same request twice leaves the server in the same state as sending it once. It is about the server state, not the reply — a second DELETE may answer 404, but the item is still just gone.

Idempotent का मतलब: एक ही request दो बार भेजने पर server की हालत वैसी ही रहती है जैसी एक बार भेजने पर। यह server की हालत के बारे में है, जवाब के बारे में नहीं — दूसरा DELETE 404 दे सकता है, पर item बस हटा हुआ ही है।

幂等 的意思是：同一个请求发两次，服务器的状态与只发一次相同。它关注的是 服务器状态，而不是回复 — 第二次 DELETE 可能返回 404，但该条目依然只是被删除了。

import requests

BASE = "https://jsonplaceholder.typicode.com"   # public sandbox API

# GET - read one post
r = requests.get(f"{BASE}/posts/1", timeout=5)
print("GET   ", r.status_code, r.json()["title"][:30])

# POST - create a new post
new_post = {"title": "Hello", "body": "World", "userId": 1}
r = requests.post(f"{BASE}/posts", json=new_post, timeout=5)
print("POST  ", r.status_code, r.json())

# PUT - replace an existing post
r = requests.put(f"{BASE}/posts/1",
                 json={"id": 1, "title": "Updated", "body": "New", "userId": 1},
                 timeout=5)
print("PUT   ", r.status_code, r.json())

# PATCH - change only the title
r = requests.patch(f"{BASE}/posts/1", json={"title": "Just the title"}, timeout=5)
print("PATCH ", r.status_code, r.json()["title"], "| body kept:", r.json()["body"][:12] + "...")

# DELETE - remove
r = requests.delete(f"{BASE}/posts/1", timeout=5)
print("DELETE", r.status_code, r.json())

🔁 Simulator: Send It Twice🔁 Simulator: दो बार भेजिए🔁 模拟器：发送两次

Pick a request. It is sent twice to a small notes API that really keeps state. Compare the server state after call 1 and after call 2: if they match, the request is idempotent.

एक request चुनिए। इसे एक छोटे notes API को दो बार भेजा जाता है जो सच में हालत याद रखता है। Call 1 और call 2 के बाद server की हालत मिलाइए: अगर दोनों मेल खाएँ, तो request idempotent है।

选一个请求。它会被 发送两次 到一个真正保存状态的小型笔记 API。比较第 1 次和第 2 次调用后的服务器状态：如果相同，这个请求就是幂等的。

Query Params vs Request Body — When to Use Which 📮Query Params बनाम Request Body — कब कौन-सा 📮查询参数 vs 请求体 — 何时用哪个 📮

There are two places to send data with a request: the URL (query string) or the body. Mixing them up is a very common reason for "why won't my POST work?".

Request के साथ data भेजने की दो जगहें हैं: URL (query string) या body। इन्हें गड़बड़ाना "मेरा POST क्यों नहीं चल रहा?" का बहुत आम कारण है।

随请求发送数据有两个位置：URL（查询字符串）或 请求体。把两者搞混是"为什么我的 POST 不工作？"的一个非常常见的原因。

import requests

# Query params - passed via params={}
r = requests.get(
    "https://api.open-meteo.com/v1/forecast",
    params={
        "latitude": 35.68,
        "longitude": 139.65,
        "current_weather": True,
    },
    timeout=5,
)
print(r.url)                          # the URL requests actually sent

# JSON body - passed via json={}
r = requests.post(
    "https://httpbin.org/post",
    json={"name": "Ada", "role": "engineer"},
    timeout=5,
)
print(r.json()["json"])               # httpbin echoes back what you sent
print(r.request.headers["Content-Type"])

Look at the first line: params= built the whole query string for you, and Python's True was sent as the text True. With json=, requests turned the dict into JSON text and set Content-Type: application/json by itself.

पहली line देखिए: params= ने पूरी query string आपके लिए बनाई, और Python का True text True के रूप में गया। json= के साथ requests ने dict को JSON text में बदला और ख़ुद Content-Type: application/json लगाया।

看第一行：params= 替你拼好了整个查询字符串，Python 的 True 被当作文本 True 发送。使用 json= 时，requests 把字典转成 JSON 文本，并自动设置 Content-Type: application/json。

import requests

user_input = "São Paulo & Rio"

# WRONG - glue the URL together by hand
r = requests.get("https://httpbin.org/get?q=" + user_input, timeout=5)
print("concat :", r.json()["args"])

# RIGHT - let requests encode it
r = requests.get("https://httpbin.org/get", params={"q": user_input}, timeout=5)
print("params :", r.json()["args"])
print("sent   :", r.url)

🔤 Simulator: URL Encoding Lab🔤 Simulator: URL Encoding Lab🔤 模拟器：URL 编码实验室

Pick a search term. Both versions were really sent; the boxes show the URL that went out and what the server actually received.

एक search term चुनिए। दोनों versions सच में भेजे गए; डिब्बे दिखाते हैं कि कौन-सा URL गया और server को असल में क्या मिला।

选一个搜索词。两个版本都真实发送过；方框里显示发出的 URL 以及服务器实际收到的内容。

Parsing JSON — The Most Common Response Format 🧾JSON Parse करना — सबसे आम Response Format 🧾解析 JSON — 最常见的响应格式 🧾

Most modern web APIs speak JSON. requests parses it with one method call, and you get back normal Python objects: dict, list, str, int, float, bool and None.

ज़्यादातर आधुनिक web APIs JSON बोलते हैं। requests इसे एक method call से parse करता है, और आपको सामान्य Python objects मिलते हैं: dict, list, str, int, float, bool और None।

大多数现代 Web API 都使用 JSON。requests 一次方法调用就能解析它，你得到的是普通的 Python 对象：dict、list、str、int、float、bool 和 None。

import requests

r = requests.get("https://api.github.com/repos/python/cpython", timeout=5)
data = r.json()                      # dict[str, Any]

print(data["full_name"])
print(data["stargazers_count"])
print(data["language"])
print(data["license"]["name"])       # nested access is just dict[key]

# Lists in JSON - same rules as normal Python
r = requests.get("https://api.github.com/repos/python/cpython/contributors",
                 params={"per_page": 3}, timeout=5)
for contributor in r.json():
    print(f"{contributor['login']:18s} {contributor['contributions']:>5} commits")

Safe Access to Optional KeysOptional Keys तक सुरक्षित पहुँच安全访问可选键

import requests

data = requests.get("https://api.github.com/users/torvalds", timeout=5).json()

# The key may be missing, or present with the value null (None)
print(data.get("bio"))                          # None (here: present, but null)
print(data.get("bio") or "no bio available")    # handles missing AND null
print(data.get("twitter", "no such key"))       # key missing -> default

# Nested optional access - "or {}" protects against a missing or null parent
license_name = (data.get("license") or {}).get("name", "unknown")
print(license_name)

print(data["twitter"])                          # KeyError: missing key

Two different problems look alike: a key that is missing (data["twitter"] → KeyError) and a key that is present with the value null (data["bio"] → None). data.get(key) or default handles both.

दो अलग समस्याएँ एक जैसी दिखती हैं: ग़ायब key (data["twitter"] → KeyError) और मौजूद key जिसकी value null है (data["bio"] → None)। data.get(key) or default दोनों संभालता है।

两个看起来相似的问题其实不同：键 缺失（data["twitter"] → KeyError），以及键存在但值为 null（data["bio"] → None）。data.get(key) or default 两种情况都能处理。

Parsing XML — For Legacy and Enterprise APIs 🌳XML Parse करना — पुराने और Enterprise APIs के लिए 🌳解析 XML — 用于旧系统和企业 API 🌳

XML still lives on in older or enterprise services — SOAP endpoints, government data feeds, RSS/Atom feeds, some payment gateways. Python's standard library reads it with xml.etree.ElementTree.

XML अब भी पुरानी या enterprise services में है — SOAP endpoints, सरकारी data feeds, RSS/Atom feeds, कुछ payment gateways। Python की standard library इसे xml.etree.ElementTree से पढ़ती है।

XML 仍存在于较老的或企业级服务中 — SOAP 端点、政府数据源、RSS/Atom 订阅、一些支付网关。Python 标准库用 xml.etree.ElementTree 读取它。

import requests
import xml.etree.ElementTree as ET

# Example: NASA's news RSS feed (XML)
r = requests.get("https://www.nasa.gov/feed/", timeout=5)
root = ET.fromstring(r.content)      # root is the outermost <rss> element
print(root.tag, root.attrib)

# RSS structure: rss > channel > item*
channel = root.find("channel")
for item in channel.findall("item")[:3]:
    title = item.findtext("title")
    link  = item.findtext("link")
    date  = item.findtext("pubDate")
    print(f"- {title}\n  {link}\n  {date}")

Authentication — Proving Who You Are 🔑Authentication — आप कौन हैं यह साबित करना 🔑认证 — 证明你是谁 🔑

Most useful APIs need you to identify yourself. There are three common patterns. In every case, credentials belong in environment variables — never in code, never in git.

ज़्यादातर काम के APIs आपसे पहचान माँगते हैं। तीन आम patterns हैं। हर हाल में credentials environment variables में रहते हैं — code में कभी नहीं, git में कभी नहीं।

大多数有用的 API 都要求你表明身份。常见的模式有三种。无论哪种，凭据都应放在环境变量中 — 绝不写进代码，绝不提交到 git。

import os, requests

# 1) API key as query param - the API tells you the parameter name
r = requests.get(
    "https://api.openweathermap.org/data/2.5/weather",
    params={"q": "Mumbai", "appid": os.environ["OWM_KEY"]},
    timeout=5,
)
print("1) key in URL   :", r.status_code, r.json()["name"])

# 2) API key as header - many modern APIs prefer this
r = requests.get(
    "https://api.example.com/data",
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=5,
)
print("2) key in header:", r.status_code, r.json())

# 3) Bearer token - GitHub, OpenAI, Stripe pattern
token = os.environ["GITHUB_TOKEN"]
r = requests.get(
    "https://api.github.com/user",
    headers={"Authorization": f"Bearer {token}"},
    timeout=5,
)
print("3) bearer token :", r.status_code, r.json()["login"])

# 4) Basic auth - requests has built-in support
r = requests.get(
    "https://api.example.com/private",
    auth=(os.environ["API_USER"], os.environ["API_PASSWORD"]),
    timeout=5,
)
print("4) basic auth   :", r.status_code, r.json())
print("   header sent  :", r.request.headers["Authorization"])

Look at the last line: YWRhOnMzY3JldA== is just ada:s3cret in base64. Anyone who sees it can decode it in a second — that is why Basic auth needs HTTPS.

आख़िरी line देखिए: YWRhOnMzY3JldA== बस base64 में ada:s3cret है। जो भी इसे देखे, एक सेकंड में decode कर सकता है — इसीलिए Basic auth को HTTPS चाहिए।

看最后一行：YWRhOnMzY3JldA== 只是 ada:s3cret 的 base64 形式。任何看到它的人一秒钟就能解码 — 所以 Basic 认证必须配合 HTTPS。

import os, requests

# Danger: USER is already set by your operating system!
print("USER is:", os.environ["USER"])         # your login name, not the API user

r = requests.get("https://api.example.com/private",
                 auth=(os.environ["USER"], os.environ["API_PASSWORD"]), timeout=5)
print(r.status_code, r.json())

r = requests.get("https://api.github.com/user",
                 headers={"Authorization": "Bearer wrong-token"}, timeout=5)
print(r.status_code, r.json()["message"])

Handling Status Codes and Errors 🚨Status Codes और Errors संभालना 🚨处理状态码与错误 🚨

The status code is your first check on every response. Ignoring it is how you get confusing bugs at 3 AM.

Status code हर response पर आपकी पहली जाँच है। इसे अनदेखा करना ही रात 3 बजे उलझाने वाले bugs की वजह बनता है।

状态码是每个响应的第一道检查。忽视它，就会在凌晨 3 点遇到让人摸不着头脑的 bug。

import requests

r = requests.get("https://api.github.com/repos/does-not/exist", timeout=5)

# Option A: check the code manually
if r.status_code == 200:
    print(r.json())
elif r.status_code == 404:
    print("repo does not exist")
elif r.status_code == 429:
    print("rate limited, wait and retry")
else:
    print(f"unexpected: {r.status_code}")

# Option B: let requests raise on any 4xx/5xx
try:
    r = requests.get("https://api.github.com/repos/does-not/exist", timeout=5)
    r.raise_for_status()          # raises HTTPError on 4xx/5xx
    data = r.json()
except requests.HTTPError as e:
    print(f"HTTP failure: {e}")
except requests.Timeout:
    print("server took too long")
except requests.ConnectionError:
    print("can't reach server (DNS / offline)")

print("r.ok =", r.ok)

The Timeout and ConnectionError branches never ran above. Here they are, triggered on purpose:

ऊपर Timeout और ConnectionError वाली branches कभी नहीं चलीं। यहाँ वे जान-बूझकर चलाई गई हैं:

上面的 Timeout 和 ConnectionError 分支都没有执行。这里我们故意触发它们：

import requests

for url in ["https://api.example.com/hang",            # never answers
            "https://no-such-host.invalid/"]:          # DNS fails
    try:
        requests.get(url, timeout=1.5)
    except requests.Timeout as e:
        print("Timeout        :", type(e).__name__)
    except requests.ConnectionError as e:
        print("ConnectionError:", type(e).__name__)

🚦 Simulator: Status Code Explorer🚦 Simulator: Status Code Explorer🚦 模拟器：状态码探索器

Click a status code. Each one was really requested, and the panel shows what requests did with it: r.ok, raise_for_status(), r.json() and redirects.

एक status code पर click कीजिए। हर एक सच में माँगा गया, और panel दिखाता है कि requests ने उसके साथ क्या किया: r.ok, raise_for_status(), r.json() और redirects।

点击一个状态码。每个都真实请求过，面板显示 requests 如何处理它：r.ok、raise_for_status()、r.json() 以及重定向。

Retries with Exponential Backoff ⏳Exponential Backoff के साथ Retries ⏳指数退避重试 ⏳

Networks fail. Servers hiccup. Rate limits happen. A good client retries temporary errors with a growing pause, so the server has room to recover. This is called exponential backoff.

Networks fail होते हैं। Servers अटकते हैं। Rate limits लगते हैं। अच्छा client अस्थायी errors को बढ़ते विराम के साथ retry करता है, ताकि server संभल सके। इसे exponential backoff कहते हैं।

网络会故障，服务器会卡顿，也会遇到限流。好的客户端会以逐渐变长的间隔重试 临时 错误，给服务器恢复的空间。这叫做 指数退避。

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

# Built-in retry - no manual loop needed
retry_policy = Retry(
    total=5,                      # up to 5 RETRIES (6 attempts in all)
    backoff_factor=1.0,           # sleeps between tries: 0, 2, 4, 8, 16 s
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "HEAD", "PUT", "DELETE", "OPTIONS"],  # idempotent only
    respect_retry_after_header=True,
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry_policy))

# Now every request through this session auto-retries transient errors
r = session.get("https://api.github.com/users/torvalds", timeout=10)
print(r.status_code)

import time, requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# A test endpoint that fails twice with 503, then succeeds
URL = "https://api.example.com/flaky/demo?fail=2&code=503"

retry = Retry(total=5, backoff_factor=0.5, status_forcelist=[429, 500, 502, 503, 504])
s = requests.Session()
s.mount("https://", HTTPAdapter(max_retries=retry))

t0 = time.perf_counter()
r = s.get(URL, timeout=5)
print(r.status_code, r.json(), f"after {time.perf_counter() - t0:.1f} s")

log = requests.get("https://api.example.com/flaky-log/demo", timeout=5).json()
gaps = [round(b - a, 1) for a, b in zip(log["t"], log["t"][1:])]
print("server saw", log["n"], "attempts; gaps between them:", gaps, "s")

🔁 Simulator: Retry Lab🔁 Simulator: Retry Lab🔁 模拟器：重试实验室

A test server fails a chosen number of times, then succeeds. The client uses Retry(total=3, backoff_factor=0.5). Every dot is a real attempt, placed at the time the server saw it. For POST, this server saves the order even when it answers with an error — just like a real server whose reply gets lost.

एक test server चुनी गई बार fail होता है, फिर सफल होता है। Client Retry(total=3, backoff_factor=0.5) लेता है। हर बिंदु एक असली प्रयास है, उसी समय पर जब server ने उसे देखा। POST के लिए यह server error देते हुए भी order save कर लेता है — बिल्कुल उस असली server की तरह जिसका जवाब खो जाता है।

一台测试服务器先失败指定的次数，然后成功。客户端使用 Retry(total=3, backoff_factor=0.5)。每个圆点都是一次真实尝试，放在服务器收到它的时间点上。对于 POST，这台服务器即使返回错误也会保存订单 — 就像回复丢失的真实服务器一样。

Sessions — Connection Reuse for Speed 🔌Sessions — Speed के लिए Connection दोबारा इस्तेमाल 🔌Session — 复用连接以提速 🔌

If you make more than one request to the same host, use a Session. It keeps the TCP + TLS connection open and reuses it, so later requests skip the connection setup (TCP handshake and TLS negotiation). A Session also keeps headers and cookies for you.

अगर आप एक ही host को एक से ज़्यादा requests भेजते हैं, तो Session लीजिए। यह TCP + TLS connection खुला रखकर दोबारा इस्तेमाल करता है, इसलिए बाद की requests connection बनाने का काम (TCP handshake और TLS negotiation) छोड़ देती हैं। Session आपके लिए headers और cookies भी याद रखता है।

如果你要向同一主机发送多个请求，就用 Session。它保持 TCP + TLS 连接打开并复用，后续请求就能跳过建立连接的步骤（TCP 握手和 TLS 协商）。Session 还会替你保存请求头和 Cookie。

import time, requests

N = 100
def stats(): return requests.get("https://api.example.com/conns?reset=1", timeout=5).json()

stats()
# Bad - new connection every call
t0 = time.perf_counter()
for i in range(N):
    requests.get(f"https://api.github.com/repos/python/cpython/issues/{i + 1}", timeout=5)
t_bad = time.perf_counter() - t0
print(f"no session : {t_bad:.2f} s, connections opened: {stats()['connections'] - 1}")

# Good - one session, connections reused
token = "ghp_demo_token_123"
t0 = time.perf_counter()
with requests.Session() as s:
    s.headers.update({"Authorization": f"Bearer {token}"})
    for i in range(N):
        r = s.get(f"https://api.github.com/repos/python/cpython/issues/{i + 1}",
                  timeout=5)
t_good = time.perf_counter() - t0
print(f"session    : {t_good:.2f} s, connections opened: {stats()['connections'] - 1}")
print(f"speed-up   : {t_bad / t_good:.1f}x")

🔌 Simulator: Session Lab🔌 Simulator: Session Lab🔌 模拟器：Session 实验室

Choose how many requests to send. Each little block is one TCP + TLS connection the server really saw.

चुनिए कितनी requests भेजनी हैं। हर छोटा block एक TCP + TLS connection है जिसे server ने सच में देखा।

选择要发送多少个请求。每个小方块代表服务器真实看到的一个 TCP + TLS 连接。

Pagination — Fetching Big Result Sets 📚Pagination — बड़े Results लाना 📚分页 — 获取大量结果 📚

APIs return data in pages — you rarely get 10,000 items in one call. There are three common styles:

APIs data pages में लौटाते हैं — एक call में 10,000 items शायद ही मिलते हैं। तीन आम तरीके हैं:

API 以 分页 形式返回数据 — 一次调用很少能拿到 10,000 条。常见的方式有三种：

import os, requests

def fetch_all_issues(repo: str, token: str) -> list[dict]:
    session = requests.Session()
    session.headers.update({"Authorization": f"Bearer {token}"})

    all_issues, page = [], 1
    while True:
        r = session.get(f"https://api.github.com/repos/{repo}/issues",
                        params={"page": page, "per_page": 100, "state": "all"},
                        timeout=10)
        r.raise_for_status()
        batch = r.json()
        print(f"page {page}: {len(batch)} items")
        if not batch:                    # empty page = we're done
            break
        all_issues.extend(batch)
        page += 1
    return all_issues

issues = fetch_all_issues("python/cpython", os.environ["GITHUB_TOKEN"])
print(f"fetched {len(issues)} issues")

This works, but it spends one extra request on the empty page. GitHub sends a Link header with the next URL, and requests parses it for you as r.links:

यह चलता है, पर ख़ाली page पर एक अतिरिक्त request ख़र्च करता है। GitHub अगले URL के साथ Link header भेजता है, और requests उसे आपके लिए r.links के रूप में parse करता है:

这样可行，但会在空页上多花一次请求。GitHub 会发送带有下一页 URL 的 Link 响应头，requests 会把它解析为 r.links：

import os, requests

def fetch_all_issues(repo: str, token: str) -> list[dict]:
    s = requests.Session()
    s.headers.update({"Authorization": f"Bearer {token}"})
    url = f"https://api.github.com/repos/{repo}/issues"
    params = {"per_page": 100, "state": "all"}
    items = []
    while url:
        r = s.get(url, params=params, timeout=10)
        r.raise_for_status()
        items.extend(r.json())
        print(f"got {len(r.json())} items, next ->", r.links.get("next", {}).get("url"))
        url = r.links.get("next", {}).get("url")   # GitHub's Link header
        params = None                              # the next URL already has them
    return items

print("fetched", len(fetch_all_issues("python/cpython", os.environ["GITHUB_TOKEN"])))

📚 Simulator: Pagination Stepper📚 Simulator: Pagination Stepper📚 模拟器：分页单步演示

237 items wait on the server. Pick a style and a page size, then step through the real requests. Watch how each style knows when to stop.

Server पर 237 items इंतज़ार कर रहे हैं। एक तरीका और page size चुनिए, फिर असली requests step-by-step देखिए। देखिए हर तरीका कैसे जानता है कि कब रुकना है।

服务器上有 237 条数据。选择一种方式和每页大小，然后逐步查看真实请求。观察每种方式如何判断何时停止。

Common Pitfalls (and Fixes) 🕳️आम ग़लतियाँ (और सुधार) 🕳️常见陷阱（及修正）🕳️

Real-World Example — Complete GitHub Repo Analyzer 🐙असली उदाहरण — पूरा GitHub Repo Analyzer 🐙实战示例 — 完整的 GitHub 仓库分析器 🐙

All the pieces together: a session, auth, timeouts, retries, error handling, JSON parsing and a typed dataclass — in one small, solid client. We added a fourth repo that does not exist, to show the error path.

सारे टुकड़े एक साथ: session, auth, timeouts, retries, error handling, JSON parsing और typed dataclass — एक छोटे, मज़बूत client में। Error वाला रास्ता दिखाने के लिए हमने चौथा repo जोड़ा जो मौजूद नहीं है।

所有部件合在一起：Session、认证、超时、重试、错误处理、JSON 解析和带类型的 dataclass — 组成一个小巧而可靠的客户端。我们加了第四个不存在的仓库，用来展示出错路径。

import os
from dataclasses import dataclass
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

BASE = "https://api.github.com"

@dataclass(frozen=True)
class RepoStats:
    full_name: str
    stars: int
    forks: int
    open_issues: int
    language: str | None
    top_contributors: list[str]

def build_session(token: str) -> requests.Session:
    retry = Retry(total=5, backoff_factor=1.0,
                  status_forcelist=[429, 500, 502, 503, 504])
    s = requests.Session()
    s.mount("https://", HTTPAdapter(max_retries=retry))
    s.headers.update({
        "Authorization": f"Bearer {token}",
        "Accept":        "application/vnd.github+json",
        "User-Agent":    "repo-analyzer/1.0",
    })
    return s

def analyze_repo(session: requests.Session, repo: str) -> RepoStats | None:
    try:
        r = session.get(f"{BASE}/repos/{repo}", timeout=10)
        r.raise_for_status()
        info = r.json()

        c = session.get(f"{BASE}/repos/{repo}/contributors",
                        params={"per_page": 5}, timeout=10)
        c.raise_for_status()
        top = [u["login"] for u in c.json()]

        return RepoStats(
            full_name        = info["full_name"],
            stars            = info["stargazers_count"],
            forks            = info["forks_count"],
            open_issues      = info["open_issues_count"],
            language         = info.get("language"),
            top_contributors = top,
        )
    except requests.HTTPError as e:
        print(f"[{repo}] HTTP error: {e}")
    except (requests.Timeout, requests.ConnectionError):
        print(f"[{repo}] network problem")
    return None

# -- Run it ------------------------------------------------
REPOS = ["python/cpython", "pallets/flask", "psf/requests", "no/such-repo"]
with build_session(os.environ["GITHUB_TOKEN"]) as s:
    for repo in REPOS:
        stats = analyze_repo(s, repo)
        if stats:
            print(f"\n{stats.full_name}")
            print(f"  stars {stats.stars:,}   forks {stats.forks:,}   issues {stats.open_issues:,}")
            print(f"  language: {stats.language}")
            print(f"  top:      {', '.join(stats.top_contributors)}")

Bug Doctor, Golden Rules and Quiz 🏆Bug Doctor, सुनहरे नियम और Quiz 🏆Bug 医生、黄金法则与小测验 🏆

🩺 Simulator: Bug Doctor🩺 Simulator: Bug Doctor🩺 模拟器：Bug 医生

Six real API mistakes. Buggy code on the left, fixed code on the right, changed lines marked. Every output is from a real run (the hanging program was stopped after 4 seconds).

छह असली API ग़लतियाँ। बाईं ओर buggy code, दाईं ओर ठीक किया हुआ, बदली lines चिह्नित। हर output असली run से है (अटका program 4 सेकंड बाद रोका गया)।

六个真实的 API 错误。左边是有 bug 的代码，右边是修正后的代码，改动的行已标出。每个输出都来自真实运行（挂起的程序在 4 秒后被停止）。

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题