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

جلسه‌ی 19: عوض کردن ردیف‌ها و صفحه‌بندی Changing Rows and Pages

API روی SQL کامل می‌شود: PATCH با UPDATE و DELETE با DELETE کار می‌کنند و .changed می‌گوید چند ردیف عوض شد؛ اگر صفر بود، 404. بعد فهرست‌های بلند را صفحه‌صفحه می‌دهی (LIMIT ? OFFSET ? برای ?page=2) و یاد می‌گیری چرا اسم ستون مرتب‌سازی فقط باید از یک فهرست ثابت بیاید.

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

درس

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

یادت هست؟ در جلسه‌ی ۱۸ برای یک ردیف از db.one استفاده کردیم: اگر None بود، 404؛ وگرنه خود ردیف. و POST با INSERT یک ردیف می‌ساخت و .id شماره‌اش را می‌داد. امروز ردیف‌ها را عوض و پاک می‌کنیم.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

@app.get("/players/<int:pid>")
def one_player(pid):
    row = db.one("SELECT * FROM players WHERE id = ?", (pid,))
    if row is None:
        abort(404, f"no player with id {pid}")
    return row

ask("GET /players/3")
ask("GET /players/30")

UPDATE و .changed. UPDATE players SET score = ? WHERE id = ? امتیاز یک بازیکن را عوض می‌کند. مقدارها به همان ترتیبی می‌آیند که ?ها در SQL هستند: اول امتیاز، بعد id. جواب db.run یک .changed دارد: تعداد ردیف‌هایی که عوض شدند. اگر 0 بود، یعنی بازیکنی با آن شماره نبود، پس 404. وگرنه ردیف تازه را با db.one بخوان و برگردان. این همان PATCH فاز ۴ است: فقط یک بخش عوض می‌شود.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

@app.patch("/players/<int:pid>")
def change_score(pid):
    score = request.json["score"]
    done = db.run("UPDATE players SET score = ? WHERE id = ?", (score, pid))
    if done.changed == 0:
        abort(404, f"no player with id {pid}")
    return db.one("SELECT * FROM players WHERE id = ?", (pid,))

ask("PATCH /players/4", {"score": 700})
ask("PATCH /players/40", {"score": 700})

DELETE و 204. DELETE FROM players WHERE id = ? یک ردیف را پاک می‌کند. باز .changed می‌گوید چیزی پاک شد یا نه: 0 یعنی 404. اگر پاک شد، مثل فاز ۴ return "", 204: «انجام شد، چیزی برای فرستادن نیست». دفعه‌ی دوم که همان را پاک کنی، دیگر چیزی نیست و 404 می‌گیری.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

@app.delete("/players/<int:pid>")
def remove_player(pid):
    done = db.run("DELETE FROM players WHERE id = ?", (pid,))
    if done.changed == 0:
        abort(404, f"no player with id {pid}")
    return "", 204

ask("DELETE /players/2")
ask("DELETE /players/2")
print(db.value("SELECT COUNT(*) FROM players"), "players left")

صفحه‌بندی. اگر هزار بازیکن داشته باشی، همه را یک‌جا نمی‌فرستی؛ صفحه‌صفحه می‌دهی، مثل نتیجه‌های جست‌وجو. LIMIT ? می‌گوید چند ردیف، و OFFSET ? می‌گوید از اول چند ردیف را رد کن. با ۳ ردیف در هر صفحه، صفحه‌ی ۲ یعنی LIMIT 3 OFFSET 3 و در کل OFFSET (page - 1) * 3. صفحه از ?page= می‌آید و مثل جلسه‌ی ۶ متن است: با int() و try/except ValueError عدد کن و اگر نشد 400. همیشه ORDER BY بگذار تا هر صفحه همیشه همان ردیف‌ها را بدهد.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

SIZE = 3

@app.get("/players")
def list_players():
    try:
        page = int(request.args.get("page", "1"))
    except ValueError:
        abort(400, "page must be a whole number")
    rows = db.all("SELECT id, name FROM players ORDER BY id LIMIT ? OFFSET ?", (SIZE, (page - 1) * SIZE))
    return {"page": page, "items": rows}

ask("GET /players?page=1")
ask("GET /players?page=3")
ask("GET /players?page=two")

مرتب‌سازی از یک فهرست ثابت. ? فقط جای یک مقدار است (یک اسم، یک عدد). اسم ستون، اسم جدول و کلمه‌هایی مثل DESC جزو خودِ SQL هستند و ? برایشان کار نمی‌کند. پس اگر کاربر بخواهد ?sort=score بدهد، آن را هرگز مستقیم داخل SQL نگذار. یک دیکشنری از مرتب‌سازی‌های مجاز بساز، ?sort= را با in بررسی کن (وگرنه 400) و متن SQL را از دیکشنری خودت بردار. این‌طوری هر چه کاربر بفرستد، فقط متنی که خودت نوشته‌ای وارد SQL می‌شود.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

SORTS = {"name": "name", "score": "score DESC, name"}

@app.get("/players")
def sorted_players():
    sort = request.args.get("sort", "name")
    if sort not in SORTS:
        abort(400, "sort must be one of: name, score")
    return db.all(f"SELECT name, score FROM players ORDER BY {SORTS[sort]} LIMIT 3")

ask("GET /players?sort=score")
ask("GET /players?sort=age")

اشتباه‌های رایج:
- UPDATE یا DELETE بدون WHERE: همه‌ی ردیف‌ها عوض یا پاک می‌شوند! .changed آن وقت می‌گوید ۷، نه ۱.
- ORDER BY ? با ("score",): خطا نمی‌دهد، ولی بر اساس متن ثابت 'score' مرتب می‌کند که برای همه یکی است، پس هیچ چیزی مرتب نمی‌شود.
- صفحه‌بندی بدون ORDER BY: ترتیب تضمینی نیست و یک ردیف ممکن است در دو صفحه بیاید.
- ?page=0: OFFSET منفی می‌شود. صفحه‌ی کمتر از ۱ را با 400 رد کن.

from server import app, ask, db, request, abort

db.script('''
CREATE TABLE players (id INTEGER PRIMARY KEY, name TEXT, level INTEGER, score INTEGER);
INSERT INTO players (name, level, score) VALUES ('Sara', 7, 1500), ('Ali', 4, 950), ('Mina', 9, 2100);
INSERT INTO players (name, level, score) VALUES ('Reza', 2, 300), ('Nima', 5, 1200), ('Yasmin', 8, 1800);
INSERT INTO players (name, level, score) VALUES ('Omid', 6, 1100);
''')

done = db.run("UPDATE players SET level = 1")
print("changed:", done.changed)
rows = db.all("SELECT name FROM players ORDER BY ? LIMIT 3", ("score",))
print(rows)

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

چالش‌ها

  1. The Right 404 (آسان)
  2. New High Score (آسان)
  3. Remove a Player (متوسط)
  4. Value or Fixed List? (متوسط)
  5. Page by Page (سخت)
  6. Top Three, Your Way (سخت)

بیشتر بخوان

← جلسه‌ی 18: API روی SQL جلسه‌ی 20: پروژه: سرور جدول امتیاز →