مسألة سحب البيانات

في هذا التمرين ستتعلّم إرسال طلبات HTTP عبر الإنترنت باستعمال مكتبة requests، ثم تطبّق ذلك على واجهة برمجية تختارها بنفسك. اقرأ الأقسام بالترتيب، شغّل الخلايا واقرأ المخرجات، ثم انتقل إلى المسألة في القسم الأخير.

أضِف المكتبة إلى بيئتك (مثلاً بـ uv add requests أو pip install requests)، ثم استوردها في الخلية التالية.

# !uv add requests

import requests

1. مثال: PoetryDB

في هذا القسم طلب بسيط إلى خدمة شِعر جاهزة؛ شغّل الخلايا وتابع كيف تتحوّل الاستجابة إلى بيانات بايثون (json).

response = requests.get("https://poetrydb.org/author/Emily Dickinson/title")

data = response.json()
print(data)

response = requests.get("https://poetrydb.org/author,title/Shakespeare;Sonnet")
data = response.json()
print(data)

2. مثال: تنزيل ملفات من GitHub

يلزمنا GitHub لتحميل الملفات بالنمط التالي:

إن كنا نتصفح الملف على هذا المسار: https://github.com/HassanAlgoz/python/blob/main/book/datasets/students.csv
فوجب تنزيله عبر هذا المسار: https://raw.githubusercontent.com/HassanAlgoz/python/main/book/datasets/students.csv

في المثال التالي نعرّف دالة تحوّل رابط صفحة GitHub (عرض المتصفّح) إلى رابط raw مناسب للتنزيل. نفّذ الخلايا واقرأ المسارات التي تطبعها الدالة.

from urllib.parse import urlparse

def github_convert_url(url: str) -> str:
    parsed = urlparse(url)
    if "githubusercontent" in parsed.hostname:
        return url
    x = parsed.path.lstrip("https://github.com/")
    x = x.replace("/blob", "")
    print(x)
    x = "https://raw.githubusercontent.com/" + x
    return x

ثم نعرّف دالة ترسل الطلب بعد تحويل الرابط إلى صيغة raw المناسبة:

def github_request_file(url: str):
    x = github_convert_url(url)
    return requests.get(x)

response1 = github_request_file(
    url="https://github.com/HassanAlgoz/python/blob/main/book/datasets/students.csv"
)

print(response1.text)

ونفس النتيجة لو جربنا بالرابط المباشر للتنزيل، لأننا تعاملنا مع هذه الحالة:

response2 = github_request_file(
    url="https://raw.githubusercontent.com/HassanAlgoz/python/main/book/datasets/students.csv"
)

print(response2.text)

3. مثال: طلب صور من موقع القطط

هنا نطلب JSON يصف صورة عشوائية؛ يمكن تشغيل المثال بدون مفتاح ضمن حدود الخدمة، أو تعيين المتغير البيئي CAT_API_KEY إن وفّرت مفتاحًا من الموقع.

import os

# الطلب يعمل بدون مفتاح ضمن حدود معيّنة؛ إن رغبت بمفتاح مجاني راجع https://thecatapi.com/
headers = {}
if key := os.environ.get("CAT_API_KEY"):
    headers["x-api-key"] = key

response = requests.get(
    url="https://api.thecatapi.com/v1/images/search",
    headers=headers,
)

print(response.text)

data = response.json()
data[0]["url"]

from IPython.display import Image, display

# display(Image(url=data[0]["url"]))

4. المسألة: التطبيق على إحدى الواجهات البرمجية

اختر واجهة برمجية واحدة وحقّق بها مهمة واحدة واضحة (مثلاً: جلب بيانات، أو بحث، أو صورة). في موقع المزوّد ابحث عن API Documentation أو Developers أو Quick Start؛ هناك تجد نقاط الالتقاء (Endpoints) والمعاملات المطلوبة.

استعمل إحدى الواجهات التالية (أو واجهة أخرى بموافقة المدرّس):

قائمة أوسع (قد يتعطّل بعضها): public-apis.

للبحث عن فكرة: اكتب في محرك البحث ما تريد إنجازه + API؛ مثلاً Google Maps API.

ملاحظة: قد تحتاج تسجيلًا للحصول على مفتاح، أو رصيدًا مدفوعًا — كل ذلك يُبيّن في مرجع المزوّد.

# طلباتك إلى الواجهة التي اخترتها، ثم معالجة الاستجابة (json() أو .text)
pass  # اكتب هنا