كورس مصغر: تحويل أي سكربت بايثون إلى API باستخدام FastAPI

كورس مصغر: تحويل أي سكربت بايثون إلى API باستخدام FastAPI

الكلمات المفتاحية الرئيسية: تحويل سكربت FastAPI، تحويل سكربت بايثون إلى API، FastAPI للمبتدئين

في كثير من الأحيان نكتب سكربتات بايثون صغيرة لحساب شيء ما، معالجة ملف، أو تنفيذ مهمة معينة، ثم نكتشف أننا نريد استخدامها من أماكن أخرى: من موقع ويب، من تطبيق موبايل، أو حتى من سكربتات أخرى على سيرفرات مختلفة. هنا تأتي فكرة تحويل السكربت إلى API.

في هذا الكورس المصغر سنشرح خطوة بخطوة كيفية تحويل أي سكربت بايثون بسيط إلى API باستخدام FastAPI، مع توضيح المسارات (Endpoints)، المعاملات (Parameters)، وطريقة التشغيل محلياً. الهدف أن تخرج في النهاية بقالب جاهز تقدر تعيد استخدامه في أي مشروع.

لماذا FastAPI بالذات لتحويل السكربت إلى API؟

مكتبة FastAPI أصبحت من أشهر الأطر في بايثون لبناء RESTful APIs لعدة أسباب:

  • سرعة عالية في التنفيذ مقارنة بكثير من أطر بايثون الأخرى.
  • كتابة بسيطة جداً قريبة من كتابة سكربت بايثون عادي.
  • توفر توثيق تلقائي للـ API عبر Swagger UI.
  • تتكامل بسهولة مع async / await لتحسين الأداء.

إن كنت مهتماً ببناء REST APIs متقدمة باستخدام FastAPI يمكن الرجوع لاحقاً إلى هذا الشرح المفصل: بناء RESTful APIs باستخدام FastAPI.

المتطلبات الأساسية قبل البدء

قبل أن نبدأ في تحويل السكربت، تأكد من:

  • تنصيب Python 3.8+ على جهازك.
  • معرفة أساسية جداً بطريقة كتابة سكربتات بايثون (متغيرات، دوال، استيراد مكتبات).
  • معرفة تشغيل أوامر بسيطة في الـ Terminal أو الـ Command Prompt.

لو ما زلت في بداية طريقك مع بايثون، يمكنك الرجوع لمسار واضح للتعلم من هنا: مسار تعلم لغة بايثون من الصفر خطوة بخطوة.

الخطوة 1: فهم سكربت بايثون الذي نريد تحويله

لنبدأ بمثال بسيط، نفترض أن لدينا سكربت بايثون اسمه calculator.py يقوم بعملية جمع عددين:

# الملف: calculator.py

def add_numbers(a, b):
    return a + b

if __name__ == "__main__":
    x = float(input("أدخل الرقم الأول: "))
    y = float(input("أدخل الرقم الثاني: "))
    result = add_numbers(x, y)
    print("النتيجة:", result)

هذا السكربت يعمل من الـ Terminal فقط، يسأل المستخدم عن الأرقام ويطبع النتيجة. هدفنا الآن:

  • نجعل دالة add_numbers متاحة كـ API Endpoint.
  • بدل ما نكتب الأرقام في الـ Terminal، نرسلها كـ معاملات (Parameters) في طلب HTTP.

الخطوة 2: إنشاء مشروع FastAPI أساسي

1. إنشاء مجلد المشروع وبيئة عمل

أنشئ مجلد جديد مثلاً:

mkdir fastapi-calculator
cd fastapi-calculator

يفضل إنشاء بيئة عمل افتراضية (اختياري لكنه مستحسن):

python -m venv venv
# تفعيلها على ويندوز
venv\Scripts\activate
# تفعيلها على لينكس / ماك
source venv/bin/activate

2. تثبيت FastAPI و Uvicorn

قم بتنصيب الحزم المطلوبة:

pip install fastapi uvicorn

مكتبة FastAPI لإنشاء الـ API، وUvicorn هو خادم ASGI لتشغيل التطبيق.

3. إنشاء ملف التطبيق main.py

سننشئ الآن ملف جديد باسم main.py في نفس المجلد:

# الملف: main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "أهلاً بك في API التجريبية باستخدام FastAPI"}

هذا أبسط تطبيق FastAPI: فيه مسار واحد / يعيد رسالة ترحيبية.

الخطوة 3: تشغيل FastAPI لأول مرة

لتشغيل التطبيق، استخدم الأمر التالي داخل مجلد المشروع:

uvicorn main:app --reload
  • main هو اسم ملف بايثون (بدون امتداد .py).
  • app هو اسم كائن FastAPI الذي أنشأناه.
  • --reload تجعل السيرفر يعيد التشغيل تلقائياً عند تعديل الكود.

الآن افتح المتصفح على العنوان:

http://127.0.0.1:8000/

سترى رسالة JSON مثل:

{"message": "أهلاً بك في API التجريبية باستخدام FastAPI"}

كما يمكنك رؤية التوثيق التلقائي للـ API من خلال:

الخطوة 4: تحويل دالة السكربت إلى API Endpoint

الآن نريد نقل دالة add_numbers من calculator.py إلى مشروع FastAPI، أو على الأقل استيرادها.

1. إعادة تنظيم السكربت الأصلي

ضع ملف calculator.py بجانب main.py في نفس المجلد، واحذف الجزء الخاص بـ input و print لأننا سنستبدله بـ API:

# الملف: calculator.py

def add_numbers(a: float, b: float) -> float:
    return a + b

إضافة الـ Type Hints (float) مفيدة جداً مع FastAPI لأنها تساعد في إنشاء توثيق واضح وفي التحقق من المدخلات.

2. إنشاء مسار (Endpoint) يستخدم هذه الدالة

نعدّل ملف main.py ليصبح كالتالي:

# الملف: main.py

from fastapi import FastAPI
from calculator import add_numbers  # استيراد الدالة من السكربت الأصلي

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "أهلاً بك في API التجريبية باستخدام FastAPI"}

@app.get("/add")
def add(a: float, b: float):
    result = add_numbers(a, b)
    return {"a": a, "b": b, "result": result}

ما الذي حدث هنا؟

  • أنشأنا مسار جديد باسم /add.
  • المسار يستخدم الطريقة GET بديهة.
  • يستقبل معاملين في دالة add هما a و b من نوع float.
  • FastAPI تلقائياً سيفهم أن a و b هما Query Parameters في الرابط.

3. تجربة الـ Endpoint الجديد

مع تشغيل السيرفر كما في السابق، افتح في المتصفح:

http://127.0.0.1:8000/add?a=10&b=20

ستحصل على استجابة JSON مثل:

{
  "a": 10.0,
  "b": 20.0,
  "result": 30.0
}

بهذا الشكل نكون حولنا دالة بسيطة في سكربت بايثون إلى API حقيقية قابلة للاستخدام من مشاريع أخرى.

الخطوة 5: فهم أنواع المعاملات في FastAPI

عند تحويل سكربت FastAPI من مجرد كود داخلي إلى API، تحتاج أن تختار كيف يستقبل الـ API البيانات. FastAPI يوفر عدة طرق:

1. Query Parameters (في رابط URL)

مثل المثال السابق: /add?a=10&b=20. هذه الطريقة مناسبة:

  • للمعاملات البسيطة (أرقام، نصوص قصيرة).
  • عند استخدام طريقة GET.

2. Path Parameters (جزء من المسار نفسه)

يمكنك جعل الأرقام جزءاً من الرابط، مثل:

@app.get("/add/{a}/{b}")
def add_path(a: float, b: float):
    return {"a": a, "b": b, "result": add_numbers(a, b)}

ثم تجربته هكذا:

http://127.0.0.1:8000/add/10/20

3. Body Parameters (إرسال JSON مع الطلب)

عندما يكون السكربت يستقبل بيانات معقدة (قوائم، قواميس، إعدادات كثيرة)، الأفضل إرسالها في الـ Body بصيغة JSON.

مثال: سنعرّف نموذج بيانات باستخدام Pydantic:

pip install pydantic

from fastapi import FastAPI
from pydantic import BaseModel
from calculator import add_numbers

app = FastAPI()

class AddRequest(BaseModel):
    a: float
    b: float

@app.post("/add-body")
def add_body(data: AddRequest):
    result = add_numbers(data.a, data.b)
    return {"a": data.a, "b": data.b, "result": result}

هنا نستخدم POST بدلاً من GET، ونرسل JSON مثل:

{
  "a": 10,
  "b": 20
}

يمكنك تجربة ذلك بسهولة من صفحة Swagger UI على: /docs حيث يوفر FastAPI واجهة تفاعلية لإرسال الطلبات.

الخطوة 6: تحويل سكربتات أكثر تعقيداً

في الواقع، السكربتات غالباً لا تتوقف عند عملية جمع بسيطة. قد يكون لديك سكربت:

  • يعالج ملف (مثل CSV أو صورة).
  • يشغل نموذج تعلم آلي.
  • يجري عمليات حسابية معقدة أو يحسب إحصائيات.

المبدأ لا يتغير: أهم شيء أن تعزل منطق العمل في دوال واضحة، ثم تناديها من مسارات FastAPI. على سبيل المثال، تحويل نموذج تعلم آلي إلى API تم شرحه بشكل موسع هنا: تحويل نماذج التعلم الآلي إلى API قابل للنشر باستخدام FastAPI.

نموذج مصغر لمعالجة نص

افترض أن لديك سكربت يحسب طول نص معين:

# text_utils.py

def text_length(text: str) -> int:
    return len(text)

يمكنك تحويله إلى API بهذه البساطة:

# main.py

from fastapi import FastAPI
from pydantic import BaseModel
from text_utils import text_length

app = FastAPI()

class TextRequest(BaseModel):
    text: str

@app.post("/text-length")
def get_text_length(data: TextRequest):
    length = text_length(data.text)
    return {"text": data.text, "length": length}

الخطوة 7: تشغيل السكربت القديم والـ API معاً (إن لزم)

أحياناً تريد الاحتفاظ بإمكانية تشغيل السكربت من سطر الأوامر، بالإضافة إلى الـ API. يمكنك فعل ذلك بوضع منطق الدوال في ملف، وتشغيل كل من:

  • ملف خاص لتطبيق FastAPI (مثل main.py).
  • وملف منفصل لسطر الأوامر (مثل cli.py) يستدعي نفس الدوال.

مثال سريع:

# calculator.py

def add_numbers(a: float, b: float) -> float:
    return a + b

# cli.py

from calculator import add_numbers

if __name__ == "__main__":
    x = float(input("أدخل الرقم الأول: "))
    y = float(input("أدخل الرقم الثاني: "))
    print("النتيجة:", add_numbers(x, y))

# main.py (FastAPI)

from fastapi import FastAPI
from calculator import add_numbers

app = FastAPI()

@app.get("/add")
def add(a: float, b: float):
    return {"result": add_numbers(a, b)}

بهذا الشكل تفصل بين:

  • منطق العمل في ملف مستقل (calculator.py).
  • واجهة سطر الأوامر في ملف (cli.py).
  • واجهة الويب / الـ API في ملف (main.py).

الخطوة 8: تجهيز الـ API للنشر مستقبلاً

في هذا الكورس المصغر ركزنا على كيفية تحويل سكربت FastAPI خطوة بخطوة للتشغيل محلياً. لكن غالباً سترغب لاحقاً في نشر الـ API على:

  • سيرفر VPS.
  • أو داخل Container باستخدام Docker.

يمكنك الانتقال لاحقاً لشرح مفصل عن نشر مشاريع Django و FastAPI على VPS باستخدام Docker Compose من هنا: نشر مشاريع Django و FastAPI على VPS باستخدام Docker Compose خطوة بخطوة.

نقاط مهمة عند تحويل أي سكربت بايثون إلى API

  • فصل المنطق عن الواجهة: ضع الحسابات أو المعالجة في دوال مستقلة يمكن استيرادها بسهولة.
  • تحديد نوع المدخلات والمخرجات: استخدم Type Hints (int, float, str, list...) ليسهل على FastAPI توليد التوثيق.
  • اختيار نوع المعاملات المناسب:
    • Query Parameters للمدخلات البسيطة.
    • Body Parameters (JSON) للبيانات المعقدة.
    • Path Parameters عندما تكون البيانات جزء من هيكل الرابط.
  • التجربة من خلال Swagger UI: قبل كتابة أي عميل (Frontend أو موبايل)، جرب الـ API من /docs.
  • التعامل مع الأخطاء: لاحقاً يمكنك استخدام HTTPException من FastAPI لإرجاع أكواد أخطاء مناسبة (400، 404، 500...).

خلاصة الكورس المصغر

تحويل أي سكربت بايثون إلى API باستخدام FastAPI ليس معقداً كما يبدو. الخطوات الأساسية:

  1. تأكد من أن منطق السكربت مكتوب داخل دوال واضحة.
  2. أنشئ تطبيق FastAPI في ملف main.py وأنشئ كائن app = FastAPI().
  3. استورد دوال السكربت داخل ملف FastAPI.
  4. عرّف مسارات (Endpoints) باستخدام @app.get أو @app.post… إلخ.
  5. مرر المدخلات إلى الدوال عبر Parameters (Query, Path, Body).
  6. شغّل التطبيق باستخدام Uvicorn، ثم جرّب من المتصفح أو Swagger UI.

بعد إتقان هذه الخطوات البسيطة يمكنك تحويل أغلب سكربتاتك الصغيرة إلى خدمات ويب قابلة للاستخدام في أي مشروع آخر، سواء كان موقع، تطبيق موبايل، أو حتى أنظمة داخلية بين السيرفرات.

إن كنت تريد خطوة إضافية بعد هذا الكورس المصغر، يمكنك استكشاف بناء تطبيق ويب كامل باستخدام نفس التقنية في مقال: بناء أول موقع باستخدام FastAPI.

بهذا تكون قد امتلكت أساس قوي لتجاوز مرحلة السكربتات المحلية إلى عالم الـ APIs والخدمات القابلة للنشر.

حول المحتوى:

شرح واضح خطوة بخطوة لتحويل سكربت بايثون بسيط إلى API جاهز للاستخدام، مع شرح المسارات، المعاملات، والتشغيل.

هل كان هذا مفيدًا لك؟

أضف تعليقك