بتل کد Battle Codeدارد باز می‌شود…

جلسه‌ی 11: سمت مشتری: استفاده از API Being the Client

این بار جای اپ یا سایت می‌نشینی: درخواست را بی‌صدا (quiet=True) می‌فرستی، r.json را می‌خوانی و یک گزارش متنی مرتب چاپ می‌کنی. روی لیست جواب حلقه می‌زنی، چند درخواست پشت هم می‌فرستی (گرم‌ترین شهر weather.test)، و پیش از خواندن جواب، r.status را نگاه می‌کنی. آخر هم برای API خودت یک مشتری می‌نویسی.

در این جلسه یاد می‌گیری

درس

🔐 قانون طلایی این دوره: سرور امانت‌دار است. هر سروری که می‌سازی داده‌ی آدم‌ها را نگه می‌دارد: اسم، امتیاز، یادداشت، رمز. پس به هر چه از بیرون می‌آید شک کن، رمز را هیچ‌وقت خام نگه ندار و داده‌ی کسی را به دیگری نشان نده. فقط سرورهای خودت را امتحان کن. سرور این دوره ساختگی است و داخل همین صفحه کار می‌کند: هر بار که برنامه را اجرا می‌کنی از صفر ساخته می‌شود، پس هر چه می‌خواهی امتحان کن.

یادت هست؟ در جلسه‌ی ۱ دیدی ask(..., quiet=True) چیزی چاپ نمی‌کند و فقط جواب را برمی‌گرداند: r.status کد وضعیت است. در جلسه‌ی ۹ هم فهمیدیم r.text متن JSON است و r.json همان، تبدیل‌شده به دیکشنری یا لیست پایتون. امروز تمام جلسه با همین‌ها کار داریم.

from server import ask

r = ask("https://weather.test/today?city=Tehran", quiet=True)
print(r.status)
print(r.text)
print("Tehran is", r.json["temp"], "degrees and", r.json["sky"])

فرانت‌اند چه می‌کند؟ اپ هواشناسی گوشی‌ات هیچ‌وقت متن خام JSON را نشانت نمی‌دهد. کارش این است: درخواست بفرستد، JSON را بگیرد، تکه‌هایی را که لازم دارد بردارد و قشنگ نشان بدهد. اپ کوییز هم همین‌طور سؤال‌ها را از سرور می‌گیرد. یک بک‌اند می‌تواند چند مشتری داشته باشد: سایت، اپ گوشی، یک ربات. در برنامه‌های ما، بخش پایین برنامه (بعد از routeها) نقش مشتری را بازی می‌کند. پس quiet=True می‌زنیم تا فقط گزارش خودمان چاپ شود.

from server import ask

r = ask("https://jokes.test/jokes/4", quiet=True)
joke = r.json
print(f"Joke #{joke['id']} ({joke['kind']})")
print(joke["text"])

وقتی جواب یک لیست است، r.json یک لیست پایتون است: با for رویش بچرخ و از هر عضو (که یک دیکشنری است) فقط چیزی را که لازم داری بردار. len(r.json) هم تعدادشان را می‌دهد. اگر جواب پاکت باشد ({"count": ..., "items": [...]}، جلسه‌ی ۱۰)، حلقه روی r.json["items"] است.

from server import ask

r = ask("https://jokes.test/jokes?kind=school", quiet=True)
print(len(r.json), "school jokes")
for joke in r.json:
    print("-", joke["text"])

چند درخواست پشت هم. خیلی وقت‌ها یک درخواست کافی نیست. اول فهرست را می‌گیری، بعد برای هر عضوش یک درخواست دیگر می‌فرستی. مثلاً weather.test/cities اسم شهرها را می‌دهد و بعد برای هر شهر today?city=... را می‌پرسی. آدرس درخواست بعدی را با f-string از جواب قبلی می‌سازی: f"https://weather.test/today?city={city}". اپ‌های واقعی هم همین کار را می‌کنند.

from server import ask

cities = ask("https://weather.test/cities", quiet=True).json
sunny = 0
for city in cities:
    r = ask(f"https://weather.test/today?city={city}", quiet=True)
    print(city, r.json["sky"])
    if r.json["sky"] == "sunny":
        sunny = sunny + 1
print(sunny, "sunny cities")

اول وضعیت، بعد جواب. هر درخواستی جواب خوب نمی‌گیرد: شهری که نیست 404 می‌گیرد و آن وقت r.json به‌جای temp فقط {"error": ...} دارد. اگر بی‌نگاه r.json["temp"] بنویسی، برنامه‌ات با KeyError می‌ترکد. پس اول r.status == 200 (یا r.ok، یعنی هر کد 2xx) را نگاه کن؛ اگر خوب نبود، r.json["error"] را مؤدبانه نشان بده. سایتی که اصلاً نیست هم کد 502 می‌دهد.

from server import ask

for city in ["Rasht", "Paris"]:
    r = ask(f"https://weather.test/today?city={city}", quiet=True)
    if r.status == 200:
        print(city, r.json["temp"])
    else:
        print("Error", r.status, r.json["error"])

r = ask("https://cats.test/", quiet=True)
print(r.status, r.ok)

مشتری API خودت. حالا هر دو طرف را با هم داری: بالای برنامه routeها (بک‌اند) و پایینش مشتری (کار فرانت‌اند). مشتری فقط از راه ask با سرور حرف می‌زند، درست مثل اپی که روی گوشی یک نفر دیگر است. از جواب یک گزارش متنی بساز: یک خط عنوان، یک خط برای هر چیز، و یک خط جمع‌بندی.

from server import app, ask

scores = [{"name": "Sara", "score": 120}, {"name": "Ali", "score": 95}, {"name": "Mina", "score": 140}]

@app.get("/scores")
def all_scores():
    return {"count": len(scores), "items": scores}

# the client: what a website or an app would do
r = ask("GET /scores", quiet=True)
print(f"Scores ({r.json['count']} players)")
total = 0
for row in r.json["items"]:
    print(f"{row['name']}: {row['score']}")
    total = total + row["score"]
print(f"Total: {total}")

اشتباه‌های رایج:
- یادت برود quiet=True بزنی: خط‌های خام ask هم کنار گزارشت چاپ می‌شوند (کد زیر را ببین).
- r["temp"] به‌جای r.json["temp"]: خودِ r دیکشنری نیست، جوابی است که JSONش در r.json است.
- خواندن r.json[...] پیش از نگاه کردن به r.status.
- r.json["name"] روی جوابی که لیست است: لیست با عدد (r.json[0]) یا با حلقه خوانده می‌شود.
- داخل f-string با کوتیشن دوتایی، کلید را با کوتیشن تکی بنویس: f"{row['name']}".

from server import ask

r = ask("https://weather.test/today?city=Shiraz")
print("Shiraz:", r.json["temp"])

مثال‌های این جلسه

چالش‌ها

  1. Weather in Shiraz (آسان)
  2. All the Players (آسان)
  3. Weather for Any City (متوسط)
  4. The Warmest City (متوسط)
  5. My Homework Report (سخت)
  6. Top Three, in Detail (سخت)

بیشتر بخوان

← جلسه‌ی 10: طراحی یک API خوب جلسه‌ی 12: پروژه: API آمار بازی و کلاینتش →