مكتبة requests

مكتبة requests — The requests Library

كل مرة تبحث في جوجل أو تفتح تطبيق الطقس أو تراسل أحداً عبر واتساب، هناك برنامج في الخلفية يرسل طلبات HTTP ويستقبل استجابات. Python تتيح لك فعل نفس الشيء في أسطر قليلة، وأشهر أداة لذلك هي مكتبة requests.

ما هو HTTP؟

HTTP (HyperText Transfer Protocol) هو البروتوكول الذي يتحدث به الويب. كل تبادل يبدأ من العميل (أنت) بطلب، وينتهي باستجابة من الخادم:

العميل → [GET /api/weather?city=Riyadh] → الخادم
العميل ← [200 OK, {"temp": 38}] ← الخادم

كل طلب له:

الأسلوب (Method): GET لقراءة البيانات، POST لإنشائها، PUT لتحديثها، DELETE لحذفها
الرابط (URL): عنوان الخادم والمسار
الترويسات (Headers): معلومات إضافية مثل نوع المحتوى أو بيانات المصادقة
الجسم (Body): البيانات المُرسَلة (في POST وPUT عادةً)

وكل استجابة لها:

رمز الحالة (Status Code): 200 نجاح، 404 غير موجود، 500 خطأ في الخادم
الترويسات: تصف نوع المحتوى وغيره
الجسم: البيانات المُعادة، غالباً JSON

تثبيت المكتبة

pip install requests

طلب GET — قراءة البيانات

GET هو أبسط الطلبات — تطلب بيانات ولا ترسل شيئاً:

import requests

# طلب حقيقي — Real request (يحتاج اتصال بالإنترنت)
response = requests.get("https://api.github.com/users/octocat")

print(response.status_code)   # 200
print(response.json())        # dict يحتوي بيانات المستخدم

لكن داخل المتصفح، الكود يعمل على Pyodide — بيئة Python وضعيّة في المتصفح لا تستطيع إرسال طلبات HTTP حقيقية لأسباب أمنية تتعلق بـ CORS وsandboxing. لذلك في التدريبات، سنحاكي الاستجابات بتحليل JSON نصي — وهذا يمنحنا تدريباً حقيقياً على الجزء الأهم: فهم شكل الاستجابة والتعامل معها.

تحليل استجابة JSON

الجزء الأكثر استخداماً في العمل مع APIs هو تحليل الاستجابة. في كود حقيقي:

import requests

response = requests.get("https://api.example.com/users/1")
# تحويل الاستجابة إلى dict — Convert response to dict
data = response.json()
print(data["name"])

في التدريبات، نُحاكي هذا بـ json.loads():

main.go

import json

# محاكاة استجابة JSON من خادم — Simulated JSON response from server
raw_response = '{"id": 1, "name": "أحمد", "email": "ahmed@example.com", "city": "الرياض"}'

# تحويل النص إلى dict — Convert text to dict
data = json.loads(raw_response)

print("الاسم:", data["name"])
print("المدينة:", data["city"])
print("البريد:", data["email"])

Output:

المعاملات في URL — Query Parameters

كثير من APIs تقبل معاملات في الرابط مثل ?page=2&limit=10. مكتبة requests تتولى بناء هذا الرابط تلقائياً:

import requests

# بدون requests — رابط يدوي
url = "https://api.example.com/products?category=books&page=1&limit=20"

# مع requests — params تُبنى تلقائياً
params = {
    "category": "books",   # الفئة — category
    "page": 1,             # رقم الصفحة — page number
    "limit": 20            # عدد النتائج — results per page
}
response = requests.get("https://api.example.com/products", params=params)
# requests يبني الرابط نيابةً عنك — requests builds URL for you

دعنا نتدرب على تحليل نتائج مُصنّفة:

main.go

import json

# محاكاة استجابة API لقائمة منتجات — Simulated product list API response
raw = '''
{
  "total": 3,
  "page": 1,
  "products": [
    {"id": 1, "name": "كتاب Python", "price": 49.99, "category": "كتب"},
    {"id": 2, "name": "دفتر ملاحظات", "price": 12.50, "category": "قرطاسية"},
    {"id": 3, "name": "قلم برمجة", "price": 8.75, "category": "قرطاسية"}
  ]
}
'''

data = json.loads(raw)

print(f"إجمالي المنتجات: {data['total']}")
print(f"الصفحة: {data['page']}")
print()

# طباعة كل منتج — Print each product
for product in data["products"]:
    print(f"  [{product['id']}] {product['name']} — {product['price']} ريال ({product['category']})")

Output:

الترويسات — Headers

الترويسات تُرسَل مع كل طلب وتحمل معلومات مهمة. أشيع استخدام لها هو المصادقة (Authentication):

import requests

# مفتاح API في الترويسة — API key in header
headers = {
    "Authorization": "Bearer my-secret-token",
    "Accept": "application/json",
    "Accept-Language": "ar"
}

response = requests.get(
    "https://api.example.com/profile",
    headers=headers
)

main.go

import json

# محاكاة طلب بترويسات — Simulated request with headers
def make_request(headers, endpoint):
    """محاكاة إرسال طلب — Simulate sending a request"""
    # نتحقق من وجود توكن المصادقة — Check for auth token
    auth = headers.get("Authorization", "")
    
    if not auth.startswith("Bearer "):
        # لا توكن — استجابة 401 — No token — 401 response
        return json.loads('{"error": "غير مصرح", "status": 401}')
    
    # توكن موجود — استجابة ناجحة — Token present — success response
    return json.loads('{"user": "أحمد", "role": "مطور", "status": 200}')

# طلب بدون توكن — Request without token
resp1 = make_request({}, "/profile")
print(f"بدون توكن: {resp1['error']} ({resp1['status']})")

# طلب مع توكن — Request with token
resp2 = make_request({"Authorization": "Bearer abc123"}, "/profile")
print(f"مع توكن: {resp2['user']} — {resp2['role']} ({resp2['status']})")

Output:

طلب POST — إرسال البيانات

POST يُستخدم لإنشاء موارد جديدة أو إرسال بيانات للمعالجة. الفرق الرئيسي عن GET أنه يحمل جسماً (body):

import requests

# إنشاء مستخدم جديد — Create a new user
new_user = {
    "name": "فاطمة",
    "email": "[email protected]",
    "role": "مطورة"
}

# json= يُحوّل dict إلى JSON ويضبط Content-Type تلقائياً
# json= converts dict to JSON and sets Content-Type automatically
response = requests.post(
    "https://api.example.com/users",
    json=new_user,
    headers={"Authorization": "Bearer my-token"}
)

if response.status_code == 201:
    created = response.json()
    print(f"أُنشئ المستخدم: {created['id']}")

main.go

import json

# محاكاة POST لإنشاء مستخدم — Simulate POST to create a user
def post_create_user(payload_str):
    """محاكاة نقطة نهاية POST /users — Simulate POST /users endpoint"""
    data = json.loads(payload_str)
    
    # تحقق بسيط — Simple validation
    if not data.get("name"):
        return {"error": "الاسم مطلوب", "status": 400}
    if not data.get("email"):
        return {"error": "البريد مطلوب", "status": 400}
    
    # إنشاء المستخدم — Create the user
    return {
        "id": 42,
        "name": data["name"],
        "email": data["email"],
        "status": 201
    }

# طلب ناجح — Successful request
result = post_create_user('{"name": "فاطمة", "email": "fatima@example.com"}')
print(f"تم الإنشاء: id={result['id']}, الاسم={result['name']} ({result['status']})")

# طلب ناقص — Incomplete request
result2 = post_create_user('{"name": "علي"}')
print(f"خطأ: {result2['error']} ({result2['status']})")

Output:

رموز حالة HTTP — Status Codes

رموز الحالة هي لغة الخوادم — كل رمز يخبرك بما حدث:

الرمز	المعنى	متى يظهر
200	OK — ناجح	GET أو PUT نجح
201	Created — أُنشئ	POST أنشأ موردًا
400	Bad Request — طلب سيء	بيانات ناقصة أو خاطئة
401	Unauthorized — غير مصرح	لا توكن أو توكن منتهٍ
403	Forbidden — محظور	لا صلاحية كافية
404	Not Found — غير موجود	المورد غير موجود
422	Unprocessable — لا يمكن معالجته	البيانات غير صالحة منطقياً
500	Server Error — خطأ في الخادم	خطأ داخلي في الخادم

import requests

response = requests.get("https://api.example.com/users/99999")

# تحقق من نجاح الطلب — Check if request succeeded
if response.status_code == 200:
    print("نجح الطلب")
elif response.status_code == 404:
    print("المستخدم غير موجود")
elif response.status_code >= 500:
    print("خطأ في الخادم — حاول لاحقاً")

# أو أبسط: raise_for_status تُولّد استثناءً عند فشل الطلب
response.raise_for_status()   # HTTPError إذا status >= 400

الجلسات — Sessions

عندما تُرسل عدة طلبات لنفس الخادم، Session تُحسّن الأداء وتحتفظ بالإعدادات المشتركة:

import requests

session = requests.Session()

# ضبط مرة واحدة — Set once
session.headers.update({
    "Authorization": "Bearer my-token",
    "Accept": "application/json"
})

# كل الطلبات ترث الإعدادات — All requests inherit settings
users = session.get("https://api.example.com/users").json()
products = session.get("https://api.example.com/products").json()

main.go

import json

# محاكاة جلسة مصادقة — Simulated auth session
class FakeSession:
    """محاكاة Session بإعدادات مشتركة — Simulate Session with shared settings"""
    
    def __init__(self):
        self.headers = {}
        self.base_url = "https://api.example.com"
    
    def get(self, path):
        """محاكاة طلب GET — Simulate GET request"""
        auth = self.headers.get("Authorization", "")
        if not auth:
            return json.loads('{"error": "غير مصرح", "status": 401}')
        
        # استجابات حسب المسار — Responses by path
        responses = {
            "/users": '[{"id":1,"name":"أحمد"},{"id":2,"name":"فاطمة"}]',
            "/products": '[{"id":1,"name":"كتاب"},{"id":2,"name":"قلم"}]'
        }
        return json.loads(responses.get(path, '{"error": "غير موجود", "status": 404}'))

session = FakeSession()
session.headers["Authorization"] = "Bearer token123"

users = session.get("/users")
products = session.get("/products")

print(f"عدد المستخدمين: {len(users)}")
print(f"عدد المنتجات: {len(products)}")
print(f"أول مستخدم: {users[0]['name']}")
print(f"أول منتج: {products[0]['name']}")

Output:

خلاصة

مكتبة requests تجعل التعامل مع HTTP بديهياً في Python. اتقان قراءة وتحليل JSON هو المهارة الأساسية — سواء كنت تبني عميل API أو تختبر خادمك. في الدرس القادم، ستنقلب الأدوار: ستبني الخادم الذي يرد على هذه الطلبات.

تحدي — Challenge

import json

# استجابة من خادم API — Response from API server
raw = '{"status": 200, "name": "محمد", "city": "جدة", "job": "مطور ويب"}'

# حلّل الاستجابة واطبع المعلومات بالتنسيق التالي:
# Parse the response and print info in this format:
# الرمز: 200
# الاسم: محمد
# المدينة: جدة
# العمل: مطور ويب

# اكتب الكود هنا — Write your code here