البرمجة: Flask

دليل بناء بوت تفاعلي على تيليجرام خطوة بخطوة

Mon, 24 Mar 2025 12:00:00 +0000

تليجرام من أشهر تطبيقات التراسل الفوري لديها عدد كبير من المستخدمين توفر مزايا كبيرة للمستخدمين والمطورين، أهمها برنامج الرد الآلي بوت Bot الذي يوفر واجهة بسيطة وسهلة للمستخدمين لاستقبال الرسائل منهم وأتمتة المهام برمجيًا.

توفر المنصة للمطورين واجهة برمجة تطبيقات بوت تلجرام Telegram Bot API، من خلالها يمكن استقبال الرسائل وتحليلها والرد عليها و إرسال إشعارات أو تنفيذ المهام برمجية.

في هذا المقال سننشئ بوت تليجرام باستخدام بايثون Python وإطار العمل فلاسك Flask يعرض صورة رمزية مصغرة avatar من موقع Adorable Avatars، وسننشره على Heroku.

تطوير تطبيق البوت

سنستخدم بيئة عمل افتراضية ضمن بايثون يمكن الرجوع إلى المقال إعداد بيئة العمل للمشاريع مع بايثون، لمعرفة الخطوات، وسنحتاج للأمور التالية:

تثبيت نسخة بايثون python ومعرفة أساسيات البرمجة باستخدام بايثون.
تثبيت نظام التحكم بالإصدارات Git ومعرفة أساسيات التعامل معه
معرفة بأساسيات التعامل مع إطار العمل فلاسك Flask
وجود حساب على تليجرام

إنشاء بوت تليجرام جديد

من حساب تليجرام وباستخدام بوت إدارة البوتات BotFather الذي يوفره لنا تيليجرام يمكن إنشاء بوت جديد وتعديل جميع خصائصه كالصورة الشخصية له أو وصف البوت أو تغيير رمز الوصول، وحتى حذف البوت.

لإنشاء بوت جديد نستخدم الأمر newbot/ ليسألنا بعده عن تحديد اسم البوت الجديد سيظهر للمستخدمين واختيار اسم المستخدم له والذي يجب أن ينتهي بكلمة bot.

سنحصل بعدها على رمز الوصول Access Token الخاص بالبوت الجديد، ومن الضروري الاحتفاظ بهذا الرمز وباسم المستخدم الذي اخترناه لاستخدامهما لاحقًا.

إعداد المشروع في بايثون

نُنشئ بيئة عمل افتراضية جديدة لعزل متطلبات مشروعنا عن البيئة العامة للغة بايثون ونفعّلها ضمن مجلد اسمه botenv (يمكن اختيار أي اسم آخر) سيحتوي على جميع مكتبات بايثون التي سنستخدمها بتنفيذ الأوامر:

python -m venv botenv/
botenv/bin/activate

سنحتاج للمكتبات التالية لبرمجة البوت:

إطار عمل flask لبناء تطبيقات الويب
مكتبة بايثون python-telegram-bot توفر واجهة برمجية لتليجرام
مكتبة بايثون requests الشهيرة للتعامل مع طلبات HTTP

ننزلها باستخدام الأمر pip install ونثبتها ضمن الملف requirements.txt بالاستعانة بالأمر pip freeze ليتمكن خادم البوت من تحضريها بعد نشر البوت، وذلك بتنفيذ الأوامر التالية داخل مجلد المشروع:

pip install flask python-telegram-bot requests
pip freeze > requirements.txt

ستكون هيكلة الملفات فى مجلد مشروعنا كالتالي::

app.py : يحوي الشيفرة الرئيسية لعمل البوت
telebot/ : مجلد يحتوي على الملفات الخاصة بالبوت
credentials.py : نخزن في هذا الملف المتغيرات الحساسة كاسم المستخدم ورمز الوصول
init.py : ملف خاص في بايثون يحدد أن المجلد الذي يحتوي عليه هو حزمة Package

├── app.py 
├── telebot 
│   ├── credentials.py 
│   |   . 
│   |   you can build your engine here 
│   |   . 
│   └── __init__.py 
└── botenv

نضيف في الملف credentials.py المتغيرات التي حصلنا عليها أثناء إنشاء البوت في BotFather واللازمة للاستيثاق Authentication أثناء التعامل مع واجهة تيليجرام البرمجية للبوتات، كما يجب تعريف عنوان النطاق لخادم البوت الذي يمكن تبديله لاحقًا بعد إعداد خادم استضافة البوت:

bot_token = "رمز الوصول الخاص بالبوت الجديد" 
bot_user_name = "اسم المستخدم للبوت الجديد"
URL = "عنوان نطاق خادم البوت"

ضمن ملف التطبيق الرئيس app.py نستورد المكتبات التي سنحتاجها، وننشئ الكائن bot من مكتبة python-telegram-bot للتفاعل مع البوت عبر الواجهة البرمجية، وننشئ الكائن app من مكتبة flask لتعريف التطبيق:

# استيراد المكتبات
from flask import Flask, request 
import telegram from telebot.credentials 
import bot_token, bot_user_name, URL # متغيرات سنستخدمها لاحقًا

global bot 
global TOKEN 
TOKEN = bot_token # رمز الوصول
bot = telegram.Bot(token=TOKEN) # كائن للتفاعل مع البوت
app = Flask(__name__) # كائن تطبيق الويب

##
## سنضيف موجهات التطبيق هنا
##

if __name__ == '__main__':
    app.run(threaded=True)

تعريف موجهات التطبيق

نعرف موجه Route من الشكل {token}/ سيستدعيه تيليجرام لكل رسالة جديدة تُرسل للبوت وفيه سنستخرج محتوى الرسالة ونرد عليها، فإذا كان نصها أمر البدء start/ وهو زر افتراضي يظهر للمستخدمين في أول مرة يتعاملون فيها مع أي بوت سنرسل رسالة ترحيب وشرح للمستخدم عن ما يفعله هذا البوت.

أما إذا كانت رسالة عادية فنستخرج من نصّها الأحرف والأرقام فقط لإنشاء رابط للصورة المقابلة للنص الذي أرسلة المستخدم عبر الواجهة البرمجية للموقع adorable.io ونرسل تلك الصورة للمستخدم عبر البوت.

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

# موجه استقبال الرسائل
@app.route('/{}'.format(TOKEN), methods=['POST'])
def respond():
   # تحويل جسم الطلب الوارد إلى كائن تلغرام
   update = telegram.Update.de_json(request.get_json(force=True), bot)

   chat_id = update.message.chat.id
   msg_id = update.message.message_id

   # استخراج نص الرسالة القادمة
   text = update.message.text.encode('utf-8').decode()

   print("got text message :", text)

   # إرسال رسالة ترحيب عند بدء المستخدم التفاعل مع البوت
   if text == "/start":
       # رسالة الترحيب
       bot_welcome = """
       مرحبًا بك، أرسل لي اسمك وسأولد لك صورة شخصية مناسبة
       """
       # إرسال الرسالة
       bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

   else:
       try:
           # استخراج الأحرف والأرقام من نص الرسالة
           text = re.sub(r"\W", "_", text)
           # إنشاء رابط الصورة بناءًا على الرسالة
           url = "https://api.adorable.io/avatars/285/{}.png".format(text.strip())
           # إرسال الصورة للمستخدم
           bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)
       except Exception:
           # إرسال رسالة في حالة حدوث خطأ من طرفنا
           bot.sendMessage(chat_id=chat_id, text="حدث خطأ، جرب اسمًا آخر لأولد لك صورة مقابله", reply_to_message_id=msg_id)

   return 'ok'

يمكننا الاستعلام عن الرسائل الجديدة الواردة للبوت عبر دالة من الواجهة البرمجية API في فترات زمنية ثابتة، ولكن يتيح تيلجرام طريقة أسهل عبر خطافات الويب Webhooks، فبدلًا من إرسال طلبات للسؤال من طرفنا سيعلمنا تيلجرام بالرسائل الجديدة عبر إرسال طلب من النوع POST لخادمنا يتضمن معلومات عن الرسالة.

يجب إعلام تيليجرام ولمرة واحدة بالرابط المحدد ضمن تطبيقنا لإرسال إشعارات بالرسائل الجديدة إليه، لذا سننشئ موجه جديد سنستدعيه يدويًا لمرة واحدة يستدعي بدوره الدالة setWebhook لإعداد الخطاف كالتالي:

@app.route('/setwebhook', methods=['GET', 'POST'])
def set_webhook():
    # إخبار تيليجرام برابط الخطاف في تطبيقنا
    s = bot.setWebhook('{URL}/{TOKEN}'.format(URL=URL, TOKEN=TOKEN))

    # فحص إتمام العملية بنجاح
    if s:
        return "تم إعداد الخطاف بنجاح"
    else:
        return "فشلت عملية إعداد الخطاف"

أصبح بذلك تطبيق البوت جاهزًا وبقي نشره على الخادم ثم الذهاب لموجه إعداد الخطاف ليبدأ البوت بالعمل، وبذلك يصبح محتوى ملف app.py كاملًا كالتالي:

# استيراد المكتبات
from flask import Flask, request 
import telegram from telebot.credentials 
import bot_token, bot_user_name, URL  

global bot 
global TOKEN 
TOKEN = bot_token # رمز الوصول
bot = telegram.Bot(token=TOKEN) # كائن للتفاعل مع البوت

app = Flask(__name__)

# موجه تلقي الاشعارات
@app.route('/{}'.format(TOKEN), methods=['POST'])
def respond():
   # تحويل جسم الطلب الوارد إلى كائن تلغرام
   update = telegram.Update.de_json(request.get_json(force=True), bot)

   chat_id = update.message.chat.id
   msg_id = update.message.message_id

   # استخراج نص الرسالة القادمة
   text = update.message.text.encode('utf-8').decode()

   print("got text message :", text)

   # إرسال رسالة ترحيب عند بدء المستخدم التفاعل مع البوت
   if text == "/start":
       # رسالة الترحيب
       bot_welcome = """
       مرحبًا بك، أرسل لي اسمك وسأولد لك صورة شخصية مناسبة
       """
       # إرسال الرسالة
       bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

   else:
       try:
           # استخراج الأحرف والأرقام من نص الرسالة
           text = re.sub(r"\W", "_", text)
           # إنشاء رابط الصورة بناءًا على الرسالة
           url = "https://api.adorable.io/avatars/285/{}.png".format(text.strip())
           # إرسال الصورة للمستخدم
           bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)
       except Exception:
           # إرسال رسالة في حالة حدوث خطأ من طرفنا
           bot.sendMessage(chat_id=chat_id, text="حدث خطأ، جرب اسمًا آخر لأولد لك صورة مقابله", reply_to_message_id=msg_id)

   return 'ok'

# موجه إعداد الخطاف
@app.route('/setwebhook', methods=['GET', 'POST'])
def set_webhook():
    # إخبار تيليجرام برابط الخطاف في تطبيقنا
    s = bot.setWebhook('{URL}/{TOKEN}'.format(URL=URL, TOKEN=TOKEN))

    # فحص إتمام العملية بنجاح
    if s:
        return "تم إعداد الخطاف بنجاح"
    else:
        return "فشلت عملية إعداد الخطاف"

if __name__ == '__main__':
   app.run(threaded=True)

تحضير خادم Heroku ونشر البوت

يمكن استضافة البوت في أي منصة توفر خوادم ببيئة بايثون وسنستخدم في هذا المقال منصة هيروكو Heroku لإنشاء الخادم ونشر التطبيق عليه، وتأكد أولًا من تثبيت أداة سطر الأوامر الخاصة بالمنصة Heroku CLI والتي سنستخدمها لتسجيل الدخول ونشر المشروع على المنصة.

نبدأ بإنشاء ملف جديد بالاسم Procfile وهو ملف خاص بمنصة هيروكو نعرّف فيه بطريقة تشغيل التطبيق بإضافة السطر التالي:

web: gunicorn app:app

نذهب لحسابنا على المنصة ومن لوحة التحكم Dashboard وننشئ تطبيق جديد بالضغط على Create new app بعدها سيعاد توجيهنا إلى صفحة النشر Deploy page، وفيها ننتقل لعلامة التبويب Settings وننسخ رابط نطاق التطبيق Domain ونضعه ضمن الملف credentials.py كقيمة للمتغير URL.

نعود لمجلد المشروع وننفذ ضمن الطرفية أمر تسجيل الدخول إلى المنصة كالتالي:

heroku login -i

تحضير مستودع Git

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

git init
git add . 
git commit -m "first commit"
heroku git:remote -a {اسم-المشروع}

يمكن أيضًا إضافة ملف gitignore. إلى مجلد الجذر للمشروع قبل الدفع كي لا تُرفع الملفات الغير مستخدمة إلى المستودع وضمن الخادم.

نشر المشروع

نحتاج فقط لدفع تغييرات مستودع المشروع في كل مرة نعدل فيها على التطبيق، وذلك بدفع الفرع الحالي بتنفيذ الامر:

git push heroku master

ستظهر رسائل تقدم البناء في الطرفية terminal وفي حال عدم وجود مشاكل سنرى خرج مشابه للتالي عند انتهائها سيكون التطبيق تم رفعه ونشره وأصبح جاهز للاستخدام:

remote: -----> Launching...
remote:        Released v6
remote:        https://project-name.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.

إعداد الخطاف Webhook

جهزنا سابقًا رابط ضمن التطبيق لإعداد الخطاف للبوت مع تيليجرام يجب نزوره لمرة واحدة ضمن المتصفح لإتمام الإعداد عندها ستظهر رسالة النجاح تم إعداد الخطاف بنجاح يصبح بعدها البوت جاهزًا للتحدث معه، وهو عنوان نطاق التطبيق على المنصة مضافًا في نهايته setwebhook/ ويكون مشابهًا للتالي:

https://appname.herokuapp.com/setwebhook

تجربة البوت

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

إضافة ميزات للبوت

يمكن إضافة أي مزايا جديدة لاحقًا للبوت عبر تعديل الشيفرة ضمن المشروع ودفع التعديلات إلى المنصة، فمثلًا يمكن إضافة ميزة إعلام المستخدم أن البوت يكتب الآن رسالة بإضافة تحديث للحالة قبل سطر إرسال الرسالة كالتالي:

# إعلام المستخدم أن البوت يكتب رسالة
bot.sendChatAction(chat_id=chat_id, action="typing")

# إرسال الرسالة
bot.sendMessage(chat_id=chat_id, text=bot_welcome, reply_to_message_id=msg_id)

#أو أن البوت يرسل لك صورة الآن كي يعلم أن البوت يتفاعل معه بتحديث حالة البوت قبل سطر إرسال الصورة كالتالي
# إعلام المستخدم أن البوت يرسل صورة
bot.sendChatAction(chat_id=chat_id, action="upload_photo")

# إرسال الصورة للمستخدم
bot.sendPhoto(chat_id=chat_id, photo=url, reply_to_message_id=msg_id)

ومثلًا يمكن توليد الردود للبوت عبر الذكاء الاصطناعي، أو أن يستخدم البوت أدوات معينة برمجيا مثلا الاطلاع على حالة الطقس أو الأسعار أو نتائج المباريات ويجيب المستخدم بما يريد، ويمكنك الاطلاع على بوتات أخرى منشورة أو أمثلة عن بوتات تستخدم مزايا مختلفة من تيليجرام مطورة باستخدام بايثون من صفحة python-telegram-bot على GitHub.

الخاتمة

يوفر تيليجرام ميزات غنية وطريقة سهلة لإنشاء بوتات ضمنه تتفاعل مع المستخدمين، شرحنا في هذا المقال خطوات إنشاء بوت تليجرام بلغة بايثون python يعرض صورة رمزية avatar باستخدام إطار عمل فلاسك Flask وبينا طريقة نشره على سيرفر مجاني من Heroku.

ترجمة وبتصرف للمقال Building Your First Telegram Bot: A Step by Step Guide لكاتبه Ali Abdel Aal

تعرف على إطار العمل فلاسك Flask

Sun, 31 Dec 2023 11:07:02 +0000

نعرفك في هذا المقال على إطار عمل تطوير الويب فلاسك Flask وهو إطار عمل صغير الحجم ومنظم ومرن للغاية مبني باستخدام لغة بايثون Python ويعد خيارًا مناسبًا للمبتدئين الذين يبدؤون خطواتهم الأولى في عالم برمجة تطبيقات الويب.

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

ما هو إطار العمل فلاسك Flask

إطار العمل فلاسك Flask هو إطار عمل مفتوح المصدر للغة البرمجة بايثون Python طوره المبرمج النمساوي أرمين روناشر Armin Ronacher عام 2010 كإطار مخصص لتطوير تطبيقات الويب

يتميز فلاسك Flask بكونه إطار ويب مصغر micro web framework وإطار العمل في البرمجة هو عبارة عن مجموعة من المكتبات التي تساعد المبرمجين على إنشاء وتطوير التطبيقات بسرعة أكبر وموثوقية أعلى، ومعنى مصغر هنا هو أنه يتضمن فقط المكتبات والمكونات الأساسية التي يحتاجها المطور من أجل إنشاء تطبيقات ويب بسيطة وسريعة لجعله صغير الحجم ما أمكن، لكنه بذات الوقت إطار مرن وقابل للتوسيع وإضافة مزيد من المكتبات عندما تستدعي الحاجة لتطوير تطبيقات ويب أكثر تعقيدًا.

وعلى سهولته وبساطته فهو يحظى بشعبية وشهرة كبيرة ونال على المرتبة رقم 15 بين أفضل أطر عمل وتقنيات تطوير الويب المستخدمة من قبل المطورين والمبرمجين وفقًا لاستطلاع الرأي الذي أجراه الموقع الشهير ستاك أوفر فلو Stack Overflow لعام 2023 متفوقًا بذلك على أطر عمل ويب مشهورة أخرى مثل إطار جانغو Django وإطار لارافيل Laravel.

استخدامات إطار فلاسك Flask

يستخدم إطار عمل Flask بشكل أساسي من قبل مطوري الويب المختصين بلغة البرمجة بايثون Python وهو يناسب المطورين المبتدئين ويساعدهم على تطوير مواقع وتطبيقات الويب الديناميكية وبشكل محدد أكثر يستخدم فلاسك لتطوير الواجهة الخلفية لمواقع الويب Backend Web Development ولاسيما التطبيقات الصغيرة والمتوسطة التي لا تتضمن الكثير من الوظائف والمهام المعقدة.

هذا لا يعني أن فلاسك Flask لا يصلح لتطوير تطبيقات الويب المعقدة مثل المتاجر الإلكترونية الضخمة أو واجهات برمجة التطبيقات فهو كما ذكرنا سابقًا إطار عمل مرن وقابل للتوسيع أي يمكن لمطور الويب تثبيت أي مكتبات إضافية يحتاجها عندما يحتاج لتضمين مهام أو وظائف متقدمة في موقعه الإلكتروني وتخصيص موقعه كما يشاء.

كما يصلح إطار فلاسك لتطوير تطبيقات ويب لتعلم الآلة ويتيح لك تحميل البيانات ومعالجتها وتدريب الخوارزميات عليها بالاستفادة من قوة مكتبات لغة بايثون التي تعد من أهم لغات برمجة الذكاء الاصطناعي، ويستخدم إطار العمل Flask أيضًا لتطوير واجهة برمجة التطبيقات RESTful التي تتيح الاتصال بين الأنظمة البرمجية المختلفة حيث يوفر مجموعة من المكتبات والأدوات اللازمة للتعامل مع طلبات واستجابات HTTP.

إيجابيات إطار العمل Flask

يعتبر إطار العمل فلاسك واحدًا من أفضل أطر عمل تطوير الواجهات الخلفية للويب الويب ومن أبرز مميزات وإيجابيات فلاسك Flask نذكر:

سهل التعلم والاستخدام ويملك توثيقًا جيدًا ما يجعله مثاليًا للمطورين المبتدئين.
يعتمد على لغة البرمجة بايثون Python التي تعد واحدة من أقوى وأشهر لغات البرمجة وأكثرها تفضيلًا بين المبرمجين.
يوفر العديد من أدوات التصحيح والاختبار التي تسهل عليك تصحيح أخطاء التطبيقات.
صغير الحجم ما يجعله مثاليًا لتطوير مواقع وتطبيقات ويب سريعة وعالية الأداء.
شائع الاستخدام ويتمتع بشهرة كبيرة بين أوساط مطوري الويب ويوفر الكثير من التوثيقات الشاملة ومصادر التعلم.
يستخدم من قبل العديد من الشركات المعروفة مثل Reddit و Netflix.
مرن وقابل للتوسع ويسمح بتثبيت أي عدد من المكتبات الإضافية المعززة لتطوير تطبيقات أكثر تقدمًا.
يستخدم محرك قوالب يسمى جينجا Jinja 2 لعرض أو إخراج عناصر الواجهة الأمامية للموقع المصممة باستخدام HTML و CSS بطريقة ديناميكية ويسهل ربط الواجهة الأمامية لتطبيقات الويب بالواجهة الخلفية.
آمن ويحمي تطبيقات الويب من الاختراق ومن هجمات XSS كما أنه يستخدم ميزة ملفات تعريف الارتباط الآمنة.
يوفر خادم ويب مدمج لاستضافة التطبيق في بيئة التطوير ومصحح أخطاء سريع يسهل اكتشاف الأخطاء، لكن تجدر الملاحظة بأن هذا الخادم مخصص للتطوير فقط وليس لنشر التطبيق فعند النشر عليك استخدام خادم آخر.
يسمح بإنشاء واجهات برمجة تطبيقات RESTful فعالة وصغيرة الحجم.

سلبيات إطار العمل Flask

يعاني إطار العمل فلاسك من بعض جوانب القصور ومن بينها:

لا يوفر فلاسك Flask الكثير من الأدوات والمكتبات المضمنة مما يضطر المطور لإضافة أي مكتبة خارجية يحتاجها يدويًا وهذا قد يتسبب في إبطاء التطبيق في حال كثرة المكتبات الخارجية.
يحتاج المطور في إطار فلاسك لكتابة جميع تعليمات SQL الخاصة بالاتصال بقاعدة البيانات ومعالجة بياناتها والتحقق من صحة بيانات النموذج يدويًا في حين توفر أطر العمل الأخرى هذه الوظائف بشكل مضمن عادة.
قد يصبح استخدام فلاسك Flask صعب التعامل والصيانة عند تطوير تطبيقات كبيرة الحجم ومليئة بالميزات.
لا يوفر فلاسك Flask موقع مدمج لمدير الموقع يمكنه من التعامل مع سجلات قاعدة البيانات بسهولة كما في معظم أطر عمل تطوير الويب الشهيرة الأخرى.

الفرق بين إطار فلاسك Flask وجانغو Django

إذا فكرت في تطوير تطبيق ويب أو موقع إلكتروني باستخدام لغة بايثون فستجد العديد من المكتبات وأطر العمل المتاحة لتنفيذ هذه المهمة لكن إطار عمل جانغو Django وفلاسك Flask هما الخياران الأكثر شيوعًا وقوة لتحقيق هذه المهمة ولمساعدتك على اختيار الإطار المناسب إليك قائمة بأبرز الفروقات بين فلاسك وجانغو:

يعد إطار العمل فلاسك Flask أسهل في التعلم ويمكنك تطوير التطبيقات باستخدامه بسرعة وسهولة في حين أن تعلم جانغو Django أكثر صعوبة وستحتاج لزمن أطول لتطوير تطبيقك الأول باستخدامه.
يعد إطار العمل جانغو Django كبير الحجم مقارنة بإطار العمل فلاسك Flask لكون إطار جانغو متكامل الميزات في حين أن فلاسك مصغر ومحدود الميزات ولا يحتوي على مكتبات مضمنة فيه كما ذكرنا سابقًا.
يتضمن إطار عمل جانغو Django ميزة تسجيل الدخول ويوفر آلية للاستيثاق أو المصادقة Authentication والتحقق من صحة بيانات النموذج غيرها من المميزات التي تسهل عمل مطور تطبيقات الويب، في حين لا يوفر إطار عمل فلاسك هذه المميزات بشكل ضمني وإنما تحتاج لاستيراد مكتبات خارجية لتضمينها.
يسهل إطار عمل جانغو إدارة الموقع ويوفر لوحة تحكم افتراضية تمكن مدير التطبيق من التعامل مع سجلات قواعد البيانات بسهولة دون الحاجة إلى كتابة أي استعلامات برمجية مخصصة، في حين لا يتضمن فلاسك هذه الميزة ضمنيًا لكن يمكنك تثبيت مكتبة تسمى flask-admin لتضمينها.
يدعم جانغو نموذج Model View Templates أو اختصارًا MVT مما يسهل على المطورين تنظيم هيكلية التطبيق والتركيز على مهام برمجة التطبيق، في حين لا يقيدك إطار العمل فلاسك بأي نموذج محدد للتطبيق ويمكنك هيكلة ملفات مشروعك بالطريقة التي تناسبك.
يتعامل جانغو مع قواعد بيانات التطبيق باستخدام ميزة Object-Relational Mapper أو اختصارًا ORM المضمنة فيه وهي طريقة للتفاعل مع قواعد البيانات من خلال واجهة برمجة تطبيقات API تعالج البيانات باستخدام تعليمات لغة بايثون، بينما لا يدعم فلاسك هذه الميزة وسيتعين عليك كتابة استعلامات SQL يدويًا لتنفيذ عمليات معالجة قواعد البيانات.
ينصح بالاعتماد على إطار العمل جانغو في حال كانت لديك خبرة جيدة في تطوير الويب باستخدام بايثون وكنت ترغب في تطوير مشاريع ضخمة بميزات متقدمة.

يمكن أن نختصر ما سبق بأن أبرز فرق بين إطار فلاسك وجانغو هو أن كلًا من جانغو Django وفلاسك هما إطارا ويب للغة بايثون Python لكن لكل منهما فلسفة مختلفة حيث يتبع فلاسك Flask فلسفة البساطة والمرونة وحين تحتاج لمكتبات خارجية عليك تضمينها يدويًا، في حين يتبع Django فلسفة تسمى فلسفة البطاريات المضمنة Battery Included Philosophy التي تعتمدها لغة بايثون أي أنه إطار عمل كامل المواصفات واستخدامه يقلل وقت تطوير تطبيقات الويب بشكل كبير.
وللمزيد من المعلومات حول الفرق بين إطار فلاسك Flask وجانغو Django أنصحك بمشاهدة الفيديو التالي:

خطوات تعلم إطار العمل Flask

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

تعلم مبادئ لغة HTML الأساسية لإنشاء قوالب الموقع أو التطبيق وتعلم أساسيات لغة CSS لتنسيق صفحات الويب الخاصة بك وجعلها جذابة بصريًا.
افهم لغة بايثون جيدًا وتعلم مفاهيم المتغيرات وأنواعها وهياكل البيانات وتعريف الدوال Functions ومبادئ البرمجة كائنية التوجه OOP …إلخ.
افهم كيف يعمل الويب وما هي أهم بروتوكولات الإنترنت وتعرف على مبادئ تطوير الويب.
تعرف على مبدأ عمل أطر تطوير الويب بشكل عام وركز على فهم طريقة عمل إطار فلاسك Flask ومفاهيمه الأساسية مثل الموجهات routes والعرض view.
تعلم طريقة إعداد بيئة التطوير الخاصة بك وخطوات تثبيت فلاسك على جهازك.
تعلم كيفية إنشاء واستخدام بيئة افتراضية معزولة لتطبيقات فلاسك المختلفة فهذا يساعد على إدارة وتنظيم تبعيات التطبيقات المختلفة.
أنشئ موقعك الأول على فلاسك Flask الخاص وتعرف على طريقة إضافة الوظائف للموقع واستخدام الوجهات ودوال العرض والقوالب .
تعلم طريقة التعامل مع النماذج في فلاسك واستخدمها لقبول المدخلات من مستخدم الموقع أو التطبيق.
تعلم التعامل قواعد البيانات بمختلف أنواعها مثل MySQL أو PostgreSQL أو MongoDB ضمن تطبيقات فلاسك Flask وتعلم كيف تشفر البيانات الحساسة قبل تخزينها وكيف تعالج البيانات المخزنة باستخدام استعلامات SQL وكيف تستعمل مكتبات خارجية تسهل عليك كتابة استعلامات مثل SQLAlchemy.
انتقل لبناء تطبيقات ويب بميزات متقدمة مثل ميزة استيثاق المستخدمين Authentication وأذوناتهم Permissions أو ميزة قبول المدفوعات أو ميزة تحليل البيانات وكيف تستورد المكتبات المناسبة لتحقيق هذه الميزات.
تعلم كيفية إنشاء ونشر واجهات برمجة تطبيقات باستخدام فلاسك Flask.
تعرف على خطوات نشر تطبيق فلاسك Flask الخاص بك على حاوية Docker أو خادم لينكس Linux أو على منصة سحابية مثل AWS.
عند إتمامك لكل الخطوات السابقة ستكون جاهزًا الآن للبحث عن فرص عمل مناسبة في شركة تطوير ويب لتعزز ما تعلمته من خلال بناء تطبيقات فعلية للمستخدمين، كما يمكنك العمل بشكل مستقل وتقديم خدماتك في تطوير المواقع والتطبيقات باستخدام فلاسك للعملاء على مواقع العمل الحر مثل مستقل أو خمسات.

مصادر تعلم فلاسك Flask

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

وإذا كنت تشعر بالتشتت من كثرة المصادر وتنوعها وتريد مصدرًا تعليميًا منظمًا يساعدك على التعلم بطريقة منهجية ضمن خطة تعلم واضحة ويوفر لك الدعم والتوجيه ويجيبك على أي تساؤلات أو مشكلات تواجهك من قبل مدربين أكفاء ويمكنك من بناء معرض أعمال احترافي بفترة وجيزة ويعزز فرصتك في الحصول على عمل فقد وفرت أكاديمية حسوب دورة تطوير التطبيقات باستخدام لغة بايثون Python التي تساعدك على تحقيق هذه الأهداف دون الحاجة لوجود أي معرفة برمجية مسبقة فمن خلالها ستبدأ من الصفر وتتعلم كل ما تحتاجه لبناء تطبيقات متكاملة بلغة بايثون وإطار عملها فلاسك Flask وغيره من أطر العمل الشهيرة.

الخلاصة

بهذا نكون قد وصلنا لنهاية مقالنا الذي عرفناك فيه على إطار العمل فلاسك Flask لتطوير تطبيقات الويب بلغة البرمجة بايثون Python وبينا أبرز مميزات هذا الإطار واستخداماته المختلفة وخطوات تعلمه بالتفصيل كما وضحنا أبرز الفروقات بينه وبين إطار العمل جانغو Django، وإذا كان لديك أي تساؤلات أو مشكلات بخصوص فلاسك Flask لا تتردد في مشاركتها معنا في قسم التعليقات.

إنشاء نظام إدارة موظفين ومعالجة البيانات باستخدام إضافة Flask-SQLAlchemy

Mon, 20 Mar 2023 13:03:00 +0000

يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا عدة أدوات وميزات من شأنها إنشاء تطبيقات ويب في لغة بايثون.

أمّا SQLAlchemy فهي أداة في محرك قواعد البيانات SQL تؤمن وصولًا فعالًا وعالي الأداء إلى قواعد البيانات العلاقية، كما توفّر طرقًا للتخاطب مع العديد من محركات قواعد البيانات، مثل SQLite و MySQL و PostgreSQ، مانحةً إمكانية الوصول إلى آليات SQL الخاصة بقواعد البيانات، كما توفّر رابط الكائن بالعلاقات Object Relational Mapper -أو اختصارًا ORM- الذي يتيح إمكانية إنشاء الاستعلامات والتعامل مع البيانات باستخدام توابع وكائنات بسيطة في بايثون.

تعدّ Flask-SQLAlchemy إضافةً لفلاسك تسهّل استخدام SQLAlchemy ضمنها وتؤمّن الأدوات والوسائل المناسبة للتعامل مع قاعدة البيانات في تطبيقات فلاسك من خلال SQLAlchemy.

سنستخدم في هذا المقال كلًا من إطار العمل فلاسك والإضافة Flask-SQLAlchemy لإنشاء نظام إدارة موظفين مع قاعدة بيانات تضم جدولًا خاصًّا بكل موظف، ليتضمّن هذا الجدول المعرّف الفريد ID للموظف واسمه الأوّل ونسبته وبريده الإلكتروني الفريد، إضافةً إلى عددٍ صحيح يدل على عمره وقيمة تاريخ تشير إلى تاريخ انضمامه إلى الشركة (تاريخ تعيّينه) وقيمةٍ منطقية تُحدّد ما إذا كان هذا الموظف متواجد حاليًا في مكتبه أم لا.

إذ سنستخدم صَدَفَة فلاسك للاستعلام عن جدول ما والحصول على سجلاتٍ معيّنة وفقًا لقيمة عمود منه (مثل البريد الإلكتروني)، أي سنجلب سجلات الموظفين المُحقّقة لشروط مُحدّدة، كأن نجلب فقط الموظفين المتواجدين حاليًا أو أن نُنشئ قائمةً بالموظفين غير المتواجدين، كما سنرتّب النتائج وفقًا لقيم أحد الأعمدة، بما يتضمّن تحديد نتائج الاستعلام وحساب عددها، وسنستخدم نهايةً الترقيم Pagination بغية عرض عدد مُحدّد من الموظفين في الصفحة الواحدة ضمن تطبيق الويب.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض، ويمكنك في هذا الصدد الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.
فهم أساسيات الإضافة Flask-SQLAlchemy، مثل إعداد قاعدة البيانات وإنشاء نماذجها وإدخال البيانات إليها، وننصحك في هذا الصدد بقراءة المقال استخدام الإضافة Flask-SQLAlchemy للتخاطب مع قواعد البيانات في تطبيقات فلاسك لفهم مبادئ هذه الإضافة.

الخطوة 1: إعداد قاعدة البيانات والنموذج

سنثبّت في هذه الخطوة كافّة الحزم اللازمة، كما سنعدّ كلًا من تطبيق فلاسك وقاعدة البيانات Flask-SQLAlchemy ونموذج الموظف المُمثّل للجدول employee، حيث سنخزّن بيانات الموظف، كما سنضيف وجهة وصفحة، حيث سنعرض كافّة الموظفين ضمن الصفحة الرئيسية للتطبيق.

لذا، وبعد التأكّد من كون البيئة الافتراضية مُفعّلة، سنستخدم أمر تثبيت الحزم pip لتثبيت كل من فلاسك والإضافة Flask-SQLAlchemy على النحو التالي:

(env)user@localhost:$ pip install Flask Flask-SQLAlchemy

بمجرّد انتهاء التثبيت بنجاح، سيظهر في السطر الأخير من الخرج ما يشبه التالي:

Successfully installed Flask-2.1.2 Flask-SQLAlchemy-2.5.1 Jinja2-3.1.2 MarkupSafe-2.1.1 SQLAlchemy-1.4.37 Werkzeug-2.1.2 click-8.1.3 greenlet-1.1.2 itsdangerous-2.1.2

الآن وبعد تثبيت الحزم اللازمة، سننشئ ملفًا جديدًا باسم "app.py" ضمن المجلد "flask.app" والذي سيحتوي على الشيفرات الخاصة بإعداد قاعدة البيانات ووجهات فلاسك اللازمة لعمل التطبيق:

(env)user@localhost:$ nano app.py

ونكتب ضمنه الشيفرة التالية، التي ستُعِدّ قاعدة بياناتٍ من نوع SQLite ونموذج قاعدة بيانات للموظف مُمثّلًا للجدول employee الذي سنستخدمه لتخزين بيانات كل موظف:

import os
from flask import Flask, render_template, request, url_for, redirect
from flask_sqlalchemy import SQLAlchemy


basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
        'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)


class Employee(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    firstname = db.Column(db.String(100), nullable=False)
    lastname = db.Column(db.String(100), nullable=False)
    email = db.Column(db.String(100), unique=True, nullable=False)
    age = db.Column(db.Integer, nullable=False)
    hire_date = db.Column(db.Date, nullable=False)
    active = db.Column(db.Boolean, nullable=False)

    def __repr__(self):
        return f''

نحفظ الملف ونغلقه.

استوردنا في الشيفرة السابقة الوحدة os التي تُمكنّنا من الوصول إلى واجهات نظام التشغيل المختلفة، والتي سنستخدمها في بناء مسار ملف قاعدة البيانات database.db، كما استوردنا من حزمة فلاسك كافّة المُساعدات اللازمة للتطبيق، مثل الصنف فلاسك Flask المُستخدم في إنشاء النسخة الفعلية من التطبيق، والدالة ()render_template لتصيير قوالب HTML، والكائن request المسؤول عن التعامل مع الطلبات، والدالة ()url_for لبناء روابط الوجهات، والدالة ()redirect لإعادة توجيه المُستخدمين من صفحة لأُخرى.

استوردنا بعد ذلك الصنف SQLAlchemy من الإضافة Flask-SQLAlchemy، والذي يسمح لنا بالوصول إلى جميع الدوال والأصناف الخاصة بالأداة SQLAlchemy، إضافةً إلى المُساعدات والآليات التي تدعم عمل فلاسك مع هذه الأداة، والتي سنستخدمها لإنشاء كائن قاعدة بيانات يتصل مع تطبيق فلاسك.

بهدف إنشاء مسار لملف قاعدة البيانات، حدّدنا المجلد الحالي ليكون المجلد الرئيسي، كما استخدمنا الدالة ()os.path.abspath للحصول على المسار المطلق لمجلد الملف الحالي، إذ يتضمّن المتغير الخاص __file__ اسم مسار الملف الحالي app.py، وخزنّا المسار المطلق للمجلد الأساسي ضمن المتغير basedir.

بعد ذلك، أنشأنا نسخةً فعليةً من تطبيق فلاسك باسم app والتي سنستخدمها لضبط مفتاحي إعدادات خاصّين بالإضافة Flask-SQLAlchemy، هما:

SQLALCHEMY_DATABASE_URI: وهو معرّف الموارد الموحّد الخاص بقاعدة البيانات database URI، وهو مسؤول عن تحديد قاعدة البيانات المراد إنشاء اتصال معها، وفي هذه الحالة تكون صيغة هذا المعرّف على النحو sqlite://path/to/database.db، إذ تُستخدم الدالة ()op.path.join لتحقيق الربط المدروس ما بين المجلد الأساسي الذي أنشاناه وخزنّا مساره في المتغير basedir، وبين اسم الملف database.db، الأمر الذي يسمح بالاتصال مع ملف قاعدة البيانات "database.db" الموجود في المجلد "flask.app"، إذ سيُنشَئ هذا الملف فور تهيئة قاعدة البيانات.
SQLALCHEMY_TRACK_MODIFICATIONS: وهو إعداد لتمكين أو إلغاء تمكين ميزة تتبع تغيرات الكائنات، وقد عيّناه إلى القيمة false لإلغاء التتبع وبالتالي تحقيق استخدام أقل لموارد الذاكرة.

بعد الانتهاء من ضبط إعدادات الأداة SQLAIchemy من خلال تعيين معرّف الموارد الموحّد لقاعدة البيانات وإلغاء تمكين ميزة تتبّع التغييرات، أنشأنا كائن قاعدة بيانات باستخدام صنف الأداة SQLAIchemy، ممررين إليه نسخة التطبيق بغية ربط تطبيق فلاسك مع الأداة SQLAIchemy، مخزنين كائن قاعدة البيانات هذا ضمن متغير باسم db والذي سنستخدمه في التخاطب مع قاعدة البيانات.

وبعد إعداد كل من نسخة التطبيق الفعلية وكائن قاعدة البيانات، أنشأنا نموذج قاعدة بيانات باسم Employee الوارث للصنف db.Model، إذ يُمثّل هذا النموذج جدول الموظفين employee المُتضمّن للأعمدة التالية:

id: وهو معرّف الموظف، ويحتوي على بياناتٍ من نوع رقم صحيح، ويمثّل المفتاح الأساسي.
firstname: الاسم الأول للموظف، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100، وتشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
lastname: الاسم الأخير للموظف، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100، وتشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
email: عنوان البريد الإلكتروني للموظف، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100، وتشير التعليمة unique=True إلى أنّ البريد الإلكتروني يجب أن يكون فريدًا لكل موظف، كما تشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
age: عمر الموظف، ويحتوي على بياناتٍ من نوع رقم صحيح.
hire_date: يحتوي على تاريخ تعيين الموظف، وقد عيّنا نمط العمود ليكون db.date بغية التصريح عن كون هذا العمود يحتوي على تواريخ.
active: يتضمّن قيمة منطقية تدل على ما إذا كان الموظف متواجد حاليًا في مكتبه أم لا.

تمكّننا الدالة الخاصة __repr__ من تمثيل كل كائن بصيغة سلسلة نصية، الأمر الذي يساعد في التعرّف على هذا الكائن لأغراض التنقيح، واستخدمنا في حالتنا الاسم الأوّل والأخير للموظف لتمثيل كائنات الموظفين.

الآن وبعد الانتهاء من إعداد كل من الاتصال مع قاعدة البيانات ونموذج الموظف، سنكتب برنامجًا في بايثون لإنشاء قاعدة البيانات والجدول employee وملء هذا الجدول ببعضٍ من بيانات الموظفين.

لذا، سننشئ ملفًا جديدًا باسم "init_db.py" ضمن المجلد "flask_app":

(env)user@localhost:$ nano init_db.py

ونكتب ضمنه الشيفرة التالية بغية حذف أي جداول حالية في قاعدة البيانات والبدء بقاعدة بيانات فارغة، كما سننشئ الجدول employee وسنملؤه ببيانات تسعة موظفين:

from datetime import date
from app import db, Employee

db.drop_all()
db.create_all()

e1 = Employee(firstname='John',
              lastname='Doe',
              email='jd@example.com',
              age=32,
              hire_date=date(2012, 3, 3),
              active=True
              )

e2 = Employee(firstname='Mary',
              lastname='Doe',
              email='md@example.com',
              age=38,
              hire_date=date(2016, 6, 7),
              active=True
              )

e3 = Employee(firstname='Jane',
              lastname='Tanaka',
              email='jt@example.com',
              age=32,
              hire_date=date(2015, 9, 12),
              active=False
              )

e4 = Employee(firstname='Alex',
              lastname='Brown',
              email='ab@example.com',
              age=29,
              hire_date=date(2019, 1, 3),
              active=True
              )

e5 = Employee(firstname='James',
              lastname='White',
              email='jw@example.com',
              age=24,
              hire_date=date(2021, 2, 4),
              active=True
              )

e6 = Employee(firstname='Harold',
              lastname='Ishida',
              email='hi@example.com',
              age=52,
              hire_date=date(2002, 3, 6),
              active=False
              )

e7 = Employee(firstname='Scarlett',
              lastname='Winter',
              email='sw@example.com',
              age=22,
              hire_date=date(2021, 4, 7),
              active=True
              )

e8 = Employee(firstname='Emily',
              lastname='Vill',
              email='ev@example.com',
              age=27,
              hire_date=date(2019, 6, 9),
              active=True
              )

e9 = Employee(firstname='Mary',
              lastname='Park',
              email='mp@example.com',
              age=30,
              hire_date=date(2021, 8, 11),
              active=True
              )

db.session.add_all([e1, e2, e3, e4, e5, e6, e7, e8, e9])

db.session.commit()

استوردنا في الشيفرة السابقة الصنف ()date من الوحدة datetime لاستخدامه في ضبط تواريخ تعيّين الموظفين.

استوردنا أيضًا كلًا من كائن قاعدة البيانات والنموذج Employee، واستدعينا الدالة ()db.drop_all بغية حذف كافّة الجداول الموجودة أصلًا في قاعدة البيانات متجنبين بذلك فرصة وجود جدول مملوء باسم "employee" سابقًا فيها، الأمر الذي قد يسبب أخطاءً.

من الجدير بالملاحظة أنّ البرنامج "init_db.py" سيحذف كامل محتويات قاعدة البيانات في كل مرة نشغّله فيها، وللمزيد حول كيفية إنشاء وتعديل وحذف جداول قاعدة البيانات، ننصحك بقراءة المقال استخدام الإضافة Flask-SQLAlchemy للتخاطب مع قواعد البيانات في تطبيقات فلاسك.

استنسخنا بعد ذلك النموذج Emolyee عدّة مرات بغية تمثيل كافّة الموظفين الذين سنستعلم عنهم في هذا المقال، ثم أضفنا هذه النسخ إلى قاعدة البيانات باستخدام الدالة ()db.session.add_all، ونهايةً استخدمنا التابع ()db.session.commit لتأكيد العمليات وتطبيق التغييرات على قاعدة البيانات.

نحفظ الملف ونغلقه.

سننفذ الآن البرنامج "init_db.py":

(env)user@localhost:$ python init_db.py

للاطلاع على البيانات المُضافة إلى قاعدة البيانات، نفتح صَدفة فلاسك بعد التأكّد من كون البيئة الافتراضية مُفعّلة بغية الاستعلام عن كافّة الموظفين وعرض بيانات كل منهم، على النحو التالي:

(env)user@localhost:$ flask shell

ثمّ نشغّل الشيفرة التالية المسؤولة عن الاستعلام عن كافّة الموظفين وعرض بياناتهم:

>>> from app import db, Employee
>>>
>>>
>>> employees = Employee.query.all()
>>>
>>> for employee in employees:
>>>     print(employee.firstname, employee.lastname)
>>>     print('Email:', employee.email)
>>>     print('Age:', employee.age)
>>>     print('Hired:', employee.hire_date)
>>>     if employee.active:
>>>         print('Active')
>>>     else:
>>>         print('Out of Office')
>>>     print('----')

استخدمنا في الشيفرة السابقة التابع ()all من السمة query للحصول على كافّة الموظفين، واستخدمنا حلقةً تكراريةً للمرور على كافّة نتائج الاستعلام؛ أمّا بالنسبة للعمود "active"، فقد استخدمنا جملةً شرطيةً لإظهار الحالة الراهنة للموظف، سواءٌ كان متواجدًا "Active" أم خارج مكتبه "Out of Office".

نحصل على خرجٍ على النحو التالي:

John Doe
Email: jd@example.com
Age: 32
Hired: 2012-03-03
Active
----
Mary Doe
Email: md@example.com
Age: 38
Hired: 2016-06-07
Active
----
Jane Tanaka
Email: jt@example.com
Age: 32
Hired: 2015-09-12
Out of Office
----
Alex Brown
Email: ab@example.com
Age: 29
Hired: 2019-01-03
Active
----
James White
Email: jw@example.com
Age: 24
Hired: 2021-02-04
Active
----
Harold Ishida
Email: hi@example.com
Age: 52
Hired: 2002-03-06
Out of Office
----
Scarlett Winter
Email: sw@example.com
Age: 22
Hired: 2021-04-07
Active
----
Emily Vill
Email: ev@example.com
Age: 27
Hired: 2019-06-09
Active
----
Mary Park
Email: mp@example.com
Age: 30
Hired: 2021-08-11
Active
----

وبذلك نجد أنه قد جرى عرض كافة الموظفين المُضافين إلى قاعدة البيانات على نحوٍ سليم.

نُغلق الآن صَدَفة فلاسك:

>>> exit()

أمّا الآن، فسننشئ وجهة فلاسك المسؤولة عن عرض الموظفين، لذا سنفتح الملف app.py لتحريره:

(env)user@localhost:$ nano app.py

ونكتب الوجهة التالية في نهايته:

...

@app.route('/')
def index():
    employees = Employee.query.all()
    return render_template('index.html', employees=employees)

نحفظ الملف ونغلقه.

ستستعلم الوجهة السابقة عن كافّة الموظفين، وتُصيّر قالب HTML للصفحة الرئيسية للتطبيق باسم "index.html" مُمررةً إليه نتائج الاستعلام.

ننشئ الآن مجلدًا للقوالب باسم "templates" وقالبًا رئيسيًا باسم "base.html":

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html

ونكتب التالي ضمن القالب الرئيسي:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة كتلة عنوان، كما أضفنا بعضًا من تنسيقات CSS لتنسيق مظهر المكونات.

أضفنا أيضًا شريط تصفّح بعنصرين، الأوّل للصفحة الرئيسية للتطبيق، والثاني لصفحة عرض معلومات حول التطبيق إلا أننا سنتركها غير فعالة حاليًا، إذ سيُستخدم شريط التصفّح هذا في التطبيق في كافّة القوالب الوارثة للقالب الرئيسي، كما ستُستبدل كتلة المحتوى من القالب الرئيسي بالمحتوى الموافق لكل صفحة موظف.

نفتح الآن قالب الصفحة الرئيسية "index.html" الذي صيّرناه في الملف "app.py":

(env)user@localhost:$ nano templates/index.html

ونكتب ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
     class="title">{% block title %} Employees {% endblock %}
     class="content">
        {% for employee in employees %}
             class="employee">
                #{{ employee.id }}
                
                     class="name">{{ employee.firstname }} {{ employee.lastname }}
                
                {{ employee.email }}
                {{ employee.age }} years old.
                Hired: {{ employee.hire_date }}
                {% if employee.active %}
                    (Active)
                {% else %}
                    (Out of Office)
                {% endif %}
            
        {% endfor %}
    
{% endblock %}

مررنا في الشيفرة السابقة على كافّة الموظفين باستخدام حلقةٍ تكرارية، لنعرض معلومات كل منهم، إذ أضفنا العنوان التوضيحي "Active" في حال كون الموظف متواجد حاليًا، وفيما عدا ذلك يُعرَض العنوان "Out of Office" دلالةً على عدم تواجده.

نحفظ الملف ونغلقه.

الآن ومع وجودنا ضمن المجلد "flask_app" ومع كون البيئة الافتراضية مُفعّلة، سنُعلم فلاسك بالتطبيق المراد تشغيله (وهو في حالتنا الملف "app.py") باستخدام متغير البيئة FLASK_APP، في حين يحدّد متغير البيئة FLASK_ENV وضع التشغيل وهنا قد اخترنا وضع development ما يعني أنّ التطبيق سيعمل في وضع التطوير مع تشغيل مُنقّح الأخطاء، وللمزيد من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

والآن سنشغّل التطبيق باستخدام الأمر flask run:

(env)user@localhost:$ flask run

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

http://127.0.0.1:5000/

فيظهر الموظفون المضافون إلى قاعدة البيانات في صفحة مشابهة للصورة التالية:

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

الخطوة 2: الاستعلام عن السجلات

سنستخدم في هذه الخطوة صَدَفة فلاسك للاستعلام عن السجلات، لنجلب النتائج ونرشّحها باستخدام توابع مختلفة تحت شروط مختلفة.

سنضبط بدايةً متغيرات البيئة FLASK_APP و FLASK_ENV أثناء كون البيئة البرمجية مُفعّلة، ثم نفتح صَدَفة فلاسك:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development
(env)user@localhost:$ flask shell

ثم نستورد كلًا من الكائن db والنموذج Employee:

>>> from app import db, Employee

استرجاع كافة السجلات

كما رأينا في الخطة السابقة، من الممكن استخدام التابع ()all من السمة query للحصول على كافّة سجلات الجدول، على النحو التالي:

>>> all_employees = Employee.query.all()
>>> print(all_employees)

وعندها سيكون الخرج قائمةً بالكائنات المُمثلّة لكل الموظفين:

[, , , , , , , , ]

استرجاع السجل الأول

من المُمكن استخدام التابع ()first للحصول على السجل الأوّل بصورةٍ مشابهة لما سبق، على النحو التالي:

>>> first_employee = Employee.query.first()
>>> print(first_employee)

وعندها سيكون الخرج هو الكائن المُتضمّن لبيانات الموظف الأوّل:

استرجاع سجل وفق معرفه

تُعرَّفُ السجلات في معظم جداول قواعد البيانات باستخدام معرّفٍ فريد ID، وتتيح الإضافة Flask-SQLAlchemy جلبَ سجلٍ ما وفقًا لمعرّفه باستخدام التابع ()get على النحو التالي:

>>> employee5 = Employee.query.get(5)
>>> employee3 = Employee.query.get(3)
>>> print(f'{employee5} | ID: {employee5.id}')
>>> print(f'{employee3} | ID: {employee3.id}')

ويكون الخرج بالشكل:

 | ID: 5
 | ID: 3

استرجاع سجل أو عدة سجلات وفقا لقيمة عمود

من الممكن استخدام تابع الترشيح ()filter_by بغية الحصول على سجل محدّد وفقًا لقيمة أحد أعمدته، فمثلًا لجلب سجل ما وفقًا لقيمة معرفّه بما يشبه مبدأ عمل التابع ()get، نكتب:

>>> employee = Employee.query.filter_by(id=1).first()
>>> print(employee)

ويكون الخرج بالشكل:

استخدمنا التابع ()first في الشيفرة السابقة لأنّ التابع ()filter_by قد يعيد عدّة نتائج، وبذلك نجلب الأولى منها فقط.

ملاحظة: في حال رغبتك بجلب سجلٍ ما وفقًا لمعرّفه، فإن المنهجية الأفضل هي استخدام التابع ()get.

من المُمكن أيضًا جلب موظف ما وفقًا لعمره، كما يلي:

>>> employee = Employee.query.filter_by(age=52).first()
>>> print(employee)

فيكون الخرج بالشكل:

لنأخذ مثالًا على حالة تتضمن فيها نتائج الاستعلام عدّة سجلات، إذ سنستعلم عندها وفقًا لاسم الموظف الأول firstname، وبقيمة "Mary"، وهنا توجد موظفتان بهذا الاسم في قاعدة البيانات لدينا:

>>> mary = Employee.query.filter_by(firstname='Mary').all()
>>> print(mary)

فيكون الخرج بالشكل:

[, ]

استخدمنا التابع ()all في الشيفرة السابقة للحصول على قائمة نتائج الاستعلام كاملةً، كما من الممكن استخدام التابع ()first للحصول على النتيجة الأولى فقط، على النحو التالي:

>>> mary = Employee.query.filter_by(firstname='Mary').first()
>>> print(mary)

ويكون الخرج عندها بالشكل:

وبذلك نكون قد جلبنا سجلاتٍ وفقًا لقيم أعمدة فيها، أما في الخطوة التالية فسنستعلم عن السجلات مُستخدمين شروطًا منطقية.

الخطوة 3: ترشيح السجلات باستخدام الشروط المنطقية

نحتاج غالبًا في تطبيقات الويب المعقدة كاملة الميزات إلى الاستعلام عن السجلات من قاعدة البيانات تحت شروطٍ معقدة، كأن نجلب الموظفين اعتمادًا على مجموعة من الشروط التي تأخذ في الحسبان مواقعهم وتوافرهم ودورهم الوظيفيّ ومسؤولياتهم.

ستتدرب في هذه الخطوة على كيفية استخدام المعاملات الشرطية، كما ستستخدم تابع الترشيح ()filter من سمة الاستعلام query بغية ترشيح نتائج الاستعلامات وفقًا لشروط منطقية تربط فيما بينها معاملاتٍ مُختلفة، إذ يمكن مثلًا استخدام المعاملات المنطقية لجلب قائمة بالموظفين غير المتواجدين في مكاتبهم حاليًا، أو أولئك الذين يستحقون ترقيةً، أو حتى لتوفير جدولة لمواعيد إجازات الموظفين وغيرها.

معامل التساوي

لعلّ أبسط معامل منطقي يمكن أن نستخدمه هو معامل المساواة ==، والذي يعمل بآلية مُشابهة للتابع ()filter_by، فللحصول مثلًا على كافّة السجلات التي قيمة عمود الاسم الأول firstname فيها تساوي "Mary"، يمكننا استخدام التابع ()filter على النحو التالي:

>>> mary = Employee.query.filter(Employee.firstname == 'Mary').all()
>>> print(mary)

استخدمنا في الشيفرة السابقة التعليمة Model.column == value وسيطًا للتابع ()filter، ويعدّ التابع ()filter_by اختصارًا لهذه الطريقة، وستكون النتيجة نفسها كما في حالة استخدام التابع ()filter_by تحت نفس الشرط، وهي:

[, ]

وكما هو الحال لدى استخدام التابع ()filter_by، من الممكن جلب نتيجة الاستعلام الأولى فقط باستخدام التابع ()first، على النحو التالي:

>>> mary = Employee.query.filter(Employee.firstname == 'Mary').first()
>>> print(mary)

فيصبح الخرج على الشّكل التالي:

معامل عدم التساوي

يتيح التابع ()filter إمكانية استخدام معامل عدم التساوي =! من بايثون في الحصول على السجلات، إذ يمكن مثلًا استخدام المنهجية التالية بغية الحصول على قائمة بالموظفين غير المتواجدين في مكاتبهم حاليًا:

>>> out_of_office_employees = Employee.query.filter(Employee.active != True).all()
>>> print(out_of_office_employees)

فيكون الخرج بالشكل التالي:

[, ]

استخدمنا في الشيفرة السابقة الشرط Employee.active != True لترشيح نتائج الاستعلام.

معامل الأصغر تماما

من الممكن استخدام المعامل > للحصول على سجل وفقًا لشرط كون قيمة أحد أعمدته أصغر تمامًا من قيمة معينة، إذ يمكن مثلًا الحصول على قائمة بالموظفين الذين أعمارهم أصغر تمامًا من 32 عامًا على النحو التالي:

>>> employees_under_32 = Employee.query.filter(Employee.age < 32).all()
>>>
>>> for employee in employees_under_32:
>>>    print(employee.firstname, employee.lastname)
>>>    print('Age: ', employee.age)
>>>    print('----')

فيكون الخرج بالشكل التالي:

Alex Brown
Age:  29
----
James White
Age:  24
----
Scarlett Winter
Age:  22
----
Emily Vill
Age:  27
----
Mary Park
Age:  30
----

كما من الممكن استخدام المعامل => للحصول على السجلات الأصغر من قيمة معينة أو تساويها، فمثلًا لتضمين الموظفين الذين أعمارهم تساوي 32 عامًا بنتائج الاستعلام السابق، نكتب:

>>> employees_32_or_younger = Employee.query.filter(Employee.age <=32).all()
>>>
>>> for employee in employees_32_or_younger:
>>>    print(employee.firstname, employee.lastname)
>>>    print('Age: ', employee.age)
>>>    print('----')

فيصبح الخرج بالشّكل:

John Doe
Age:  32
----
Jane Tanaka
Age:  32
----
Alex Brown
Age:  29
----
James White
Age:  24
----
Scarlett Winter
Age:  22
----
Emily Vill
Age:  27
----
Mary Park
Age:  30
----

معامل الأكبر تماما

من الممكن استخدام المعامل < للحصول على سجل وفقًا لشرط كون قيمة أحد أعمدته أكبر تمامًا من قيمة معينة. فعلى سبيل المثال، للحصول على قائمة بالموظفين الذين أعمارهم أكبر تمامًا من 32 عامًا، نكتب:

>>> employees_over_32 = Employee.query.filter(Employee.age > 32).all()
>>>
>>> for employee in employees_over_32:
>>>    print(employee.firstname, employee.lastname)
>>>    print('Age: ', employee.age)
>>>    print('----')

فيكون الخرج بالشكل:

Mary Doe
Age:  38
----
Harold Ishida
Age:  52
----

كما من الممكن استخدام المعامل =< للحصول على السجلات الأكبر من قيمة معينة أو تساويها. فمثلًا لتضمين الموظفين الذين أعمارهم تساوي 32 عامًا بنتائج الاستعلام السابق، نكتب:

>>> employees_32_or_older = Employee.query.filter(Employee.age >=32).all()
>>>
>>> for employee in employees_32_or_older:
>>>    print(employee.firstname, employee.lastname)
>>>    print('Age: ', employee.age)
>>>    print('----')

فيصبح الخرج بالشّكل:

John Doe
Age:  32
----
Mary Doe
Age:  38
----
Jane Tanaka
Age:  32
----
Harold Ishida
Age:  52
----

تابع الانتماء In

تتيح الإضافة SQLAlchemy إمكانية الحصول على السجلات التي توافق قيمة أحد أعمدتها قيمةً ضمن قائمة معطاة وذلك باستخدام التابع ()_in على العمود المطلوب على النحو التالي:

>>> names = ['Mary', 'Alex', 'Emily']
>>> employees = Employee.query.filter(Employee.firstname.in_(names)).all()
>>> print(employees)

فيكون الخرج بالشكل:

[, , , ]

استخدمنا في الشيفرة السابقة شرطًا وفق الصيغة (Model.column.in_(iterable، إذ تشير العبارة iterable لأي نوع تكراري من الكائنات (أي كائن يمكن المرور على عناصره، مثل القائمة). لنأخذ مثال آخر، إذ من الممكن استخدام دالة بايثون ()range للحصول على الموظفين المُنتمين لمجال معيّن من العمر، والاستعلام التالي يجلب كافّة الموظفين الذين أعمارهم في الثلاثينات:

>>> employees_in_30s = Employee.query.filter(Employee.age.in_(range(30, 40))).all()
>>> for employee in employees_in_30s:
>>>    print(employee.firstname, employee.lastname)
>>>    print('Age: ', employee.age)
>>>    print('----')

فيكون الخرج بالشّكل:

John Doe
Age:  32
----
Mary Doe
Age:  38
----
Jane Tanaka
Age:  32
----
Mary Park
Age:  30
----

تابع عدم الانتماء Not in

من الممكن استخدام تابع عدم الانتماء ()not_in بصورةٍ مشابهة لآلية استخدام التابع السابق ()_in بغية الحصول على السجلات التي لا تنتمي قيمة أحد أعمدتها لمجموعة قيم ضمن كائن تكراري ما، كما في المثال التالي:

>>> names = ['Mary', 'Alex', 'Emily']
>>> employees = Employee.query.filter(Employee.firstname.not_in(names)).all()
>>> print(employees)

فيكون الخرج بالشّكل:

[, , , , ]

إذ حصلنا على كافّة الموظفين عدا أولئك الذي أسماؤهم الأولى موجودة ضمن القائمة المُسمّاة names.

معامل And

من الممكن ربط عدّة شروط منطقية مع بعضها بعضًا باستخدام الدالة ()_db.and التي تعمل بنفس آلية المعامل and في بايثون.

لنفرض مثلًا أننا نريد الحصول على جميع الموظفين الذين تبلغ أعمارهم 32 عامًا والمتواجدين في مكاتبهم حاليًا، ففي هذه الحالة، سنتحقق بدايةً من الموظفين البالغة أعمارهم 32 عامًا باستخدام التابع ()filter_by (أو التابع ()filter إذا أردت)، على النحو:

>>> for employee in Employee.query.filter_by(age=32).all():
>>>    print(employee)
>>>    print('Age:', employee.age)
>>>    print('Active:', employee.active)
>>>    print('-----')

فيكون الخرج على النحو التالي:


Age: 32
Active: True
-----

Age: 32
Active: False
-----

حصلنا في الخرج السابق على موظَفيْن تبلغ أعمارهما 32 عامًا، أحدهما متواجد في مكتبه حاليًا والآخر قد غادره، وللحصول على الموظفين البالغة أعمارهم 32 عامًا والمتواجدين في مكاتبهم حاليًا، فلا بدّ من استخدام شرطين ضمن التابع ()filter، هما:

Employee.age == 32
Employee.active == True

ولربط الشرطين معًا، من الممكن استخدام الدالة ()_db.and كما يلي:

>>> active_and_32 = Employee.query.filter(db.and_(Employee.age == 32,
>>>                                      Employee.active == True)).all()
>>> print(active_and_32)

فيكون الخرج على النحو التالي:

[]

استخدمنا في الشيفرة السابقة الصيغة ((filter(db.and_(condition1, condition2 للربط بين الشرطين.

ومع تطبيق التابع ()all على نتائج الاستعلام نحصل على قائمة بكافّة النتائج المُحقّقة لكلا الشرطين، كما من الممكن استخدام التابع ()first للحصول على النتيجة الأولى فقط من نتائج الاستعلام.

>>> active_and_32 = Employee.query.filter(db.and_(Employee.age == 32,
>>>                                      Employee.active == True)).first()
>>> print(active_and_32)

فيكون الخرج على النحو التالي:

لنأخذ مثالًا أكثر تعقيدًا، لنفرض أننا نريد الاستعلام عن الموظفين الذين جرى تعيينهم خلال فترة زمنية معينة، عندها من الممكن استخدام الدالة ()db.and مع الدالة ()date، كما في المثال التالي الهادف للحصول على كافّة الموظفين المُعينين خلال عام 2019:

>>> from datetime import date
>>>
>>> hired_in_2019 = Employee.query.filter(db.and_(Employee.hire_date >= date(year=2019, month=1, day=1), Employee.hire_date < date(year=2020, month=1, day=1))).all()
>>> 
>>> for employee in hired_in_2019:
>>>     print(employee, ' | Hired: ', employee.hire_date)

فيكون الخرج على النحو التالي:

  | Hired:  2019-01-03
  | Hired:  2019-06-09

استوردنا في الشيفرة السابقة الدالة ()date، كما رشّحنا نتائج الاستعلام باستخدام الدالة ()_db.and بغية ربط شرطين، هما:

(Employee.hire_date >= date(year=2019, month=1, day=1: وهو مُحقّق "True" من أجل الموظفين المُعينين بدءًا من الأول من كانون الثاني لعام 2019 فما بعد.
(Employee.hire_date < date(year=2020, month=1, day=1: وهو مُحقّق "True" من أجل الموظفين المُعينين قبل الأول من كانون الثاني لعام 2020.

حصلنا من خلال الربط بين الشرطين على الموظفين المُعينين بدءًا من بداية عام 2019 وحتى نهايته.

معامل Or

تعمل الدالة ()_db.or على ربط شرطين منطقيين كما تفعل الدالة ()_db.and، إلا أنها تشابه آلية عمل المعامل or في بايثون، إذ تعمل على جلب كافّة السجلات التي تحقق شرطًا على الأقل من الشرطين المُمررين إليها، فعلى سبيل المثال، للحصول على الموظفين البالغة أعمارهم 32 عامًا أو 52 عامًا، من الممكن الربط بين هذين الشرطين باستخدام الدالة ()_db.or بالشكل:

>>> employees_32_or_52 = Employee.query.filter(db.or_(Employee.age == 32, Employee.age == 52)).all()
>>> 
>>> for e in employees_32_or_52:
>>>     print(e, '| Age:', e.age)

فيكون الخرج على النحو التالي:

 | Age: 32
 | Age: 32
 | Age: 52

يمكن استخدام التابعين ()startswith (الذي يشترط على السلسة النصية البدء بمحرف معيّن) و ()endswith (الذي يشترط على السلسة النصية الانتهاء بمحرف معيّن) على السلاسل النصية في الشروط المُمرّرة إلى التابع ()filter، فعلى سبيل المثال، لجلب كافة الموظفين الذين يبدأ اسمهم الأول بالحرف 'M' وأولئك الذين ينتهي اسمهم الأخير بالحرف 'e' نكتب:

>>> employees = Employee.query.filter(db.or_(Employee.firstname.startswith('M'), Employee.lastname.endswith('e'))).all()
>>> 
>>> for e in employees:
>>>    print(e)

فنحصل على الخرج التالي:

ربطنا في الشيفرة السابقة الشرطين التاليين:

('Employee.firstname.startswith('M: للحصول على الموظفين الذين يبدأ اسمهم الأول بالحرف 'M'.
('Employee.lastname.endswith('e: للحصول على الموظفين الذين ينتهي اسمهم الأخير بالحرف 'e'.

وبذلك أصبح من الممكن الآن ترشيح نتائج الاستعلام باستخدام الشروط المنطقية في تطبيقات Flask-SQLAlchemy، أمّا في الخطوة التالية فسنعمل على ترتيب وتحديد وحساب عدد النتائج التي نحصل عليها من قاعدة البيانات.

الخطوة 4: ترتيب وتحديد وحساب عدد النتائج

غالبًا ما نضطر إلى ترتيب السجلات عند عرضها في تطبيقات الويب، فمن الممكن مثلًا أن يكون لدينا صفحةٌ لعرض التعيينات الأخيرة في كل قسم، وهذا يجعل باقي أعضاء فريق العمل يتعرّفون على زملائهم الجدد؛ كما من الممكن ترتيب عرض الموظفين بحيث يظهر الموظفين الأقدم أولًا بهدف معرفة أطول الموظفين خدمةً؛ وقد تحتاج أيضًا في بعض الحالات إلى تحديد النتائج، كما في حال رغبتك بعرض أحدث ثلاث موظفين ضمن شريط جانبي صغير، وغالبًا ما نضطر إلى حساب عدد نتائج الاستعلام، لعرض مثلًا عدد الموظفين المتواجدين في مكاتبهم حاليًا. ستتعرف في هذه الخطوة على كيفية ترتيب وتحديد وحساب عدد نتائج الاستعلامات.

ترتيب النتائج

نستخدم التابع ()order_by لترتيب النتائج وفقًا لقيم عمود ما، فعلى سبيل المثال، لترتيب النتائج حسب الاسم الأول للموظف نكتب:

>>> employees = Employee.query.order_by(Employee.firstname).all()
>>> print(employees)

فنحصل على الخرج التالي:

[, , , , , , , , ]

نلاحظ من الخرج السابق أنّ النتائج مُرتّبة أبجديًا وفق الاسم الأول للموظف، كما من الممكن ترتيب النتائج وفقًا لقيم عمود آخر، كأن نستخدم الاسم الأخير للترتيب، كما يلي:

>>> employees = Employee.query.order_by(Employee.lastname).all()
>>> print(employees)

فيصبح الخرج على النحو التالي:

[, , , , , , , , ]

كما من الممكن ترتيب الموظفين وفقًا لتواريخ تعيّينهم، على النحو:

>>> em_ordered_by_hire_date = Employee.query.order_by(Employee.hire_date).all()
>>> 
>>> for employee in em_ordered_by_hire_date:
>>>    print(employee.firstname, employee.lastname, employee.hire_date)

فيكون الخرج على النحو التالي:

Harold Ishida 2002-03-06
John Doe 2012-03-03
Jane Tanaka 2015-09-12
Mary Doe 2016-06-07
Alex Brown 2019-01-03
Emily Vill 2019-06-09
James White 2021-02-04
Scarlett Winter 2021-04-07
Mary Park 2021-08-11

نلاحظ من الخرج السابق ترتيب تواريخ التعيين تصاعديًا من الأقدم إلى الأحدث، ومن الممكن عكس هذا الترتيب وجعله تنازلي أي من الأحدث إلى الأقدم باستخدام التابع ()desc على النحو التالي:

>>> em_ordered_by_hire_date_desc = Employee.query.order_by(Employee.hire_date.desc()).all()
>>> 
>>> for employee in em_ordered_by_hire_date_desc:
>>>     print(employee.firstname, employee.lastname, employee.hire_date)

فيصبح الخرج كما يلي:

Mary Park 2021-08-11
Scarlett Winter 2021-04-07
James White 2021-02-04
Emily Vill 2019-06-09
Alex Brown 2019-01-03
Mary Doe 2016-06-07
Jane Tanaka 2015-09-12
John Doe 2012-03-03
Harold Ishida 2002-03-06

كما من الممكن ربط كلا تابعي الترشيح ()filter والترتيب ()order_by معًا بغية ترتيب النتائج بعد ترشيحها، إذ تجلب الشيفرة التالية مثلًا كافّة الموظفين المُعينين خلال عام 2021 ثمّ ترتبهم حسب أعمارهم:

>>> from datetime import date
>>> hired_in_2021 = Employee.query.filter(db.and_(Employee.hire_date >= date(year=2021, month=1, day=1), Employee.hire_date < date(year=2022, month=1, day=1))).order_by(Employee.age).all()
>>> 
>>> for employee in hired_in_2021:
>>>    print(employee.firstname, employee.lastname,
>>>          employee.hire_date, '| Age', employee.age)

فيكون الخرج كما يلي:

Scarlett Winter 2021-04-07 | Age 22
James White 2021-02-04 | Age 24
Mary Park 2021-08-11 | Age 30

استخدمنا في الشيفرة السابقة الدالة ()_db.and للربط بين شرطين مطلوب تحققهما معًا، الأول لتحديد الموظفين المُعينين بدءًا من الأول من كانون الثاني لعام 2021 فما بعد:

Employee.hire_date >= date(year=2021, month=1, day=1)

والثاني لتحديد الموظفين المُعينين قبل اليوم الأول من عام 2022:

Employee.hire_date < date(year=2022, month=1, day=(1)

ومن ثمّ استخدمنا التابع ()order_by لترتيب الموظفين المُحققين للشرطين السابقين وفق أعمارهم.

تحديد النتائج

قد نحصل في معظم حالات الاستعلام عن جداول قواعد البيانات في التطبيقات الحقيقية على ملايين النتائج الموافقة، ما يجعل من تحديد عدد النتائج برقم معيّن أمرًا ضروريًا، ولتحقيق ذلك في تطبيقات Flask-SQLAlchemy، نستخدم التابع ()limit. يبين المثال التالي كيفية الاستعلام عن البيانات في جدول الموظفين employee، ليعيد أول ثلاث نتائج موافقة فقط:

>>> employees = Employee.query.limit(3).all()
>>> print(employees)

فيكون الخرج على النحو التالي:

[, , ]

كما من الممكن استخدام التابع ()limit مع توابع أُخرى، مثل filter و order_by، إذ يمكن مثلًا الحصول على آخر موظَفيْن مُعيَنيْن لعام 2021 باستخدام التابع ()limit على النحو التالي:

>>> from datetime import date
>>> hired_in_2021 = Employee.query.filter(db.and_(Employee.hire_date >= date(year=2021, month=1, day=1), Employee.hire_date < date(year=2022, month=1, day=1))).order_by(Employee.age).limit(2).all()
>>> 
>>> for employee in hired_in_2021:
>>>     print(employee.firstname, employee.lastname,
>>>           employee.hire_date, '| Age', employee.age)

فنحصل على الخرج التالي:

Scarlett Winter 2021-04-07 | Age 22
James White 2021-02-04 | Age 24

استخدمنا في الشيفرة السابقة نفس الاستعلام الوارد في القسم السابق ولكن مع استدعاء للتابع (limit(2.

حساب عدد النتائج

يمكننا استخدام التابع ()count لحساب عدد نتائج استعلام ما، فعلى سبيل المثال، للحصول على عدد الموظفين الموجودين في قاعدة البيانات نكتب:

>>> employee_count = Employee.query.count()
>>> print(employee_count)

فنحصل على الخرج التالي:

كما من الممكن استخدام التابع ()count جنبًا إلى جنب مع توابع استعلام أُخرى مثل ()limit. للحصول على عدد الموظفين المُعينين خلال عام 2021 مثلًا نكتب:

>>> from datetime import date
>>> hired_in_2021_count = Employee.query.filter(db.and_(Employee.hire_date >= date(year=2021, month=1, day=1), Employee.hire_date < date(year=2022, month=1, day=1))).order_by(Employee.age).count()
>>> print(hired_in_2021_count)

فنحصل على الخرج التالي:

استخدمنا في هذه الشيفرة نفس الاستعلام السابق الخاص بالحصول على الموظفين المُعينين خلال عام 2021 ولكن مع استخدام التابع ()count للحصول على عددهم (عدد السجلات الموافقة) وهو 3.

ومع نهاية هذه الخطوة نكون قد تعرّفنا على كيفية ترتيب وتحديد وحساب عدد نتائج استعلام في Flask-SQLAlchemy، أمّا في الخطوة التالية فسنتعرف على كيفية تقسيم نتائج الاستعلام على صفحاتٍ مُتعدّدة، إضافةً إلى كيفية إنشاء نظام ترقيم في تطبيقات فلاسك.

الخطوة 5: كيفية عرض قوائم السجلات الطويلة على صفحات متعددة

سنعمل في هذه الخطوة على تعديل الوجهة الرئيسية للتطبيق لتجعل الصفحة الرئيسية تعرض سجلات الموظفين على صفحاتٍ مُتعدّدة، ما يجعل من تصفّح قائمة الموظفين أسهل.

سنستخدم بدايةً صَدَفة فلاسك لنوضّح كيفية استخدام ميزة الترقيم pagination في الإضافة Flask-SQLAlchemy، لذا نفتح صَدَفة فلاسك (إن لم تكن مفتوحة أصلًا):

(env)user@localhost:$ flask shell

وبفرض أنّنا نريد توزيع سجلات جدول الموظفين على صفحاتٍ مُتعدّدة، من خلال عرض عنصرين اثنين فقط في كل صفحة، فمن الممكن إنجاز ذلك باستخدام تابع الاستعلام ()paginate كما يلي:

>>> page1 = Employee.query.paginate(page=1, per_page=2)
>>> print(page1)
>>> print(page1.items)

فيكون الخرج على النحو التالي:


[, ]

استخدمنا في الشيفرة السابقة معامل الصفحة page من تابع الاستعلام ()paginate بغية تحديد الصفحة المراد الوصول إليها، وهي الصفحة الأولى في حالتا، أمّا المعامل per_page فيُحدّد عدد العناصر المعروضة في كل صفحة، وقد عيّنا قيمته لتكون "2" لتعرض كل صفحة عنصرين فقط، أمّا المتغير page1 فما هو إلا كائن ترقيم يمكّننا من الوصول إلى السمات والتوابع المُستخدمة في إدارة عملية الترقيم.

استخدمنا السمة items للوصول إلى عناصر الصفحة؛ أما للوصول إلى الصفحة التالية، فمن الممكن استخدام التابع ()next من كائن الترقيم على النحو التالي، إذ ستكون النتيجة المُعادة كائن ترقيم أيضًا:

>>> page2 = page1.next()
>>> 
>>> print(page2.items)
>>> print(page2)

فيكون الخرج على النحو التالي:

[, ]

كما من الممكن الحصول على كائن ترقيم خاص بالصفحة السابقة باستخدام التابع ()prev، ففي المثال التالي، نحصل على كائن الترقيم الخاص بالصفحة الرابعة، ومنه نصل إلى كائن ترقيم الصفحة السابقة، أي الصفحة رقم 3، على النحو التالي:

>>> page4 = Employee.query.paginate(page=4, per_page=2)
>>> print(page4.items)
>>> page3 = page4.prev()
>>> print(page3.items)

فيكون الخرج كما يلي:

[, ]

[, ]

كما من الممكن الوصول إلى رقم الصفحة الحالية باستخدام السمة page على النحو:

>>> print(page1.page)
>>> print(page2.page)

فنحصل على الخرج التالي:

1
2

كما من الممكن استخدام السمة pages من كائن الترقيم للحصول على العدد الإجمالي من الصفحات، ففي المثال التالي، تعيد كلًا من التعليمتين page1.pages و page2.pages نفس القيمة لأن العدد الإجمالي للصفحات ثابت:

>>> print(page1.pages)
>>> print(page2.pages)

ويكون الخرج على النحو التالي:

5
5

أمّا للحصول على العدد الكلي من العناصر، فنستخدم السمة total من كائن الترقيم، على النحو التالي:

>>> print(page1.total)
>>> print(page2.total)

فنحصل على الخرج التالي:

9
9

نلاحظ في الخرج السابق وطالما أنّنا استعلمنا عن كافّة الموظفين، سيكون العدد الإجمالي للعناصر في كائن الترقيم هو 9، نظرًا لوجود تسعة موظفين في قاعدة البيانات.

وفيما يلي قائمة ببعض السمات الأخرى التي تملكها كائنات الترقيم:

prev_num: رقم الصفحة السابقة.
next_num: رقم الصفحة التالية.
has_next: تعيد القيمة "True" في حال وجود صفحة تالية.
has_prev: تعيد القيمة "True" في حال وجود صفحة سابقة.
per_page: عدد العناصر في الصفحة.

كما يمتلك كائن الترقيم تابعًا باسم ()iter_pages للمرور على أرقام الصفحات، إذ من الممكن مثلًا طباعة أرقام الصفحات على النحو:

>>> pagination = Employee.query.paginate(page=1, per_page=2)
>>> 
>>> for page_num in pagination.iter_pages():
>>>     print(page_num)

فيكون الخرج كما يلي:

وفيما يلي مثال لتوضيح كيفية الوصول إلى جميع الصفحات وعناصرها باستخدام كل من كائن الترقيم والتابع ()iter_pages:

>>> pagination = Employee.query.paginate(page=1, per_page=2)
>>> 
>>> for page_num in pagination.iter_pages():
>>>     print('PAGE', pagination.page)
>>>     print('-')
>>>     print(pagination.items)
>>>     print('-'*20)
>>>     pagination = pagination.next()

فنحصل على الخرج التالي:

PAGE 1
-
[, ]
--------------------
PAGE 2
-
[, ]
--------------------
PAGE 3
-
[, ]
--------------------
PAGE 4
-
[, ]
--------------------
PAGE 5
-
[]
--------------------

أنشأنا في الشيفرة السابقة كائن ترقيم يبدأ من الصفحة الأولى، ثمّ مررنا على الصفحات باستخدام حلقة for تكرارية عن طريق تابع الترقيم ()iter_pages، لنطبع رقم وعناصر الصفحة، ثم أسندنا قيمة كائن الترقيم الخاص بالصفحة التالية إلى كائن الترقيم pagination باستخدام التابع ()next.

يمكن استخدام كلًا من تابعي الترشيح ()filter والترتيب ()order_by جنبًا إلى جنب مع تابع الترقيم ()paginate لترقيم نتائج الاستعلام بعد ترشيحها وترتيبها، فعلى سبيل المثال، يمكننا الحصول على الموظفين ممن تجاوزوا الثلاثين من عمرهم ونرتّب النتائج وفقًا للعمر وننفّذ على النتائج عملية ترقيم كما يلي:

>>> pagination = Employee.query.filter(Employee.age > 30).order_by(Employee.age).paginate(page=1, per_page=2)
>>> 
>>> for page_num in pagination.iter_pages():
>>>     print('PAGE', pagination.page)
>>>     print('-')
>>>     for employee in pagination.items:
>>>         print(employee, '| Age: ', employee.age)
>>>     print('-'*20)
>>>     pagination = pagination.next()

فنحصل على خرجٍ بالشّكل التالي:

PAGE 1
-
 | Age:  32
 | Age:  32
--------------------
PAGE 2
-
 | Age:  38
 | Age:  52
--------------------

الآن وبعد أن تعرفنا على آلية عمل ميزة الترقيم في Flask-SQLAlchemy بوضوح، سنحرّر صفحة التطبيق الرئيسية لعرض الموظفين على صفحاتٍ مُتعدّدة، وهذا ما يجعل تصفحهم أسهل على المُستخدم.

نخرج من صَدَفة فلاسك:

>>> exit()

سنستخدم معاملات الروابط URL المعروفة باسم سلاسل الاستعلام عن الروابط URL query strings للوصول إلى صفحاتِ الموظفين المُختلفة، وهي طريقة لتمرير المعلومات إلى التطبيق من خلال الروابط، إذ تُمرّر المعاملات إلى التطبيق بعد الرمز ? في الرابط. على سبيل المثال، من الممكن استخدام الروابط التالية لتمرير معامل الصفحة page بقيمٍ مُختلفة:

http://127.0.0.1:5000/?page=1
http://127.0.0.1:5000/?page=3

إذ يمرِّر هنا الرابط الأوّل القيمة "1" إلى معامل الرابط page، بينما يمرّر الرابط الثاني القيمة "3" لنفس المعامل.

نفتح الآن الملف app.py:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة الرئيسية index لتصبح على النحو التالي:

@app.route('/')
def index():
    page = request.args.get('page', 1, type=int)
    pagination = Employee.query.order_by(Employee.firstname).paginate(
        page, per_page=2)
    return render_template('index.html', pagination=pagination)

حصلنا في الشيفرة السابقة على قيمة معامل الرابط للصفحة المسمّى page باستخدام كل من الكائن request.args وتابعه ()get. فعلى سبيل المثال، نأخذ من الجزء page=1?/ من الرابط القيمة "1" الخاصّة بمعامل الرابط للصفحة المسمّى page، لتُمرّر هذه القيمة "1" مثل قيمة افتراضية، ونمرّر نمط البيانات int من بايثون مثل وسيط لمعامل النوع type لضمان كون القيمة المُمررة من النوع عدد صحيح.

ثمّ أنشأنا الكائن pagination، ورتّبنا نتائج الاستعلام وفق الاسم الأول للموظف، كما مرّرنا قيمة معامل الرابط page إلى التابع ()paginate، ووزّعنا النتائج على عنصرين لكل صفحة عبر تمرير القيمة "2" إلى المعامل per_page، ومرّرنا نهايةً كائن الترقيم المُنشأ pagination إلى القالب المُصيّر index.html.

نحفظ الملف ونغلقه.

أمّا الآن، سنحرر القالب index.html بغية عرض عناصر الترقيم:

(env)user@localhost:$ nano templates/index.html

سنعدّل وسم التقسيم div الخاص بالمحتوى ليتضمّن عنوانًا من المستوى الثاني h2 للدلالة على الصفحة الحالية، كما سنعدّل حلقة for التكرارية لتمر على الكائن pagination.items بدلًا من الكائن employees الذي لم يعد موجودًا.

 class="content">
    (Page {{ pagination.page }})
    {% for employee in pagination.items %}
         class="employee">
            #{{ employee.id }}
            
                 class="name">{{ employee.firstname }} {{ employee.lastname }}
            
            {{ employee.email }}
            {{ employee.age }} years old.
            Hired: {{ employee.hire_date }}
            {% if employee.active %}
                (Active)
            {% else %}
                (Out of Office)
            {% endif %}
        
    {% endfor %}

نحفظ الملف ونغلقه.

الآن، سنضبط كلًا من متغيري البيئة FLASK_APP و FLASK_ENV، كما سنشغّل خادم التطوير (وذلك في حال عدم إنجاز هذه الخطوات مُسبقًا):

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development
(env)user@localhost:$ flask run

ننتقل الآن إلى الصفحة الرئيسية للتطبيق باستخدام قيمٍ مُختلفة لمعامل الرابط page، على النحو التالي:

http://127.0.0.1:5000/
http://127.0.0.1:5000/?page=2
http://127.0.0.1:5000/?page=4
http://127.0.0.1:5000/?page=19

فسيظهر في كل مرة صفحة جديدة، يتضمّن كل منها عنصرين مُختلفين بما يُشبه النتيجة التي رأيناها سابقًا ضمن صَدَفة فلاسك.

وفي حال كون الرقم المُمرّر إلى معامل الرابط غير موجود، فعندها سيُعرض خطأ HTTP من النوع "‎404 Not Found"، كما هو الحال مع الرابط الأخير من قائمة الروابط أعلاه.

أمّا الآن، فسننشئ عنصر واجهة مستخدم widget خاص بالترقيم لنسمح للمستخدم بالتنقّل بين الصفحات، إذ سنستخدم بعض سمات وتوابع كائن الترقيم بغية عرض أرقام كافّة الصفحات، إذ سيمثّل كل رقم رابطًا إلى صفحته الموافقة، كما سنعرض الزر >>> للرجوع في حال كانت الصفحة الحالية تمتلك صفحة سابقة، وزر <<< للانتقال إلى الصفحة التالية في حال كانت الصفحة الحالية تمتلك صفحة تليها.

وسيبدو عنصر واجهة المستخدم الخاص بالترقيم بالشكل التالي:

ولإضافته، نفتح الملف index.html:

(env)user@localhost:$ nano templates/index.html

ونعدّله بإضافة وسم تقسيم div جديد أسفل وسم div السابق الخاص بالمحتوى، على النحو:

 class="content">
    {% for employee in pagination.items %}
         class="employee">
            #{{ employee.id }}
            
                 class="name">{{ employee.firstname }} {{ employee.lastname }}
            
            {{ employee.email }}
            {{ employee.age }} years old.
            Hired: {{ employee.hire_date }}
            {% if employee.active %}
                (Active)
            {% else %}
                (Out of Office)
            {% endif %}
        
    {% endfor %}


 class="pagination">
    {% if pagination.has_prev %}
        
             class='page-number' href="{{ url_for('index', page=pagination.prev_num) }}">
                {{ '<<<' }}
            
        
    {% endif %}

    {% for number in pagination.iter_pages() %}
        {% if pagination.page != number %}
            
                     class='page-number'
                        href="{{ url_for('index', page=number) }}">
                    {{ number }}
                    
            
        {% else %}
             class='current-page-number'>{{ number }}
        {% endif %}
    {% endfor %}

    {% if pagination.has_next %}
        
             class='page-number'
                href="{{ url_for('index', page=pagination.next_num) }}">
                {{ '>>>' }}
            
        
    {% endif %}

نحفظ الملف ونغلقه.

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

url_for('index', page=pagination.prev_num)

وفيها يُربط الزر بدالة العرض الرئيسية index ممررين القيمة pagination.prev_num إلى معامل الرابط page.

لعرض روابط لكل أرقام الصفحات المتوفرة، مررنا باستخدام حلقة تكرارية على كافّة عناصر التابع ()pagination.iter_pages الذي يزودنا برقم صفحة عند كل تكرار، واستخدمنا الشرط if pagination.page != number لنتحقق ما إذا كان رقم الصفحة الحالي مغاير للرقم في التكرار الحالي؛ فعند تحقق الشرط، ننشئ رابطًا يُمكّن المستخدم من تغيّير الصفحة الحالية إلى صفحة أخرى، وإلّا فإنّنا نعرض رقم الصفحة دون رابط، إذ تكون الصفحة الحالية في هذه الحالة موافقة للرقم الحالي في التكرار، وهذا ما سيساعد المستخدمين على معرفة رقم الصفحة الحالية من خلال عنصر واجهة المستخدم الخاص بالترقيم.

استخدمنا نهايةً الشرط pagination.has_next لنتحقّق من وجود صفحة تلي الصفحة الحالية، وفي حال تحقُّق هذا الشرط، نُنشئ رابطًا إليها من خلال استدعاء التابع وربطه بالزر <<<:

url_for('index', page=pagination.next_num)

الآن وبالانتقال إلى الصفحة الرئيسية للتطبيق عبر المتصفح باستخدام الرابط:

http://127.0.0.1:5000/

سنجد عنصر واجهة المستخدم الخاص بالترقيم يعمل بنجاح، كما في الشكل التالي:

استخدمنا هنا الرمز <<< للدلالة على الانتقال إلى الصفحة التالية، والرمز >>> للدلالة على الانتقال إلى الصفحة السابقة، ولكن من الممكن استخدام أي رمز آخر مثل > و <، أو حتى صور باستخدام وسم الصورة .

مع نهاية هذه الخطوة نكون قد عرضنا بيانات الموظفين على صفحاتٍ مُتعدّدة، وتعلّمنا كيفية التعامل مع مفهوم الترقيم في Flask-SQLAlchemy، ومن الآن أصبح بإمكانك استخدام عنصر واجهة المستخدم الخاص بالترقيم الذي أنشأناه في أي تطبيقات فلاسك أخرى تُنشئها.

الخاتمة

استخدمنا في هذا المقال الإضافة Flask-SQLAlchemy لإنشاء نظام إدارة موظفين، إذ استعرضنا كيفية الاستعلام عن جدول وترشيح نتائجه وفق قيم أحد أعمدته أو وفق شروطٍ منطقية بسيطة ومُركّبة، كما بيّنا كيفية ترتيب نتائج الاستعلامات وتحديدها وحساب عددها، وأنشأنا أيضًا نظام ترقيم بغية عرض عددٍ مُحدّد من السجلات في كل صفحة من صفحات تطبيق الويب، مع إمكانية التنقّل بين هذه الصفحات.

ترجمة -وبتصرف- للمقال How To Query Tables and Paginate Data in Flask-SQLAlchemy لصاحبه Abdelhadi Dyouri.

استخدام SQLAlchemy في فلاسك لإنشاء مدونة مع علاقات many-to-many

Mon, 13 Mar 2023 13:01:03 +0000

أمّا SQLAlchemy، فهي أداةٌ في محرك قواعد البيانات SQL تؤمن وصولًا فعالًا وعالي الأداء إلى قواعد البيانات العلاقية، كما توفّر طرقًا للتخاطب مع العديد من محركات قواعد البيانات، مثل SQLite و MySQL و PostgreSQ، مانحةً إمكانية الوصول إلى آليات SQL الخاصة بقواعد البيانات، كما توفّر رابط الكائنات بالعلاقات Object Relational Mapper -أو اختصارًا ORM- الذي يتيح إمكانية إنشاء الاستعلامات والتعامل مع البيانات باستخدام توابع وكائنات بسيطة في بايثون.

تعدّ Flask-SQLAlchemy إضافة لفلاسك تسهّل من استخدام SQLAlchemy ضمن فلاسك مؤمنةً الأدوات والوسائل المناسبة للتعامل مع قاعدة البيانات في تطبيقات فلاسك من خلال SQLAlchemy.

تُعرَّف علاقة قاعدة البيانات متعدّد-إلى-متعدّد many-to-many على أنها علاقةٌ بين جدولين، إذ يمكن لأي سجلٍ من الجدولين الارتباط مع عدّة سجلات من الآخر، فمثلًا في تطبيق مدونة يمكن لجدول التدوينات posts أن يرتبط بعلاقة من نوع متعدّد-إلى-متعدّد مع جدول أسماء المؤلفين (كُتَّاب التدوينات)، بمعنى أن كل تدوينة قد ترتبط بعدّة أسماء مؤلفين، وأيضًا قد يرتبط كل اسم مؤلف بعدّة تدوينات، وبالتالي فإنّ العلاقة ما بين التدوينات وأسماء المؤلفين هي علاقة متعدّد-إلى-متعدّد. أيُّ تطبيقٍ آخر من تطبيقات التواصل الاجتماعي هو مثالٌ آخر، إذ أن كل منشور قد يحتوي عدّة إشارات مرجعية، وكل إشارة مرجعية قد تتضمّن عدة منشورات.

سنعمل في هذا المقال على تعديل تطبيق مبني باستخدام كل من فلاسك والإضافة SQLAlchemy فيه، وذلك بإضافة علاقة من نوع متعدّد-إلى-متعدّد إليه، إذ سننشئ علاقة ما بين التدوينات والوسوم tags، بحيث يمكن لكل تدوينة أن تتضمّن عدّة وسوم، ويمكن أن يُشار للوسم الواحد في عدّة تدوينات.

يمكنك قراءة هذا المقال مُنفصلًا، إلّا أنّه تكملة لمقالنا السابق كيفية استخدام SQLAlchemy في فلاسك، وفيه قد بنينا قاعدة بيانات مُتعدّدة الجداول بعلاقة من نواع واحد إلى مُتعدّد one-to-many ما بين التدوينات والتعليقات عليها وذلك ضمن تطبيق مدونة.

سيتضمّن تطبيقك -مع نهاية هذا المقال- ميزةً جديدة تتمثّل بإمكانية إضافة الوسوم إلى التدوينات، بحيث يُشار إلى التدوينة الواحدة في عدّة وسوم، لتعرض صفحة الوسم الواحد كافّة التدوينات المُشار إليها من خلاله.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بُدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض، وفي هذا الصدد يمكنك الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.
(مُتطلّب اختياري) في الخطوة الأولى ستنسخ تطبيق المدونة الذي ستعمل عليه في هذا المقال، ولكن يمكنك بناءه من الصفر بدلًا من نسخه باتباعك للخطوات الواردة في المقال السابق، كما يمكنك الوصول إلى الشيفرة الكاملة للتطبيق من flask-slqa-bloggy.

الخطوة 1 - إعداد تطبيق الويب

سنعمل في هذه الخطوة على إعداد تطبيق المدونة ليكون جاهزًا للتعديل عليه، كما سنستعرض نماذج قاعدة بيانات Flask-SQLAlchemy ووجهات فلاسك لضمان فهمك الجيد لبنية التطبيق.

يمكنك تجاوز هذه الخطوة في حال اتباعك للمقال السابق المذكور آنفًا في فقرة مستلزمات العمل واحتفاظك بالشيفرة والبيئة الافتراضية على حاسوبك.

سنستخدم شيفرة التطبيق المبني في المقال السابق (راجع فقرة مستلزمات العمل) لشرح آلية إضافة علاقة من النوع متعدّد-إلى-متعدّد لتطبيق ويب مبني باستخدام فلاسك مع الإضافة Flask-SQLAlchemy؛ وهذا التطبيق هو مدونة يتيح إمكانية إضافة وعرض التدوينات والتعليق عليها، إضافةً إلى إمكانية قراءة التعليقات الموجودة وحذفها.

سننسخ الآن ملف الشيفرة من المستودع ونعيد تسميته من "flask-slqa-bloggy" ليصبح "flask_app" وذلك باستخدام الأمر التالي:

user@localhost:$ git clone https://github.com/do-community/flask-slqa-bloggy flask_app

ننتقل الآن إلى الملف "flask_app" على النحو التالي:

user@localhost:$ cd flask_app

ثمّ سننشئ بيئة افتراضية جديدة:

user@localhost:$ python -m venv env

ونفعّل هذه البيئة على النحو التالي:

user@localhost:$ source env/bin/activate

ونثبّت الآن كلًا من فلاسك والإضافة Flask-SQLAlchemy باستخدام الأمر:

(env)user@localhost:$ pip install Flask Flask-SQLAlchemy

ثمّ نضبط متغيرات البيئة التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

يشير متغيّر البيئة FLASK_APP إلى التطبيق الذي نعمل على تطويره حاليًا، وهو "app.py" في حالتنا، أمّا المتغير FLASK_ENV فيحدّد وضع التشغيل، وقد اخترناه ليكون وضع التطوير development الذي يوفّر إمكانية تنقيح الأخطاء في التطبيق، مع الانتباه إلى عدم استخدام وضع التشغيل هذا في بيئة الإنتاج.

والآن، سنفتح صَدَفَة فلاسك لإنشاء جداول قاعدة البيانات:

(env)user@localhost:$ flask shell

ومن ثمّ سنستورد الكائن db الخاص بقاعدة بيانات Flask-SQLAlchemy، بالإضافة إلى النموذج post الخاص بالتدوينات، والنموذج Comment الخاص بالتعليقات، لننشئ بعدها جداول قاعدة البيانات الموافقة للنماذج السابقة باستخدام الدالة ()db.create_all، كما يلي:

>>> from app import db, Post, Comment
>>> db.create_all()
>>> exit()

ومن ثمّ سنملأ قاعدة البيانات باستخدام البرنامج من الملف "init_db.py":

(env)user@localhost:$ python init_db.py

والذي سيضيف ثلاث تدوينات وأربعة تعليقات إلى قاعدة البيانات.

نشغّل الآن خادم التطوير:

(env)user@localhost:$ flask run

الآن وبالذهاب إلى المتصفّح، يصبح من الممكن الوصول إلى التطبيق عبر الرابط:

http://127.0.0.1:5000/

فتظهر صفحة شبيهة بما يلي:

وفي حال ظهور خطأ، تأكّد من اتباعك الخطوات السابقة على النحو الصحيح.

يمكنك إيقاف تشغيل خادم التطوير بالضغط على مفتاحي "CTRL+C" في لوحة المفاتيح.

فيما يلي سنمر على نماذج قاعدة البيانات Flask-SQLAlchemy بغية فهم العلاقات الحالية ما بين الجداول فيها، فإذا كانت محتويات الملف "app.py" مألوفةً يالنسبة لك من المقال السابق، فيمكنك تجاوز هذه الخطوة.

نفتح الآن الملف "app.py":

(env)user@localhost:$ nano app.py

فتظهر محتوياته على النحو التالي:

import os
from flask import Flask, render_template, request, redirect, url_for
from flask_sqlalchemy import SQLAlchemy

basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
           'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False


db = SQLAlchemy(app)


class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100))
    content = db.Column(db.Text)
    comments = db.relationship('Comment', backref='post')

    def __repr__(self):
        return f''


class Comment(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    content = db.Column(db.Text)
    post_id = db.Column(db.Integer, db.ForeignKey('post.id'))

    def __repr__(self):
        return f''


@app.route('/')
def index():
    posts = Post.query.all()
    return render_template('index.html', posts=posts)


@app.route('//', methods=('GET', 'POST'))
def post(post_id):
    post = Post.query.get_or_404(post_id)
    if request.method == 'POST':
        comment = Comment(content=request.form['content'], post=post)
        db.session.add(comment)
        db.session.commit()
        return redirect(url_for('post', post_id=post.id))

    return render_template('post.html', post=post)


@app.route('/comments/')
def comments():
    comments = Comment.query.order_by(Comment.id.desc()).all()
    return render_template('comments.html', comments=comments)


@app.post('/comments//delete')
def delete_comment(comment_id):
    comment = Comment.query.get_or_404(comment_id)
    post_id = comment.post.id
    db.session.delete(comment)
    db.session.commit()
    return redirect(url_for('post', post_id=post_id))

وفيه لدينا نموذجي قاعدة بيانات يمثلان جدولين، هما:

الجدول Post: والذي يتضمّن عمودًا لكل من معرّف التدوينة وعنوانها ومضمونها، إضافةً إلى علاقة من النوع واحد-إلى-مُتعدّد مع جدول التعليقات.
الجدول Comment: والذي يتضمّن عمودًا لكل من معرّف التعليق ومحتواه، إضافةً إلى عمود لمعرّف التدوينة post_id للإشارة إلى التدوينة التي يتبع لها التعليق.

كما يتضمّن الملف بعد النموذجين كل من الوجهات التالية:

/: الصفحة الرئيسية للتطبيق، والتي تعرض كافّة التدوينات الموجودة في قاعدة البيانات.
//: الصفحة الخاصّة بكل تدوينة، فمثلًا يعرض الرابط "/http://127.0.0.1:5000/2" تفاصيل التدوينة الثانية من قاعدة البيانات مع التعليقات عليها.
/comments/: صفحة لعرض كافّة التعليقات من قاعدة البيانات مع روابط التدوينات التي يتبع لها كل تعليق.
comments//delete/: وجهة مُخصّصة لحذف التعليقات باستخدام زر أوامر باسم حذف تعليق Delete Comment.

نغلق الآن الملف app.py.

سنستخدم في الخطوة التالية علاقة من نوع مُتعدّد-إلى-مُتعدّد للربط بين الجدولين المذكورين سابقًا.

الخطوة 2 - إعداد نماذج قاعدة بيانات لإنشاء علاقة من نوع متعدد-إلى-متعدد

سنضيف في هذه الخطوة نموذج قاعدة البيانات المُمثّل لجدول الوسوم، والذي سنربطه مع جدول التدوينات الحالي باستخدام "جدول ارتباط association table"، والذي يعرّف بأنّه جدول وسيط يربط بين جدولين بعلاقة مُتعدّد-إلى-مُتعدّد.

تربط العلاقة مُتعدّد-إلى-مُتعدّد بين جدولين، بحيث يتعلّق كل عنصر من أحدهما بعدّة عناصر من الآخر، وتشير كل تدوينة في جدول الارتباط إلى وسومها، كما يشير كل وسم إلى كافّة التدوينات المُتضمّنة له.

سنضيف أيضًا في هذه الخطوة بعضًا من التدوينات والوسوم إلى قاعدة البيانات، لنتمكن لاحقًا من عرض التدوينات مع وسوم كل منها أو الوسوم مع التدوينات المُتضمّنة لكل منها.

ليكن لدينا جدول تدوينات بسيط على النحو التالي:

Posts
+----+-----------------------------------+
| id | content                           |
+----+-----------------------------------+
| 1  | A post on life and death          |
| 2  | A post on joy                     |
+----+-----------------------------------+

وجدولًا للوسوم كما يلي:

Tags
+----+-------+
| id | name  |
+----+-------+
| 1  | life  |
| 2  | death |
| 3  | joy   |
+----+-------+

يمكننا مثلًا إضافة كل من الوسمين "life" و "death" إلى التدوينة "A post on life and death" عن طريق إضافة عمود جديد إلى جدول التدوينات، ليصبح بالشّكل:

Posts
+----+-----------------------------------+------+
| id | content                           | tags |
+----+-----------------------------------+------+
| 1  | A post on life and death          | 1, 2 |
| 2  | A post on joy                     |      |
+----+------------------------------------------+

لن تعمل هذه المنهجية لأنّ كل عمود يجب أن يتضمّن قيمة واحدة، وفي حال وجود عدّة قيم للعمود الواحد من السجل، ستصبح العمليات الأساسية مثل إضافة البيانات وتحديثها مرهقة وبطيئة، وسنستخدم بدلًا من ذلك جدولًا إضافيًا ثالثًا ليشير إلى المفاتيح الأساسية ويربط بينها وبين الجداول المرتبطة، وهو ما ندعوه بجدول الارتباط أو جدول الصلة join table، والذي سيخزّن معرّفات كل عنصر من كل جدول.

وفيما يلي مثال لجدول ارتباط يربط بين جدولي التدوينات والوسوم:

post_tag
+----+---------+-------------+
| id | post_id | tag_id      |
+----+---------+-------------+
| 1  | 1       | 1           |
| 2  | 1       | 2           |
+----+---------+-------------+

ترتبط التدوينة ذات المعرّف رقم "1" (وهي "A post on life and death") مع الوسم ذي المعرّف رقم "1" (وهو "life") في السجل الأوّل من الجدول السابق؛ أمّا في السجل الثاني، فترتبط التدوينة الأولى نفسها أيضًا مع الوسم ذو المعرّف رقم "2" (وهو "death")، ما يعني أنّ التدوينة الأولى تتضمّن كلا الوسمين "life" و "death"، ويمكن ربط كل تدوينة بوسومات متعدّدة بنفس الآلية.

سنعدّل الآن الملف app.py لإضافة نموذج قاعدة بيانات جديد ليمثّل الجدول الذي سنستخدمه لتخزين الوسوم، كما سنضيف جدول ارتباط باسم "post_tag" لربط التدوينات بالوسوم.

لذا، سنفتح بدايةً الملف app.py بغية إنشاء العلاقة ما بين التدوينات والوسوم:

(env)user@localhost:$ nano app.py

سنضيف الآن جدول post_tag ونموذج باسم Tag بعد كائن قاعدة البيانات db وقبل النموذج Post، ومن ثمّ سنضيف للنموذج Post عمودًا علاقيًا زائفًا للوسوم باسم tags لنمكّن لاحقًا من الوصول إلى وسوم التدوينة باستخدام التعليمة post.tags أو الوصول إلى التدوينات المُتضمّنة وسمًا ما باستخدام التعليمة tag.posts.

# ...

db = SQLAlchemy(app)


post_tag = db.Table('post_tag',
                    db.Column('post_id', db.Integer, db.ForeignKey('post.id')),
                    db.Column('tag_id', db.Integer, db.ForeignKey('tag.id'))
                    )


class Tag(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))

    def __repr__(self):
        return f'' 



class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100))
    content = db.Column(db.Text)
    comments = db.relationship('Comment', backref='post')
    tags = db.relationship('Tag', secondary=post_tag, backref='posts')

    def __repr__(self):
        return f''

احفظ الملف واغلقه.

استخدمنا في الشيفرة السابقة الدالة ()db.Table لإنشاء جدول بعمودين، إذ أنّ الإجراء الأفضل بالنسبة لجدول الارتباط هو استخدام جدول بدلًا من نموذج قاعدة بيانات، وهنا يمتلك الجدول post_tag عمودين يمثلان مفتاحين خارجيين foreign keys أي المفتاحين المستخدمين للإشارة إلى أعمدة المفاتيح الأساسية في الجداول الأصل (المفتاح الأساسي لجدول ما هو مفتاح أجنبي عند تواجده في جدول آخر):

post_id: وهو مفتاح خارجي من نوع عدد صحيح يمثّل معرّف التدوينة ويشير إلى عمود المُعرّف ID في جدول التدوينات post.
tag_id: وهو مفتاح خارجي من نوع عدد صحيح يمثّل معرّف الوسم ويشير إلى عمود المُعرّف ID في جدول الوسوم tag.

ستُنشئ هذه المفاتيح العلاقات ما بين الجداول.

وبعد الانتهاء من الجدول post_tag، أنشأنا النموذج Tag الممثّل للجدول الذي سنخزّن ضمنه الوسوم، ويحتوي هذا الجدول على عمودين:

id: معرّف الوسم.
name: اسم الوسم.

استخدمنا اسم الوسم ضمن التابع الخاص ()__repr__ بغية إعطاء كل كائن وسم تمثيلًا محرفيًا واضحًا لأسباب تنقيحية، كما أضفنا متغير صنف للوسوم باسم tags ضمن النموذج Post، وذلك باستخدام التابع ()db.relationship ممررين إليه اسم نموذج الوسوم، وهو Tag في حالتنا.

مرّرنا جدول الارتباط post_tag إلى المعامل الثاني secondary من التابع بغية إنشاء علاقة من نوع مُتعدّد-إلى-مُتعدّد ما بين التدوينات والوسوم. استخدمنا المعامل backref لإضافة مرجعٍ عكسي back reference يلعب ما يشبه دور العمود في النموذج Tag، وبذلك يصبح من الممكن الوصول تدوينات الوسم المُحدّد عبر التعليمة tag.posts ووسوم تدوينة ما باستخدام التعليمة post.tags، وسنعرض مثالًا يوضّح هذه الفكرة لاحقًا.

أمّا الآن فسنحرّر برنامج بايثون "init_db.py" لتعديل قاعدة البيانات بإضافة كل من جدول الارتباط post_tag وجدول الوسوم المبني استنادًا إلى نموذج الوسوم Tag، على النحو التالي:

(env)user@localhost:$ nano init_db.py

ونعدّل الملف ليصبح كما يلي:

from app import db, Post, Comment, Tag

db.drop_all()
db.create_all()

post1 = Post(title='Post The First', content='Content for the first post')
post2 = Post(title='Post The Second', content='Content for the Second post')
post3 = Post(title='Post The Third', content='Content for the third post')

comment1 = Comment(content='Comment for the first post', post=post1)
comment2 = Comment(content='Comment for the second post', post=post2)
comment3 = Comment(content='Another comment for the second post', post_id=2)
comment4 = Comment(content='Another comment for the first post', post_id=1)

tag1 = Tag(name='animals')
tag2 = Tag(name='tech')
tag3 = Tag(name='cooking')
tag4 = Tag(name='writing')

post1.tags.append(tag1)  # Tag the first post with 'animals'
post1.tags.append(tag4)  # Tag the first post with 'writing'
post3.tags.append(tag3)  # Tag the third post with 'cooking'
post3.tags.append(tag2)  # Tag the third post with 'tech'
post3.tags.append(tag4)  # Tag the third post with 'writing'


db.session.add_all([post1, post2, post3])
db.session.add_all([comment1, comment2, comment3, comment4])
db.session.add_all([tag1, tag2, tag3, tag4])

db.session.commit()

احفظ الملف واغلقه.

استوردنا في الشيفرة السابقة النموذج Tag، كما حذفنا كل محتويات قاعدة البيانات باستخدام الدالة ()db.drop_all بغية إضافة كل من جدول الوسوم والجدول post_tag بأمان، متجنبين بذلك وقوع أي من المشاكل الشائعة التي قد تحدث لدى إضافة جداول جديدة إلى قاعدة البيانات. أنشأنا بعد ذلك جميع الجداول مُجدّدًا باستخدام الدالة ()db.create_all.

يمكننا -بعد تصريح الشيفرة من المقال السابق عن التدوينات والتعليقات- استخدام نموذج الوسوم Tag لإنشاء أربعة وسوم، ومن ثم إضافة الوسوم إلى التدوينات باستخدام السمة tags، التي أُضيفت عبر السطر البرمجي:

tags = db.relationship('Tag', secondary=post_tag, backref='posts')

من الملف app.py. كما خصّصنا الوسوم للتدوينات باستخدام تابع الإسناد ()append الشبيه بقوائم بايثون.

أُضيفت بعد ذلك الوسوم المُنشأة إلى جلسة قاعدة البيانات باستخدام الدالة ()db.session.add_all.

ملاحظة: لا تعيد الدالة ()db.create_all إنشاء جدول موجود أصلًا ولا تحدثّه، فعلى سبيل المثال، لو عدّلنا أحد النماذج بإضافة عمود جديد إليه، ثمّ استخدمنا الدالة ()db.create_all فلن يُطبَّق هذا التغيير على الجدول في حال كان هذا الجدول موجود أصلًا. ويكون الحل بحذف كافّة الجداول الموجودة في قاعدة البيانات باستخدام الدالة ()db.drop_all ومن ثمّ إعادة إنشائها باستخدام الدلة ()db.create_all كما هو موضّح في الملف "init_db.py".

تضمن هذه الآلية تطبيق التغييرات المُنفّذة على النماذج إلّا أنّها ستتسبب بحذف كافّة البيانات الموجودة في الجداول. من الممكن تهجير ملف تخطيط قاعدة البيانات Schema migration بغية تحديث قاعدة البيانات مع الحفاظ على البيانات الموجودة ضمنها، وهذا التهجير سيسمح بتعديل الجداول مع الحفاظ على البيانات فيها، إذ يمكننا استخدام الإضافة Flask-Migrate لإجراء ترحيل لملف تخطيط قاعدة بيانات SQLAlchemy عن طريق واجهة سطر أوامر فلاسك.

سنشغّل الآن البرنامج init_db.py لتطبيق التغييرات على قاعدة البيانات:

(env)user@localhost:$ python init_db.py

يُفترض في هذه المرحلة أن يُنفّذ البرنامج بنجاح دون ظهور أي خرج، أمّا في حال ظهور رسالة خطأ، فتأكّد من كونك قد أجريت التغييرات الصحيحة على الملف init_db.py.

ولإلقاء نظرة على التدوينات والوسوم الموجودة حاليًا في قاعدة البيانات، سنفتح صَدَفَة فلاسك:

(env)user@localhost:$ flask shell

ثمّ سننفّذ الشيفرة التالية التي ستمر على كافّة التدوينات والوسوم:

from app import Post

posts = Post.query.all()

for post in posts:
    print(post.title)
    print(post.tags)
    print('---')

استوردنا في الشيفرة السابقة نموذج التدوينات Post من الملف app.py، واستعلمنا عن جدول التدوينات جالبين منه كافّة التدوينات الموجودة في قاعدة البيانات، ومررنا بعدها على كل تدوينة لنعرض عنوانها وقائمة الوسوم المرتبطة بها، وسيظهر الخرج كما يلي:

Post The First
[<Tag "animals">, <Tag "writing">]
---
Post The Third
[<Tag "cooking">, <Tag "tech">, <Tag "writing">]
---
Post The Second
[]
---

يمكنك الوصول إلى أسماء الوسوم باستخدام الأمر tag.name كما هو مبين في المثال التالي، والذي يمكنك تشغيله باستخدام صَدَفَة فلاسك:

from app import Post

posts = Post.query.all()

for post in posts:
    print('TITLE: ', post.title)
    print('-')
    print('TAGS:')
    for tag in post.tags:
        print('> ', tag.name)
    print('-'*30)

وفي هذه الحالة وبالإضافة إلى طباعة عنوان كل تدوينة، نمرّ على وسوم كل منها ونطبع أسماءها، لنحصل على خرجٍ على النحو التالي:

TITLE:  Post The First
-
TAGS:
>  animals
>  writing
------------------------------
TITLE:  Post The Third
-
TAGS:
>  cooking
>  tech
>  writing
------------------------------
TITLE:  Post The Second
-
TAGS:
------------------------------

نلاحظ مما سبق أنّ الوسوم المُضافة إلى التدوينات في البرنامج init_db.py متموضعة بمكانها الصحيح بالنسبة للتدوينات.

وللاطلاع على مثال لتوضيح كيفية الوصول إلى التدوينات التابعة لكل وسم باستخدام التعليمة tag.posts، سنشغّل الشيفرة التالية في صّدّفّة فلاسك:

from app import Tag

writing_tag = Tag.query.filter_by(name='writing').first()

for post in writing_tag.posts:
    print(post.title)
    print('-'*6)
    print(post.content)
    print('-')
    print([tag.name for tag in post.tags])
    print('-'*20)

استوردنا في الشيفرة السابقة النموذج Tag، ثمّ استخدمنا تابع الترشيح ()filter_by على سمة الاستعلام query ممررين إليه معامل الاسم name ليحصل على الوسم writing، ونحصل على أوّل نتيجة باستخدام التابع ()first، ثم خزّنا كائن الوسم الناتج ضمن متغير باسم writing_tag. للمزيد حول تابع الترشيح filter_by ننصحك بقراءة الخطوة 4 من المقال استخدام الإضافة Flask-SQLAlchemy للتخاطب مع قواعد البيانات في تطبيقات فلاسك.

مررنا بعد ذلك على جميع التدوينات المُتضمّنة للوسم writing، والتي وصلنا إليها باستخدام التعليمة writing_tag.posts، لنطبع عنوان كل تدوينة ومحتواها وقائمة بأسماء الوسوم الخاصّة بها والتي أنشأناها باستخدام طريقة استيعاب القائمة list comprehension المعتمدة على وسوم التدوينة، التي يمكننا الوصول إليها باستخدام الأمر post.tags.

ويكون الخرج على النحو التالي:

Post The Third
------
Content for the third post
-
['cooking', 'tech', 'writing']
--------------------
Post The First
------
Content for the first post
-
['animals', 'writing']
--------------------

نرى في الخرج السابق التدوينتان المُتضمنتان للوسم writing مع قائمة بايثون بأسماء كافّة وسوم كل من التدوينتين.

ومع نهاية هذه الخطوة أصبح من الممكن الوصول إلى التدوينات ووسوم كل منها أو إلى التدوينات المُتضمّنة لوسم معيّن، إذ أضفنا نموذج قاعدة بيانات ليمثّل جدول الوسوم، وربطنا ما بين جدولي التدوينات والوسوم باستخدام جدول ارتباط، كما أدخلنا عددًا من الوسوم إلى قاعدة البيانات واستخدمناها للإشارة إلى التدوينات، وأصبح من الممكن الوصول إلى التدوينات ووسوم كل منها أو إلى التدوينات المُتضمّنة لوسم ما.

سنستخدم في الخطوة التالية صَدَفَة فلاسك لإضافة تدوينات ووسوم جديدة والربط فيما بينها، كما سنتعرّف على كيفية حذف وسوم من تدوينة ما.

الخطوة 3 - إدارة البيانات في العلاقة متعدد-إلى-متعدد

سنستخدم في هذه الخطوة صَدَفَة فلاسك لإضافة تدوينات ووسوم جديدة إلى قاعدة البيانات والربط فيما بينها، إذ سنتمكّن من الوصول إلى كل تدوينة مع وسومها، وسنتعرّف على كيفية فك ارتباط عنصرين في العلاقة مُتعدّد-إلى-مُتعدّد.

بدايةً وفي حال كون صَدَفَة فلاسك غير مفتوحة أصلًا، نفتحها مع التأكّد من كون البيئة البرمجية مُفعّلة، كما يلي:

(env)user@localhost:$ flask shell

سنضيف بعد ذلك بضعة تدويناتٍ ووسوم:

from app import db, Post, Tag

life_death_post = Post(title='A post on life and death', content='life and death')
joy_post = Post(title='A post on joy', content='joy')

life_tag = Tag(name='life')
death_tag = Tag(name='death')
joy_tag = Tag(name='joy')

life_death_post.tags.append(life_tag)
life_death_post.tags.append(death_tag)
joy_post.tags.append(joy_tag)

db.session.add_all([life_death_post, joy_post, life_tag, death_tag, joy_tag])

db.session.commit()

وهذا ما سيُنشئ بالنتيجة تدوينتين وثلاثة وسوم. إذ أشرنا إلى التدوينات باستخدام الوسوم الموافقة، كما استخدمنا التابع ()add_all لإضافة العناصر المُنشأة حديثًا إلى جلسة قاعدة البيانات. ونهايةً أكدنا التغييرات وطبّقناها على قاعدة البيانات باستخدام التابع ()commit.

فيما يلي سنستخدم صَدَفة فلاسك للحصول على كافّة التدوينات ووسومها كما فعلنا في الخطوة السابقة، على النحو التالي:

posts = Post.query.all()

for post in posts:
    print(post.title)
    print(post.tags)
    print('---')

فنحصل على خرجٍ شبيه بما يلي:

Post The First
[, ]
---
Post The Third
[, , ]
---
Post The Second
[]
---
A post on life and death
[, ]
---
A post on joy
[]
---

وبذلك نجد أنّ التدوينات قد أُضيفت مع وسوم كل منها.

الآن وبغية توضيح كيفية فك ارتباط عنصرين ضمن علاقة قاعدة البيانات من النوع مُتعدّد-إلى-مُتعدّد، سنفرض على سبيل المثال أنّ التدوينة الثالثة Post The Third لم تعد معنية بالطبخ، وبالتالي يجب أن نحذف الوسم cooking منها.

لتحقيق ذلك، سنجلب بدايةً التدوينة مع الوسم المراد حذفه، كما يلي:

>>> from app import db, Post, Tag
>>> post = Post.query.filter_by(title='Post The Third').first()
>>> tag = Tag.query.filter_by(name='cooking').first()
>>> print(post.title)
>>> print(post.tags)
>>> print(tag.posts)

جلبنا في الشيفرة السابقة التدوينة ذات العنوان Post The Third باستخدام التابع ()filter_by، كما جلبنا الوسم cooking، لنطبع كل من عنوان التدوينة ووسومها وكافّة التدوينات المُتضمّنة للوسم cooking.

يعيد التابع ()filter_by كائن استعلام، وباستخدام التابع ()all نحصل على نتائج هذا الاستعلام ضمن قائمة، ولكن وبما أنّنا نتوقّع الحصول على نتيجة واحدة من الاستعلام في هذه الحالة، فاستخدمنا التابع ()first للحصول فقط على النتيجة الأولى، وللمزيد حول كل من التابعين ()first و ()all، ننصحك بقراءة الخطوة 4 من المقال استخدام الإضافة Flask-SQLAlchemy للتخاطب مع قواعد البيانات في تطبيقات فلاسك.

ويكون الخرج في هذه الحالة على النحو التالي:

Post The Third


[, , ]


[]

وفيه نرى عنوان التدوينة ووسومها، مع قائمة بكافّة التدوينات المُتضمّنة للوسم cooking.

الآن وبغية حذف الوسم cooking من التدوينة، سنستخدم التابع ()remove كما يلي:

>>> post.tags.remove(tag)
>>> db.session.commit()
>>> print(post.tags)
>>> print(tag.posts)

استخدمنا في الشيفرة السابقة التابع ()remove لفصل الوسم cooking عن التدوينة، ثمّ استخدمنا التابع ()db.session.commit لتطبيق التغييرات على قاعدة البيانات، فنحصل على خرجٍ يؤكّد حذف الوسم من التدوينة، على النحو التالي:

[, ]

[]

وبذلك نجد أنّ الوسم cooking قد حُذف فعلًا من القائمة post.tags، كما أنّ التدوينة لم تعد موجودةً ضمن قائمة التدوينات tag.posts المُتضمّنة لهذا الوسم.

نُغلق الآن صَدَفَة فلاسك:

>>> exit()

ومع نهاية هذه الخطوة نكون قد أضفنا تدويناتٍ ووسوم جديدة، كما أضفنا الوسوم إلى التدوينات وحذفناها منها.

سنعمل في الخطوة التالية على عرض الوسوم الخاصّة بكل تدوينة في صفحة تطبيق المدونة الرئيسية.

الخطوة 4 - عرض الوسوم أسفل كل تدوينة

سنحرّر في هذه الخطوة قالب الصفحة الرئيسية لعرض الوسوم الخاصّة بكل تدوينة أسفلها. لذا، اطلع بدايةً على البنية الحالية للصفحة الرئيسية للتطبيق.

أعلم فلاسك بالتطبيق المطلوب تشغيله وهو في حالتنا الملف app.py باستخدام متغير البيئة FLASK_APP وذلك بعد التأكد من أن البيئة البرمجية مُفعّلة، واضبط متغير البيئة FLASK_ENV على وضع التطوير development، على النحو التالي:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

شغّل البرنامج الآن:

(env)user@localhost:$ flask run

وأثناء كون خادم التطوير قيد التشغيل، انتقل إلى الرابط التالي باستخدام المُتصفح:

http://127.0.0.1:5000/

فستظهر لك صفحة شبيهة بالشّكل التالي:

نترك خادم التطوير قيد التشغيل ونفتح نافذة سطر أوامر جديدة.

نريد في هذه المرحلة عرض كافّة وسوم كل تدوينة ضمن صفحتين من صفحات التطبيق: الأولى في الصفحة الرئيسية أسفل كل تدوينة، والثانية في الصفحة المُخصّصة لكل تدوينة لتظهر الوسوم أسفل محتواها، إذ سنستخدم في الحالتين نفس الشيفرة لعرض الوسوم، لذا ولتجنّب التكرار سنستخدم ماكرو جينجا jinja macro، الذي يعمل مثل أي دالة في بايثون ويتضمّن شيفرة HTML ديناميكية قابلة للاستخدام في أي مكان يُستدعى فيه الماكرو؛ وفي حال التعديل عليه، سيُعدّل تلقائيًا في كافّة الأماكن المُستدعى فيها ما يجعل الشيفرة قابلة لإعادة الاستخدام.

لذا، سننشئ ملفًا جديدًا باسم "macros.html" ضمن مجلد القوالب templates، على النحو التالي:

(env)user@localhost:$ nano templates/macros.html

ونكتب ضمنه الشيفرة التالية:

{% macro display_tags(post) %}
     class="tags">
        
            
Tags:
            {% for tag in post.tags %}
                 href="#" style="text-decoration: none; color: #dd5b5b">
                    {{ tag.name }}
                
                |
            {% endfor %}
        
    
{% endmacro %}

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة الكلمة المفتاحية macro للتصريح عن ماكرو باسم ()display_tags ذو معامل باسم post، إذ استخدمنا الوسم

ليعرض عنوانًا من المستوى الرابع

، كما استخدمنا حلقة for تكرارية بغية المرور على كافّة وسوم كائن التدوينة المُمرّرة مثل وسيط إلى الماكرو المُستدعى، كما هو الحال لدى تمرير أي وسيط لدالة بايثون اعتيادية مُراد استدعاؤها.

حصلنا على وسوم كل تدوينة باستخدام التعليمة post.tags، لنعرض اسم الوسم ضمن وسم رابط ، إذ سنعدّل لاحقًا قيمة السمة href لوسم الرابط لنجعله يشير إلى صفحة مُخصّصة للوسم سننشئها لاحقًا لتعرض كافّة التدوينات المُتضمّنة للوسم المُحدّد. نهايةً، استخدمنا الكلمة المفتاحية endmacro للدلالة على انتهاء الماكرو.

الآن، وبغية عرض كافّة الوسوم التابعة للتدوينة أسفلها في الصفحة الرئيسية للتطبيق، سنفتح ملف القالب index.html:

(env)user@localhost:$ nano templates/index.html

وسنستورد بدايةً الماكرو ()display_tags من الملف "macros.html"، لذا سنضيف الاستيرادات التالية إلى بداية الملف قبل السطر {% extends 'base.html' %}، كما يلي:

{% from 'macros.html' import display_tags %}
{% extends 'base.html' %}

سنعدّل بعد ذلك الحلقة التكرارية for post in posts لتتضمّن استدعاءً للماكرو ()display_tags على النحو التالي:

{% for post in posts %}
     class="post">
        #{{ post.id }}
        
             class="title">
                 href="{{ url_for('post', post_id=post.id)}}">
                    {{ post.title }}
                
            
        
         class="content">
            {{ post.content }}

{% endfor %}

نحفظ الملف ونغلقه.

استدعينا في الشيفرة السابقة الشيفرة الجامعة ()display_tags ممررين إليها الكائن post، وهذا ما سيعرض بالنتيجة أسماء الوسوم أسفل كل تدوينة.

الآن، بتحديث الصفحة الرئيسية للتطبيق، نرى الوسوم أسفل كل تدوينة كما في الشّكل:

أمّا الآن فسنعمل على إضافة الوسوم أسفل محتوى التدوينة في الصفحة المُخصّصة لها. لذا، نفتح ملف القالب post.html:

(env)user@localhost:$ nano templates/post.html

ونستورد في بدايته الماكرو display_tags بالشّكل:

{% from 'macros.html' import display_tags %}
{% extends 'base.html' %}

ونستدعي بعد ذلك الماكرو ()display_tags ممررين إليه الكائن post أسفل محتوى التدوينة وقبل وسم الفاصل الأفقي

على النحو التالي:

 class="post">
    #{{ post.id }}
    
         class="title">{{ post.title }}
    
     class="content">
        {{ post.content }}
    

    {{ display_tags(post) }}

    
    Comments

نحفظ الملف ونغلقه.

الآن وبالانتقال إلى صفحة التدوينة (الثانية مثلًا) باستخدام الرابط:

http://127.0.0.1:5000/2

نرى الوسوم معروضة أسفل محتوى التدوينة بنفس طريقة عرضها في الصفحة الرئيسية للتطبيق.

سنعمل في الخطوة التالية على إضافة وجهة جديدة إلى تطبيق فلاسك هذا لتعرض كافّة التدوينات المُتضمّنة لوسم معيّن، كما سنجعل رابط الوسم الذي أضفناه في هذه الخطوة فعّالًا.

الخطوة 5 - عرض الوسوم وتدويناتها

سنضيف في هذه الخطوة وجهةً وقالبًا إلى التطبيق لعرض الوسوم الموجودة في قاعدة البيانات مع التدوينات المُتضمّنة لكل منها.

لذا، سنضيف بدايةً وجهةً لعرض التدوينات المُتضمّنة لكل وسم، فعلى سبيل المثال، ستعرض الوجهة /tags/tag_name/ صفحةً تحتوي كافّة التدوينات المُتضمّنة للوسم المُحدّد في الجزء المُخصّص لاسم الوسم المطلوب tag_name من الوجهة.

نقتح الآن الملف app.py لتحريره:

(env)user@localhost:$ nano app.py

ونضيف الوجهة التالية إلى نهايته:

# ...

@app.route('/tags//')
def tag(tag_name):
    tag = Tag.query.filter_by(name=tag_name).first_or_404()
    return render_template('tag.html', tag=tag)

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة متغير الرابط tag_name المسؤول عن تحديد كل من الوسم والتدوينات المُتضمّنة لهذا الوسم والتي ستُعرض ضمن صفحة الوسم، إذ يُمرّر اسم الوسم إلى الدالة ()tag العاملة في فلاسك باستخدام المعامل tag_name المُستخدم أيضًا ضمن تابع الترشيح ()filter_by للاستعلام عن الوسم المطلوب.

استخدمنا التابع ()first_or_404 للحصول على كائن الوسم، فإمّا أن يُخزّن في حال وجوده ضمن متغير باسم tag، وإلّا سنحصل على رسالة الخطأ "‎404 Not Found" في حال عدم وجود وسم في قاعدة البيانات باسم مطابق للاسم المطلوب. ثمّ صيّرنا ملف قالب باسم "tag.html" مُمررين إليه الكائن tag.

سنفتح الآن القالب الجديد "templates/tag.html" بغية تحريره:

(env)user@localhost:$ nano templates/tag.html

ونكتب ضمنه الشيفرة التالية:

{% from 'macros.html' import display_tags %}
{% extends 'base.html' %}

{% block content %}
     class="title">
        {% block title %} Posts Tagged with "{{ tag.name }}" {% endblock %}
    
     class="content">
        {% for post in tag.posts %}
         class="post">
            #{{ post.id }}
            
                 class="title">
                     href="{{ url_for('post', post_id=post.id)}}">
                        {{ post.title }}
                    
                
            
             class="content">
                {{ post.content }}
            

            {{ display_tags(post) }}

            
        
        {% endfor %}
    
{% endblock %}

نحفظ الملف ونغلقه.

استوردنا في الشيفرة السابقة الماكرو ()display_tags من الملف "macros.html"، واستخدمنا القالب الرئيسي بالاعتماد على تعليمة extend. كما عيّنا ترويسةً ضمن كتلة المحتوى لتعمل مثل عنوان مُتضمنةً اسم الوسم، مرّرنا بعد ذلك على كافّة التدوينات المُتضمّنة للوسم المطلوب والتي قد وصلنا إليها باستخدام التعليمة tag.posts، لنعرض معرّف التدوينة وعنوانها ومحتواها، ومن ثمّ استدعينا الماكرو ()display_tags لعرض كافّة الوسوم التابعة للتدوينة.

الآن ومع كون خادم التطوير قيد التشغيل، ننتقل إلى الرابط التالي باستخدام المُتصفّح:

http://127.0.0.1:5000/tags/writing/

وهي الصفحة المُخصّصة للوسم writing، وكما هو موضّح في الصورة أدناه فإنّ كافّة الوسوم المُتضمّنة للوسم writing معروضةٌ في هذه الصفحة.

أمّا الآن فسنعدّل الماكرو ()display_tags لجعل روابط الوسوم فعّالة، لذا سنفتح الملف "macros.html":

(env)user@localhost:$ nano templates/macros.html

ونعدّل قيمة السمة href كما يلي:

{% macro display_tags(post) %}
     class="tags">
        
            
Tags:
            {% for tag in post.tags %}
             href="{{ url_for('tag', tag_name=tag.name) }}"
               style="text-decoration: none; color: #dd5b5b">
                    {{ tag.name }}
                
                |
            {% endfor %}
        
    
{% endmacro %}

نحفظ الملف ونغلقه.

الآن وبتحديث الصفحات التي استخدمنا فيها الماكرو ()display_tags، نلاحظ أنّ روابط الوسوم أصبحت فعّالة:

http://127.0.0.1:5000/
http://127.0.0.1:5000/2/
http://127.0.0.1:5000/tags/writing/

وبذلك نجد أنّ استخدام الماكرو المُقدّمة من محرّك القوالب جينجا سمح بإعادة استخدام الشيفرة وبالتالي تقليل التكرار، ناهيك عن حقيقة كون تعديل ملف الماكرو الرئيسي كفيل بتطبيق التغييرات على كافّة القوالب المُستخدِمة له.

ومع نهاية هذه الخطوة أصبح لدينا صفحة خاصّة بكل وسم يتمكّن من خلالها المُستخدمون من رؤية كافّة التدوينات المُتضمّنة لوسم معيّن، إذ يمكن الوصول إلى صفحة الوسم هذه من خلال النقر على الوسوم أسفل كل تدوينة كونها تتضمّن روابط إلى الصفحة الخاصّة بالوسم.

الخاتمة

وضحنا في هذا المقال كيفية إدارة العلاقات من نوع مُتعدّد-إلى-مُتعدّد باستخدام الإضافة Flask-SQLAlchemy وذلك بإضافة ميزة الوسوم إلى تطبيق المدونة السابق، إذ تعرفنا على كيفية ربط جدولين باستخدام جدول الارتباط (والذي يُدعى أيضًا جدول الصلة)، وكيفية ربط المدخلات ببعضها وإضافتها إلى قاعدة البيانات والوصول إلى البيانات وفك ارتباطها عن أحد المُدخلات.

ترجمة -وبتصرف- للمقال How To Use Many-to-Many Database Relationships with Flask-SQLAlchemy لصاحبه Abdelhadi Dyouri.

كيفية استخدام SQLAlchemy في فلاسك

Thu, 09 Feb 2023 16:08:02 +0000

يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا العديد من الأدوات والميزات التي من شأنها إنشاء تطبيقات ويب في لغة بايثون.

أمّا SQLAlchemy، فهي أداةٌ في محرك قواعد البيانات SQL تؤمن وصولًا فعالًا وعالي الأداء إلى قواعد البيانات العلاقية، كما توفّر طرقًا للتخاطب مع العديد من محركات قواعد البيانات مثل SQLite، و MySQL، و PostgreSQ، مانحةً إمكانية الوصول إلى آليات SQL الخاصة بقواعد البيانات، كما توفّر مُخطِّط الكائنات العلاقية Object Relational Mapper -أو اختصارًا ORM- ليتيح إمكانية إنشاء الاستعلامات والتعامل مع البيانات باستخدام توابع وكائنات بسيطة في بايثون.

تُعدّ Flask-SQLAlchemy إضافة لفلاسك تسهّل من استخدام SQLAlchemy ضمنه وتؤمن الأدوات والوسائل المناسبة للتعامل مع قاعدة البيانات في تطبيقات فلاسك من خلال SQLAlchemy.

تُعرَّف علاقة قاعدة البيانات من النوع واحد-إلى-متعدد one-to-many بكونها علاقةً بين جدولين من قاعدة البيانات، بحيث يمكن لسجلٍ موجودٍ في أحد الجدولين الإشارة إلى عدّة سجلات من الجدول الثاني، ويشكّل تطبيق المدونة خير مثال على العلاقات في قواعد البيانات من النوع واحد-إلى-متعدد، نظرًا لارتباط الجدول الخاص بتخزين التدوينات posts مع الجدول الخاص بتخزين التعليقات comments بعلاقة من نوع واحد-إلى-متعدد؛ إذ يمكن أن يكون لكل تدوينة عدّة تعليقاتٍ مرتبطةٍ بها، وبالمقابل يرتبط كل تعليق بتدوينة واحدةٍ فقط، وبذلك فإنّ للتدوينة الواحدة علاقةٌ بالعديد من التعليقات. يُعد الجدول الخاص بالتدوينات في هذه الحالة الجدول الأب parent، في حين يُعد الجدول الخاص بالتعليقات الجدول الابن child؛ إذ يمكن للسجل الموجود في الجدول الأب الإشارة إلى عدّة سجلات موجودة في الجدول الابن، وهو أمرٌ أساسي لإتاحة إمكانية الوصول إلى البيانات المطلوبة في كل جدول.

سنعمل في هذا المقال على بناء مدونة ويب صغيرة لبيان كيفيّة إنشاء علاقة من النوع واحد-إلى-مُتعدّد باستخدام الإضافة Flask-SQLAlchemy، إذ سننشئ علاقةً بين التدوينات والتعليقات، فمن الممكن أن يكون لكل تدوينة عددًا من التعليقات.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو flask_app.
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض، وفي هذا الصدد يمكنك الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.

الخطوة 1: تثبيت فلاسك والأداة Flask-SQLAlchemy

سنعمل في هذه الخطوة على تثبيت كل من فلاسك وكافّة الحزم اللازمة لعمل التطبيق.

لذا، وبعد التأكّد من تفعيل البيئة الافتراضية، سنستخدم أمر تثبيت الحزم pip لتثبيت كل من فلاسك وأداة Flask-SQLAlchemy على النحو التالي:

(env)user@localhost:$ pip install Flask Flask-SQLAlchemy

وبمجرّد انتهاء التثبيت بنجاح، سيظهر في السطر الأخير من الخرج ما يشبه التالي:

Successfully installed Flask-2.1.1 Flask-SQLAlchemy-2.5.1 Jinja2-3.1.1 MarkupSafe-2.1.1 SQLAlchemy-1.4.35 Werkzeug-2.1.1 click-8.1.2 greenlet-1.1.2 itsdangerous-2.1.2

ومع نهاية هذه الخطوة نكون قد ثبتنا ما يلزم من حزم بايثون، وأصبح من الممكن الانتقال إلى الخطوة التالية المُتمثّلة بإعداد قاعدة البيانات.

الخطوة 2: إعداد النماذج Models وقاعدة البيانات

سنعمل في هذه الخطوة على إعداد الاتصال مع قاعدة البيانات وإنشاء نماذج قاعدة البيانات SQLAlchemy، وهي أصناف بايثون تمثّل جداول قاعدة البيانات، إذ سننشئ نموذجًا للتدوينات وآخرًا للتعليقات، وسنعمل على تهيئة قاعدة البيانات وإنشاء جدول للتدوينات وآخرٍ للتعليقات وفقًا للنماذج التي سنصرّح عنها، ونهايةً سنضيف بعض التدوينات والتعليقات إلى قاعدة البيانات.

إعداد الاتصال بقاعدة البيانات

سننشئ بدايةً ملفًا باسم app.py ضمن المجلد flask.app، والذي سيحتوي على الشيفرات الخاصة بإعداد قاعدة البيانات ووجهات فلاسك اللازمة لعمل التطبيق:

(env)user@localhost:$ nano app.py

سيتصل هذا الملف بقاعدة بيانات من نوع SQLite باسم database.db، وسيحتوي على صنفين، الأوّل يدعى Post ويمثّل جدول التدوينات في قاعدة البيانات, والثاني يُدعى Comment ويمثّل جدول التعليقات، كما سيتضمّن هذا الملف وجهات فلاسك. الآن، سنضيف الاستدعاءات التالية باستخدام التعليمة import إلى بداية الملف app.py:

import os
from flask import Flask, render_template, request, redirect, url_for
from flask_sqlalchemy import SQLAlchemy

استوردنا في الشيفرة السابقة الوحدة os التي تمكنّنا من الوصول إلى واجهات نظام التشغيل المختلفة، والتي سنستخدمها في بناء مسار ملف قاعدة البيانات database.db.

كما استوردنا من حزمة فلاسك كافّة المُساعدات اللازمة للتطبيق، مثل الصنف Flask المُستخدم في إنشاء النسخة الفعلية من التطبيق، والدالة ()render_template لتصيير قوالب HTML، والكائن request المسؤول عن التعامل مع الطلبيات، والدالة ()url_for لبناء روابط الوجهات، والدالة ()redirect لإعادة توجيه المُستخدمين من صفحة لأُخرى.

وبعد الانتهاء من الاستدعاءات، سنعيّن مسارًا لملف قاعدة البيانات، ونستنسخ تطبيق فلاسك، كما سنضبط ونؤسس اتصالًا للتطبيق مع الإضافة SQLAlchemy، ثمّ سنضيف الشيفرة التالية إلى الملف app.py:

basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
           'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False


db = SQLAlchemy(app)

أنشأنا في الشيفرة السابقة مسارًا لملف قاعدة البيانات SQLite، إذ حددنا المجلد الحالي ليكون المجلد الرئيسي، كما استخدمنا الدالة ()os.path.abspath للحصول على المسار الكامل لمجلد الملف الحالي، إذ يتضمّن المتغير الخاص __file__ اسم مسار الملف الحالي app.py، لنخزّن المسار الكلي للمجلد الأساسي ضمن المتغير basedir، ثمّ أنشأنا نسخةً فعلية من تطبيق فلاسك باسم app، والتي سنستخدمها لضبط مفتاحي إعدادات خاصّين بالإضافة Flask-SQLAlchemy وهما:

SQLALCHEMY_DATABASE_URI: وهو معرّف الموارد الموحّد الخاص بقاعدة البيانات database URI المسؤول عن تحديد قاعدة البيانات المراد إنشاء اتصال معها، وفي هذه الحالة تكون صيغة هذا المعرّف بالشكل الآتي:

sqlite:///path/to/database.db

إذ نستخدم الدالة ()op.path.join لتحقيق الربط المدروس ما بين المجلد الأساسي الذي أنشاناه وخزنّا مساره في المتغير basedir، وبين اسم الملف database.db، الأمر الذي يسمح بالاتصال مع ملف قاعدة البيانات database.db الموجود في المجلد flask_app، إذ سيُنشأ هذا الملف فور تهيئة قاعدة البيانات.

SQLALCHEMY_TRACK_MODIFICATIONS: وهو إعداد لتمكين أو إلغاء تمكين ميزة تتبع تغيرات الكائنات، وقد عيّناه إلى القيمة false لإلغاء التتبع وبالتالي تحقيق استخدام أقل لموارد الذاكرة.

ملاحظة: من الممكن استخدام أي محرّك قواعد بيانات آخر مثل، PostgreSQL، أو MySQL، ويجب في هذه الحالة استخدام معرّف الموارد الموحد URI المناسب. ففي حال استخدام PostgreSQL سيتبع الصيغة:

postgresql://username:password@host:port/database_name

أمّا في حال استخدام MySQL:

mysql://username:password@host:port/database_name

وبعد الانتهاء من ضبط إعدادات الأداة SQLAIchemy من خلال تعيين معرّف الموارد الموحّد لقاعدة البيانات وإلغاء تمكين ميزة تتبّع التغييرات، سننشئ كائن قاعدة بيانات باستخدام الصنف SQLAIchemy، ممررين إليه نسخة التطبيق بغية ربط تطبيق فلاسك مع الأداة SQLAIchemy، ونخزّن كائن قاعدة البيانات هذا ضمن متغير باسم db لنستخدمه في التخاطب مع قاعدة البيانات.

التصريح عن الجداول

الآن وبعد تأسيس الاتصال مع قاعدة البيانات وإنشاء كائن قاعدة البيانات، سنستخدم هذا الكائن لإنشاء جدول للتدوينات وآخر للتعليقات، حيث تُمثّل الجداول بنماذج models، والنموذج هو صنف بايثون يرث من صنف رئيسي توفرّه الأداة Flask-SQLAlchemy من خلال نسخة قاعدة البيانات db التي أنشأناها مُسبقًا. لذا، وبغية تعريف جدولي التدوينات والتعليقات مثل نماذج، سنضيف الصنفين التاليين إلى الملف app.py على النحو التالي:

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100))
    content = db.Column(db.Text)
    comments = db.relationship('Comment', backref='post')

    def __repr__(self):
        return f''


class Comment(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    content = db.Column(db.Text)
    post_id = db.Column(db.Integer, db.ForeignKey('post.id'))

    def __repr__(self):
        return f''

أنشأنا في الشيفرة السابقة كل من النموذج Post والنموذج Comment مُستخدمين الصنف db.Column لتعريف أعمدة الجداول، إذ يمثّل الوسيط الأوّل نوع العمود، أمّا باقي الوسطاء فتمثّل إعدادات العمود.

وقد عرفنا الأعمدة التالية للنموذج Post:

id: وهو معرّف التدوينة، ويحتوي على بياناتٍ من نوع رقم صحيح وذلك باستخدام db.Integer و primary_key=True التي تعرّفه مفتاحًا أساسيًا، وتُخصّص قيمةٌ فريدة في قاعدة البيانات من أجل كل سجل (والسجل هو التدوينة في حالتنا).
title: عنوان التدوينة، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100.
content: محتوى التدوينة، وتشير db.Text إلى أنّ هذا العمود يضم نصوصًا طويلة.

وتُعرِّف سمة الصنف المسماة comments علاقةً من النوع واحد-إلى-متعدد ما بين النموذج Post والنموذج Comment، إذ استخدمنا التابع ()db.relationship ممررين إليه اسم نموذج التعليقات (المُسمّى Comment في حالتنا)، كما استخدمنا المعامل backref لإضافة مرجعٍ للعودة back reference، والذي يتمثّل بأحد أعمدة النموذج Comment، بحيث يمكننا الوصول إلى المنشور الذي يتبع له تعليق معيّن باستخدام السمة post. على سبيل المثال، إذا كان لدينا كائن تعليق مُخزّن ضمن متغير باسم comment، فمن الممكن الوصول إلى المنشور الذي وُضع هذا التعليق عليه باستخدام التعليمة comment.post، وسنبين فيما بعد مثال يوضح هذه الفكرة.

تمكننا الدالة الخاصة __repr__ من تمثيل كل كائن بصيغة سلسلة نصية، الأمر الذي يساعد في التعرّف على هذا الكائن لأغراض التنقيح، إذ استخدمنا في حالتنا عنوان التدوينة لهذا الغرض.

أمّا النموذج Comment فيمثّل جدول التعليقات، وقد عرفنا الأعمدة التالية له:

id: وهو معرّف التعليق، ويحتوي على بياناتٍ من نوع رقم صحيح وذلك باستخدام db.Integer و primary_key=True التي تعرّفه مفتاحًا أساسيًا، وتُخصّص قيمةٌ فريدة في قاعدة البيانات من أجل كل سجل (والسجل هو التعليق في هذه الحالة).
content: محتوى التعليق، وتشير db.Text إلى أنّ هذا العمود يضم نصوصًا طويلة.
post_id: وهو عدد صحيح يمثّل مفتاحًا خارجيًا foreign مُنشأ باستخدام الصنف ()db.ForeignKey؛ وهو مفتاح يربط جدولًا بآخر من خلال مفتاحه الأساسي، وفي حالتنا سيربط التعليق بالتدوينة التي يتبع لها باستخدام المفتاح الأساسي للتدوينة المتمثّل بمعرّفها، وبذلك يكون جدول التدوينات في هذه الحالة هو الجدول الأب، ما يعني أنّ كل تدوينة سترتبط بعدّة تعليقات، إذ يمثّل جدول التعليقات الجدول الابن، ويرتبط كل تعليق بتدوينة من الجدول الأب باستخدام معرّفها، وبالتالي سيكون لكل تعليق قيمة في العمود post_id والتي سنستخدمها في الوصول إلى التدوينة التي أُضيف التعليق عليها.

تُظهر الدالة الخاصة __repr__ في نموذج التعليقات أوّل 20 محرفًا من محتوى التعليق ما يمنح كائن التعليق تمثيلًا محرفيًا قصيرًا.

وبذلك سيبدو الملف app.py حاليًا بالشّكل التالي:

import os
from flask import Flask, render_template, request, redirect, url_for
from flask_sqlalchemy import SQLAlchemy

basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
           'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False


db = SQLAlchemy(app)


class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100))
    content = db.Column(db.Text)
    comments = db.relationship('Comment', backref='post')

    def __repr__(self):
        return f''


class Comment(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    content = db.Column(db.Text)
    post_id = db.Column(db.Integer, db.ForeignKey('post.id'))

    def __repr__(self):
        return f''

نحفظ الملف ونغلقه.

إنشاء قاعدة بيانات

الآن، وبعد الانتهاء من إعداد كل من الاتصال مع قاعدة البيانات ونماذج التدوينة والتعليق، سنستخدم صدفة فلاسك لإنشاء قاعدة البيانات وجداول التدوينات والتعليقات اعتمادًا على النماذج المُعرّفة مُسبقًا.

بعد التأكّد من كون البيئة الافتراضية مُفعّلة، نستخدم متغير البيئة FLASK_APP لتحديد الملف app.py على أنه تطبيق فلاسك:

(env)user@localhost:$ export FLASK_APP=app

ومن ثمّ نفتح صَدفة فلاسك باستخدام الأمر التالي وذلك أثناء وجودنا ضمن المجلد flask_app:

(env)user@localhost:$ flask shell

فتُفتح صَدفة بايثون تفاعلية خاصّة، تعمل على تشغيل الأوامر ضمن تطبيق فلاسك، وبذلك نضمن اتصال دوال Flask-SQLAlchemy التي سنستدعيها مع تطبيق فلاسك.

سنستورد الآن كائن قاعدة البيانات ونماذج التدوينات والتعليقات، ثمّ سنشغّل الدالة ()db.create_all بغية إنشاء الجداول الموافقة لتلك النماذج، كما يلي:

>>> from app import db, Post, Comment
>>> db.create_all()

نبقي الصدفة في حالة تشغيل، ونفتح نافذة طرفية جديدة وننتقل إلى المجلد flask_app، فنجد ملفًا جديدًا ضمنه باسم database.db.

ملاحظة:لا تنشئ الدالة ()db.create_all أو تحدّث جدولًا موجودًا أصلًا، فمثلًا لو عدّلنا أحد النماذج التي أنشأناها بإضافة عمود جديد إليه، ثمّ شغلنا الدالة ()db.create_all فلن يُطبّق التغيير الذي أجريته على النموذج على الجدول إذا كان الجدول موجود أصلًا في قاعدة البيانات، ويكون الحل لهذه المشكلة بحذف كافّة الجداول الموجودة في قاعدة البيانات باستخدام الدالة ()db.drop_all، ثمّ إعادة إنشائها باستخدام الدالة ()db.create_all، على النحو التالي:

>>> db.drop_all()
>>> db.create_all()

ستعمل هذه الشيفرة على تطبيق التعديلات على النموذج، كما ستحذف كافّة البيانات الموجودة في قاعدة البيانات، فلو أردت تحديث قاعدة البيانات مع الحفاظ على البيانات الموجودة فيها، لا بدّ من استخدام أداة ترحيل ملف تخطيط قاعدة البيانات schema migration، لنتمكن من تعديل الجداول مع الحفاظ على البيانات، ولاستخدام هذه الأداة من الممكن الاستعانة بالإضافة Flask-Migrate لتنفيذ ترحيل ملف تخطيط قاعدة البيانات باستخدام الأداة SQLAIchemy من خلال واجهة أسطر الأوامر في فلاسك.

وفي حال ظهور رسالة خطأ، يجب التأكّد من كون التصريح صحيح عن كل من النماذج ومعرّف الموارد الموحّد لقاعدة البيانات.

ملء الجدول

الآن وبعد إنشاء قاعدة البيانات وجداول التدوينات والتعليقات، سننشئ ملفًا ضمن المجلد flask_app لإضافة بعض التدوينات والتعليقات إلى قاعدة البيانات.

لذا، سننشئ ملفًا جديدًا باسم init_db.py:

(env)user@localhost:$ nano init_db.py

ونكتب ضمنه الشيفرات التالية، إذ سينشئ هذا الملف ثلاثة كائنات للتدوينات وأربعة كائنات للمنشورات، مُضيفًا كل منها إلى قاعدة البيانات:

from app import db, Post, Comment

post1 = Post(title='Post The First', content='Content for the first post')
post2 = Post(title='Post The Second', content='Content for the Second post')
post3 = Post(title='Post The Third', content='Content for the third post')

comment1 = Comment(content='Comment for the first post', post=post1)
comment2 = Comment(content='Comment for the second post', post=post2)
comment3 = Comment(content='Another comment for the second post', post_id=2)
comment4 = Comment(content='Another comment for the first post', post_id=1)


db.session.add_all([post1, post2, post3])
db.session.add_all([comment1, comment2, comment3, comment4])

db.session.commit()

نحفظ الملف ونغلقه.

استوردنا في الشيفرة السابقة كلًا من كائن قاعدة البيانات والنموذج Post والنموذج Comment من الملف app.py، كما أنشأنا بضعة كائنات تدوينات باستخدام النموذج Post، ممررين لذلك عنوان التدوينة إلى المعامل title ومحتواها إلى المعامل content، ثمّ أنشأنا بعد ذلك بضع كائنات تعليقات، ممررين محتوى التعليق؛ وهنا من الممكن استخدام أحدى طريقتين لربط التعليق بالتدوينة التي يتبع لها، الأولى بتمرير كائن التدوينة إلى المعامل post كما هو مبيّن في كلا الكائنين comment1 و comment2، أو من الممكن تمرير معرّف التدوينة إلى المعامل post_id كما هو مبيّن في الكائنين comment3 و comment4، وبالتالي من الممكن تمرير العدد الصحيح المُمثّل لمعرّف التدوينة وحده في حال عدم وجود كائن التدوينة في الشيفرة.

بعد الانتهاء من تعريف كل من كائني التدوينة والتعليق، استخدمنا التابع ()db.session.add_all لإضافة كافة كائنات التدوينات والتعليقات إلى جلسة قاعدة البيانات التي تدير العمليات، ثمّ استخدمنا التابع ()db.session.commit لتأكيد وتطبيق التغييرات على قاعدة البيانات. للمزيد حول جلسات قواعد البيانات في SQLAIchemy، ننصحك بقراءة الخطوة الثانية من المقال كيفية استخدام الإضافة Flask-SQLAlchemy للتخاطب مع قواعد البيانات في تطبيقات فلاسك.

الآن، سنشغل الملف init_db.py لتنفيذ الشيفرة وإضافة البيانات إلى قاعدة البيانات:

(env)user@localhost:$ python init_db.py

وللاطلاع على البيانات المُضافة إلى قاعدة البيانات، نفتح صَدفة فلاسك بغية الاستعلام عن كافّة التدوينات وعرض عناوينها ومحتويات التعليقات على كل منها، على النحو التالي:

(env)user@localhost:$ flask shell

ثمّ نشغّل الشيفرة التالية المسؤولة عن الاستعلام عن كافّة التدوينات وعرض عنوان كل تدوينة والتعليقات عليها أسفلها:

from app import Post

posts = Post.query.all()

for post in posts:
    print(f'## {post.title}')
    for comment in post.comments:
            print(f'> {comment.content}')
    print('----')

استوردنا في الشيفرة السابقة النموذج Post من الملف app.py، ثمّ استعلمنا عن كافّة التدوينات الموجودة في قاعدة البيانات باستخدام السمة query للتابع ()all، وخزّنا نتائج الاستعلام ضمن متغير باسم posts، ثمّ استخدمنا حلقة for تكرارية بغية المرور على كل عنصر من المتغير posts، لتُعرض العناوين، ثمّ استخدمنا بعد ذلك حلقة for تكرارية ثانية للمرور على كافّة تعليقات كل تدوينة، إذ استخدمنا التعليمة post.comments للوصول إلى التعليقات، ليُعرض بعدها محتوى التعليقات ويُطبَع فاصل بالشكل '----' بغية الفصل بين التدوينات في الخرج.

فنحصل على الخرج التالي:

## Post The First
> Comment for the first post
> Another comment for the first post
----
## Post The Second
> Comment for the second post
> Another comment for the second post
----
## Post The Third
----

فكما هو واضح، من الممكن الوصول إلى بيانات كل تدوينة وتعليقاتها باستخدام شيفرة قصيرة جدًا.

والآن نخرج من الصدفة:

>>> exit()

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

الخطوة 3: عرض جميع السجلات

سنعمل في هذه الخطوة على إنشاء وجهة وقالب لعرض كافّة التدوينات الموجودة في قاعدة البيانات ضمن الصفحة الرئيسية للتطبيق.

نفتح الملف app.py لنضيف إليه وجهةً للصفحة الرئيسية:

(env)user@localhost:$ nano app.py

ونضيف الوجهة التالية إلى نهاية الملف:

# ...

@app.route('/')
def index():
    posts = Post.query.all()
    return render_template('index.html', posts=posts)

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة المُزخرف ()app.route لإنشاء دالة عرض باسم ()index، التي نستعلم فيها ضمن قاعدة البيانات لجلب كافّة التدوينات كما فعلنا في الخطوة السابقة، لنخزّن نتائج هذا الاستعلام ضمن متغير باسم posts ممررين إياه إلى ملف قالب باسم index.html، الذي ستصيّره باستخدام الدالة المساعدة ()render_template.

الآن وقبل إنشاء ملف القالب index.html المسؤول عن عرض التدوينات الموجودة ضمن قاعدة البيانات في الصفحة الرئيسية للتطبيق، سننشئ بدايةً ملف قالب رئيسي ليتضمّن كافة شيفرات HTML الأساسية اللازمة لترثها لاحقًا القوالب الأُخرى، وهذا ما يجنبنا تكرار الشيفرات؛ ثمّ سننشئ ملف قالب الصفحة الرئيسية index.html المُصيّر أصلًا باستخدام الدالة ()index.

لذلك، سننشئ مجلدًا للقوالب باسم templates، وننشئ ضمنه ملف قالب باسم base.html، والذي سيمثّل القالب الأساسي لبقية القوالب، كما يلي:

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html

وسنكتب فيه الشيفرة التالية:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">Comments
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي سنحتاجها في القوالب الأُخرى.

ستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن ثلاثة روابط؛ إذ ينقل الأوّل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for؛ والثاني إلى صفحة التعليقات Comments، أمّا الأخير لصفحة المعلومات حول التطبيق About في حال قررت تضمينها في تطبيقك، مع ملاحظة أنّنا سنعدّل هذا الملف لاحقًا بعد إضافة صفحة لعرض التعليقات الأحدث بغية جعل الرابط إلى هذه الصفحة فعّالًا.

الآن، سننشئ ملف قالب باسم index.html وهو الاسم الذي حددناه في الملف app.py:

(env)user@localhost:$ nano templates/index.html

ونضيف ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <span class="title"><h1>{% block title %} Posts {% endblock %}h1>span>
    <div class="content">
        {% for post in posts %}
            <div class="post">
                <p><b>#{{ post.id }}b>p>
                <b>
                    <p class="title">
                        <a href="#">
                            {{ post.title }}
                        a>
                    p>
                b>
                <div class="content">
                    <p>{{ post.content }}p>
                div>
                <hr>
            div>
        {% endfor %}
    div>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب base.html باستخدام تعليمة extends، واستبدلنا محتوى كتلة المحتوى content مُستخدمين تنسيق العنوان من المستوى الأوّل

الذي يفي أيضًا بالغرض لعنوان الصفحة.

استخدمنا في السطر البرمجي {% for post in posts %} حلقة for من تعليمات محرّك القوالب جينجا jinja، والهدف من استخدام هذه الحلقة هو المرور على كل تدوينة ضمن المتغير posts المُمرّر من الدالة ()index إلى هذا القالب، حيث سنعرض معرّف التدوينة وعنوانها ومحتواها، إذ سيعمل لاحقًا عنوان التدوينة مثل رابط إلى صفحة مُستقلّة تعرض هذه التدوينة مع تعليقاتها.

الآن ومع وجودنا ضمن المجلد flask_app ومع كون البيئة الافتراضية مُفعّلة، سنُعلم فلاسك بالتطبيق المراد تشغيله (وهو في حالتنا الملف app.py) باستخدام متغير البيئة FLASK_APP، في حين يحدّد متغير البيئة FLASK_ENV وضع التشغيل وهنا قد اخترنا الوضع development ما يعني أنّ التطبيق سيعمل في وضع التطوير مع تشغيل مُنقّح الأخطاء. لمزيدٍ من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

والآن سنشغّل التطبيق باستخدام الأمر flask run:

(env)user@localhost:$ flask run

وبعد التأكد من تشغيل خادم التطوير، نذهب إلى الرابط التالي باستخدام المتصفح:

http://127.0.0.1:5000/

فتظهر لنا التدوينات المُضافة إلى قاعدة البيانات في صفحة مشابهة للصورة التالية:

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

الخطوة 4: عرض تدوينة مفردة مع التعليقات عليها

سننشئ في هذه الخطوة وجهة وقالب لعرض التفاصيل الخاصة بكل تدوينة في صفحة مُخصّصة لذلك، مع عرض كافّة تعليقات كل منها أدناها.

في نهاية هذه الخطوة سيعرض الرابط http://127.0.0.1:5000/1 صفحةً تعرض التدوينة الأولى مع تعليقاتها (لأن الرابط يحوي على المعرّف رقم 1)، بينما يعرض الرابط http://127.0.0.1:5000/ID المنشور ذو المعرّف ID الموافق له إن وُجد.

نبقي خادم التطوير قيد التشغيل، ونفتح نافذة طرفية جديدة.

نفتح الملف app.py لتعديله كما يلي:

(env)user@localhost:$ nano app.py

ونضيف الوجهة التالية إلى نهاية الملف:

# ...

@app.route('//')
def post(post_id):
    post = Post.query.get_or_404(post_id)
    return render_template('post.html', post=post)

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة الوجهة // إذ يمثّل المعامل :int محوّلًا لتحويل السلسلة النصية الافتراضية في الرابط إلى نوع عدد صحيح، ويمثل post_id متغير الرابط الذي سيُحدّد التدوينة المطلوب عرضها في الصفحة.

مررنا المعرّف من الرابط إلى دالة العرض ()post من خلال المعامل post_id، والتي نستعلم فيها عن جدول التدوينات لنجلب منه التدوينة من خلال معرّفها باستخدام التابع ()get_or_404، الأمر الذي يؤدي إلى حفظ بيانات التدوينة (في حال وجودها) ضمن المتغير post، وإلّا ستُعرض استجابة خطأ HTTP من النوع ‎404 Not Found في حال عدم وجود تدوينة موافقة للمعرّف المطلوب في قاعدة البيانات.

ومن ثمّ صيّرنا قالبًا باسم post.html ممرّرين إليه التدوينة المُستخرجة.

لذا، سنفتح ملف قالب جديد باسم post.html:

(env)user@localhost:$ nano templates/post.html

وسنكتب فيه الشيفرة التالية، والأمر مشابه للقالب index.html باستثناء أنّ هذا الملف سيعرض تدوينةً واحدةً كل مرة:

{% extends 'base.html' %}

{% block content %}
    <span class="title"><h1>{% block title %} {{ post.title }}  {% endblock %}h1>span>
    <div class="content">
            <div class="post">
                <p><b>#{{ post.id }}b>p>
                <b>
                    <p class="title">{{ post.title }}p>
                b>
                <div class="content">
                    <p>{{ post.content }}p>
                div>
                <hr>
                <h3>Commentsh3>
                {% for comment in post.comments %}
                    <div class="comment">
                        <p>#{{ comment.id }}p>
                        <p>{{ comment.content }}p>
                    div>
                {% endfor %}
            div>
    div>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في هذه الشيفرة على الوراثة من القالب base.html باستخدام تعليمة extends، وجعلنا عنوان التدوينة عنوانًا للصفحة، كما عرضنا كلًا من معرّف التدوينة ومحتواها، ومن ثمّ مررنا على كافّة التعليقات المتوفرّة على هذه التدوينة باستخدام سمة الكائن post.comments، لنعرض معرّف التعليق ومحتواه.

ننتقل باستخدام متصفح الويب إلى رابط التدوينة الثانية كما يلي:

http://127.0.0.1:5000/2/

فتظهر صفحة مشابهة لما يلي:

ثمّ سنحرّر ملف القالب index.html لنربط عنوان كل تدوينة مع الصفحة الخاصة بها:

(env)user@localhost:$ nano templates/index.html

نعدّل قيمة سمة الرابط href لعنوان التدوينة ضمن حلقة for التكرارية:

...

{% for post in posts %}
    <div class="post">
        <p><b>#{{ post.id }}b>p>
        <b>
            <p class="title">
                <a href="{{ url_for('post', post_id=post.id)}}">
                {{ post.title }}
                a>
            p>
        b>
        <div class="content">
            <p>{{ post.content }}p>
        div>
        <hr>
    div>
{% endfor %}

نحفظ الملف ونغلقه.

ننتقل إلى الصفحة الرئيسية للتطبيق ونحدثّها:

http://127.0.0.1:5000/

وبالنقر على عنوان كل تدوينة في الصفحة الرئيسية للتطبيق نجد أنّه مرتبط بالصفحة الموافقة.

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

الخطوة 5: إضافة تعليقات جديدة

سنعمل في هذه الخطوة على تحرير الوجهة // ودالة العرض ()post الخاصة بها والمسؤولة عن عرض التدوينات المنفردة، إذ سنضيف نموذج ويب أسفل كل تدوينة من شأنه السماح للمستخدمين بإضافة تعليقات جديدة على التدوينة، ومن ثمّ سنجهّز الآليات اللازمة للتعامل مع إرسال التعليق وإضافته إلى قاعدة البيانات.

لذا، سنفتح بدايةً ملف القالب post.html لإضافة نموذج ويب مكوّن من حقل نصي لمحتوى التعليق بالإضافة إلى زر أوامر Add Comment لتأكيد وإرسال التعليق:

(env)user@localhost:$ nano templates/post.html

نعدّل الملف بإضافة نموذج بعد العنوان من المستوى الثالث Comments وقبل حلقة for التكرارية، كما يلي:

<hr>
<h3>Commentsh3>
<form method="post">
    <p>
        <textarea name="content"
                    placeholder="Comment"
                    cols="60"
                    rows="5">textarea>
    p>

    <p>
        <button type="submit">Add commentbutton>
    p>
form>
{% for comment in post.comments %}

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة الوسم

وضبطنا فيه السمة method التي تُحدّد نوع طلبية HTTP لتكون من النوع POST، ما يعني أنّ نموذج الويب هذا سيرسل طلبًا من النوع POST.

وبذلك أصبح لدينا حقلًا نصيًا لمحتوى التعليق بالإضافة إلى زر تأكيد وإرسال له.

الآن -وأثناء عمل خادم التطوير- نستخدم المتصفح للانتقال إلى تدوينة ما (ولتكن التدوينة الثانية مثلًا):

http://127.0.0.1:5000/2/

فستظهر صفحة مشابهة للصورة التالية:

يرسل نموذج الإدخال هذا طلبًا من النوع POST إلى دالة العرض ()post، ولكن حتى هذه اللحظة لا توجد شيفرة مسؤولة عن معالجة هذا الطلب، وبالتالي لن يحدث شيء في حال ملء النموذج الآن وإرساله بمعنى أنّ النموذج لا يعمل حتى اللحظة.

الآن، سنضيف الشيفرة اللازمة لدالة العرض ()post لمعالجة النماذج المُرسلة وإضافة التعليق الجديد إلى قاعدة البيانات. لذا، سنفتح الملف app.py بهدف تعديله ليتعامل مع الطلبات من النوع post المُرسلة من قبل المستخدم:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة // ودالة العرض ()post الخاصة بها لتصبح كما يلي:

@app.route('//', methods=('GET', 'POST'))
def post(post_id):
    post = Post.query.get_or_404(post_id)
    if request.method == 'POST':
        comment = Comment(content=request.form['content'], post=post)
        db.session.add(comment)
        db.session.commit()
        return redirect(url_for('post', post_id=post.id))

    return render_template('post.html', post=post)

نحفظ الملف ونغلقه.

سمحنا في الشيفرة السابقة بكلا نوعي طلبيات HTTP وهما GET و POST من خلال المعامل method؛ إذ تتخصّص الطلبيات من النوع GET بجلب البيانات من الخادم، أمّا الطلبيات من النوع POST فهي مُتخصّصة بإرسال البيانات إلى وجهة مُحدّدة، مع ملاحظة أنّ الطلبيات من النوع GET هي الوحيدة المسموحة افتراضيًا.

تُعالج الطلبية من النوع POST المُرسلة من قبل المُستخدم عبر النموذج ضمن العبارة الشرطية 'if request.method == 'POST، إذ ننشئ كائن تعليقات باستخدام النموذج Comment، ممررين إليه محتوى التعليق المُرسل والمُستخرج من الكائن request.form، ثمّ نحدّد التدوينة التي يتبع لها التعليق باستخدام المعامل post ممررين إليه الكائن post المُستخرج اعتمادًا على مُعرّف التدوينة الموافقة باستخدام التابع ()get_or_404.

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

الآن، نحدّث صفحة التدوينة ونضيف تعليقًا ونرسله، فسيظهر هذا التعليق الجديد أسفل التدوينة.

أصبح لدينا مع نهاية هذه الخطوة نموذج ويب يمكّن المُستخدمين من إضافة تعليقات على التدوينة، وللمزيد حول نماذج الويب ننصحك بقراءة المقال كيفية استخدام نماذج الويب في تطبيقات فلاسك، وللمزيد من المعلومات المتقدمة ولتتعرّف على كيفية إدارة نماذج الويب بأمان ننصحك بقراءة المقال استخدام والتحقق من نماذج الويب ذات واجهة المستخدم التفاعلية في فلاسك باستخدام الإضافة Flask-WTF.

سنعمل في الخطوة التالية على إضافة صفحة لعرض كافّة التعليقات الموجودة ضمن قاعدة البيانات مع التدوينة التي يتبع لها كل تعليق.

الخطوة 6: عرض جميع التعليقات

سنعمل في هذه الخطوة على إضافة صفحة للتعليقات Comments لعرض جميع التعليقات الموجودة ضمن قاعدة البيانات وترتيبها بحيث تظهر التعليقات الأحدث أولًا، حيث سيظهر مع كل تعليق عنوان ورابط التدوينة المرتبط بها.

نفتح الملف app.py:

(env)user@localhost:$ nano app.py

ثم نضيف الوجهة التالية إلى نهاية هذا الملف، والتي تجلب جميع التعليقات من قاعدة البيانات، وترتّبها بحيث يكون الأحدث أولًا، لتمرّرها إلى ملف قالب باسم comments.html، الذي سننشئه لاحقًا:

# ...

@app.route('/comments/')
def comments():
    comments = Comment.query.order_by(Comment.id.desc()).all()
    return render_template('comments.html', comments=comments)

نحفظ الملف ونغلقه.

طبقنا في الشيفرة السابقة التابع ()order_by على السمة query بغية جلب كافّة التعليقات ولكن وفق ترتيب معيّن، وقد استخدمنا في حالتنا التابع ()desc على العمود Comment.id بهدف جلب التعليمات وفق ترتيب تنازلي، بحيث يكون التعليق الأحدث هو الأوّل، ومن ثمّ استخدمنا التابع ()all للحصول على النتيجة وتخزينها ضمن متغير باسم comments.

ثمّ صيّرنا ملف قالب باسم comments.html، ممررين إليه الكائن comments المُتضمّن كافّة التعليقات مُرتبّة بحيث يكون التعليق الأحدث أولًا.

لذا، سنفتح الآن ملف القالب comments.html:

(env)user@localhost:$ nano templates/comments.html

ونكتب ضمنه الشيفرة التالية، والتي ستعمل على عرض التعليقات وربط كل منها بالتدوينة التي يتبع لها:

{% extends 'base.html' %}

{% block content %}
    <span class="title"><h1>{% block title %} Latest Comments {% endblock %}h1>span>
    <div class="content">
                {% for comment in comments %}
                    <div class="comment">
                        <i>
                            (#{{ comment.id }})
                            <p>{{ comment.content }}p>
                        i>
                        <p class="title">
                        On <a href="{{ url_for('post',
                                                post_id=comment.post.id) }}">
                                {{ comment.post.title }}
                              a>
                        p>
                    div>
                {% endfor %}
            div>
    div>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب الأساسي base.html باستخدام تعليمة extends، وعيّنا عنوانًا ومررنا على كافّة التعليقات باستخدام حلقة for تكرارية، لنعرض بعدها معرّف التعليق ومحتواه ورابط التدوينة التي يتبع لها، إذ تمكنا من الوصول إلى بيانات التدوينة باستخدام سمة الكائن comment.post.

الآن وباستخدام المتصفّح ننتقل إلى صفحة التعليقات باستخدام الرابط التالي:

http://127.0.0.1:5000/comments/

فتظهر صفحة مشابهة للصورة التالية:

والآن سنعمل على تمكين رابط صفحة التعليقات Comments في شريط التصفّح، لذا نفتح ملف القالب base.html لتحريره:

(env)user@localhost:$ nano templates/base.html

ونعدل الشيفرة الخاصّة بشريط التنقل لتبدو كما يلي:


         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('comments') }}">Comments
         href="#">About

نحفظ الملف ونغلقه.

الآن وبتحديث صفحة التعليقات نجد أنّ الرابط Comments في شريط التصفّح بات يعمل.

ومع نهاية هذه الخطوة أصبح لدينا صفحة لعرض كافّة التعليقات الموجودة ضمن قاعدة البيانات، أمّا في الخطوة التالية فسنعمل على إضافة زر أسفل كل تعليق في صفحة التدوينة من شأنه السماح للمُستخدمين بحذف التعليقات.

الخطوة 7: حذف تعليقات

سنعمل في هذه الخطوة على إضافة زر حذف التعليق Delete Comment أسفل كل تعليق في صفحة المنشور لنمكّن المستخدمين من حذف التعليقات غير المرغوبة.

بدايةً، سنضيف وجهةً جديدةً للحذف، وهي ‎/comments/ID/delete تتعامل مع الطلبات من النوع POST، إذ ستستقبل دالة الحذف رقم معرّف التعليق ID المراد حذفه، لتجلبه من قاعدة البيانات وتحذفه، ليُعاد بعدها التوجيه إلى صفحة التدوينة التي حّذف منها التعليق.

الآن، افتح الملف app.py:

(env)user@localhost:$ nano app.py

أضِف الوجهة التالية إلى نهاية الملف:

# ...

@app.post('/comments//delete')
def delete_comment(comment_id):
    comment = Comment.query.get_or_404(comment_id)
    post_id = comment.post.id
    db.session.delete(comment)
    db.session.commit()
    return redirect(url_for('post', post_id=post_id))

نحفظ الملف ونغلقه.

استخدمنا المزخرف app.post المُقدّم في الإصدار 2.0.0 من فلاسك بدلًا من استخدام المزخرف app.route المعتاد، والذي أضاف اختصارات للعديد من توابع HTTP الشائعة، فعلى سبيل المثال الأمر:

@app.post("/login")

هو اختصارٌ للأمر:

@app.route("/login", methods=["POST"])

ما يعني أن الدالة العاملة في فلاسك هذه تتعامل فقط مع طلبيات من النوع POST، وبزيارة الوجهة comments/ID/delete/ في المتصفّح سيظهر الخطأ ‎405 Method Not Allowed لأن المتصفحات تستخدم طريقة GET افتراضيًا للطلبات، لذا بغية حذف تعليق ما، سنضيف زر أوامر عندما يضغط المستخدم عليه، تُرسَل إلى الوجهة طلبية من النوع POST.

تستقبل دالة العرض ()delete_comment في الشيفرة السابقة معرّف التعليق المراد حذفه من خلال متغير الرابط comment_id، إذ استخدمنا التابع ()get_or_404 لجلب التعليق وحفظه في متغير باسم comment، أو الاستجابة بخطأ من النوع ‎404 Not Found في حال عدم وجود تعليق موافق، كما خزّنا معرّف التدوينة التي يتبع لها التعليق المحذوف في المتغير post_id والذي سنستخدمه في إعادة التوجيه إلى صفحة هذه التدوينة بعد حذف التعليق.

استخدمنا التابع ()delete في الجلسة المفتوحة مع قاعدة البيانات في السطر البرمجي (db.session.delete(comment ممررين إليه كائن التدوينة، وهذا ما يجعل الجلسة بالنتيجة تحذف التعليق الموافق بمجرّد تأكيد الإجراءات، إذ ما من حاجة لإجراء أي تعديلات إضافية كون الإجراءات تُأكَّد مباشرةً باستخدام الأمر ()db.session.commit، ونهايةً أعدنا توجيه المستخدم إلى صفحة التدوينة التي يتبع لها التعليق المحذوف.

سنعدّل القالب "post.html" بإضافة زر لحذف التعليق Delete Comment أسفل كل تعليق:

(env)user@localhost:$ nano templates/post.html

سنعدّل حلقة for التكرارية بإضافة وسم نموذج مباشرةً أسفل محتوى التعليق:

{% for comment in post.comments %}
        <div class="comment">
            <p>#{{ comment.id }}p>
            <p>{{ comment.content }}p>
            <form method="POST"
                action="{{ url_for('delete_comment',
                                    comment_id=comment.id) }}">
                <input type="submit" value="Delete Comment"
                    onclick="return confirm('Are you sure you want to delete this entry?')">
            form>
        div>
    {% endfor %}

نحفظ الملف ونغلقه.

أنشأنا في الملف السابق نموذج ويب يُرسل طلبًا من النوع POST إلى دالة العرض ()delete_comment ممررين القيمة comment.id وسيطًا للمعامل comment_id لتحديد التعليق المراد حذفه، كما استخدمنا التابع confirm()‎ المتوفّر في متصفحات الويب لعرض رسالة تأكيد قبل إرسال الطلب.

الآن وبالانتقال إلى صفحة إحدى التدوينات (التدوينة الثانية مثلًا):

http://127.0.0.1:5000/2/

سيظهر زر أوامر لحذف التعليق Delete Comment أسفل كل تعليق، وبالنقر عليه ستظهر رسالة لتأكيد عملية الحذف، ومن ثمّ نجد أنّ التعليق قد حُذِف فعلًا.

وبذلك أصبحت الآلية اللازمة لحذف التعليقات من قاعدة البيانات متوفّرة في التطبيق.

الخاتمة

عملنا في هذا المقال على بناء تطبيق مدونة بغية بيان كيفيّة إدارة علاقات قواعد البيانات من نوع واحد-إلى-مُتعدّد باستخدام الإضافة Flask-SQLAlchemy، إذ تعرفنا على كيفيّة ربط الجدول الأب بالجدول الابن، وكيفية إنشاء اقتران ما بين كائن ابن مع أبيه وإضافته إلى قاعدة البيانات، وكيفية الوصول إلى بيانات الابن انطلاقًا من سجلات الأب وبالعكس.

ترجمة -وبتصرف- للمقال How to Use One-to-Many Database Relationships with Flask-SQLAlchemy لصاحبه Abdelhadi Dyouri.

استخدام إضافة Flask-SQLAlchemy للتخاطب مع قواعد بيانات تطبيقات فلاسك

Sun, 05 Feb 2023 16:00:00 +0000

نحتاج عادةً إلى قاعدة بيانات في تطبيقات الويب، وهي مجموعةٌ مُنطمّةٌ من البيانات نستخدمها لتخزين وتنظيم البيانات الدائمة، موفّرةً لنا إمكانية استرجاعها ومعالجتها بفعالية، إذ سنحتاج مثلًا في تطبيق ما للتواصل الاجتماعي إلى قاعدة بيانات لتخزين بيانات المستخدم (من معلومات شخصية ومنشورات وتعليقات ومتابعين) لنتمكّن من معالجتها بفعالية، إذ توفّر قاعدة البيانات إمكانية إضافة بيانات جديدة إليها، أو استرجاع بيانات مُخزّنة أصلًا، أو التعديل عليها، أو حذفها بكل مرونة وذلك اعتمادًا على المتطلبات والشروط والظروف المُختلفة، ففي تطبيق ويب ما قد تكون هذه المتطلبات مثلًا هي حالة إضافة المُستخدم لمنشور جديد، أو حذف منشور سابق، أو حذف حسابه مع كافّة منشوراته أو مع الإبقاء عليها، بمعنى أنّ طريقة معالجة البيانات تعتمد أولًا وأخيرًا على الميزات التي يتيحها التطبيق، فقد لا ترغب مثلًا بالسماح لمُستخدمي تطبيقك بإضافة منشورات غير معنونة.

أمّا SQLAlchemy فهي أداة في محرك قواعد البيانات SQL تؤمن وصولًا فعالًا وعالي الأداء إلى قواعد البيانات العلاقية، كما توفّر طرقًا للتخاطب مع العديد من محركات قواعد البيانات، مثل SQLite و MySQL و PostgreSQ، مانحةً إمكانية الوصول إلى آليات SQL الخاصة بقواعد البيانات، كما توفّر مُخطِّط الكائنات العلاقية Object Relational Mapper -أو اختصارًا ORM- الذي يتيح إمكانية إنشاء الاستعلامات والتعامل مع البيانات باستخدام توابع وكائنات بسيطة في بايثون.

تُعدّ Flask-SQLAlchemy بمثابة إضافة لفلاسك، لتسهيل استخدام SQLAlchemy ضمن فلاسك، وتؤمن الأدوات والوسائل المناسبة للتعامل مع قاعدة البيانات في تطبيقات فلاسك من خلال SQLAlchemy.

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

سنستخدم الإضافة SQLAlchemy مع محرّك قواعد البيانات SQLite رغم أنه من الممكن استخدامها مع محركات قواعد بيانات أخرى، مثل PostgreSQL و MySQL، إلّا أنّ SQLite تعمل بكفاءة مع بايثون، لأن المكتبة القياسية لبايثون توفر الوحدة sqlite3 المُستخدمة من قبل SQLAlchemy في الخلفية للتعامل مع قاعدة بيانات SQLite دون الحاجة إلى تثبيت أي شيء إضافي، إذ تُثبّت SQlite افتراضيًا على أنظمة لينكس Linux، كما تُثبّت على أنها جزءٌ من حزمة بايثون في أنظمة تشغيل ويندوز Windows.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بُدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو flask_app.
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض، ويمكنك في هذا الصدد الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.

الخطوة 1 – تثبيت فلاسك والإضافة Flask-SQLAlchemy

سنعمل في هذه الخطوة على تثبيت كل من فلاسك وكافّة الحزم اللازمة لعمل التطبيق. لذلك، وبعد التأكّد من كون البيئة الافتراضية مُفعّلة، سنستخدم أمر تثبيت الحزم pip لتثبيت كل من فلاسك والإضافة Flask-SQLAlchemy على النحو التالي:

(env)user@localhost:$ pip install Flask Flask-SQLAlchemy

وبمجرّد انتهاء التثبيت بنجاح، سيظهر في السطر الأخير من الخرج ما يشبه التالي:

Successfully installed Flask-2.0.3 Flask-SQLAlchemy-2.5.1 Jinja2-3.0.3 MarkupSafe-2.1.0 SQLAlchemy-1.4.31 Werkzeug-2.0.3 click-8.0.4 greenlet-1.1.2 itsdangerous-2.1.0

الخطوة 2 – إعداد النموذج وقاعدة البيانات

سنعمل في هذه الخطوة على إعداد الاتصال مع قاعدة البيانات وإنشاء نموذج قاعدة البيانات SQLAlchemy، وهو صنف بايثون يمثّل الجدول الذي سيخزّن البيانات، إذ سنعمل على تهيئة قاعدة البيانات وإنشاء جدول للطلاب وفقًا للنموذج الذي سنصرّح عنه، ونهايةً سنضيف بعض الطلاب إلى جدول الطلاب هذا.

إعداد الاتصال بقاعدة البيانات

سننشئ بدايةً ملف باسم app.py ضمن المجلد flask.app والذي سيحتوي على الشيفرات الخاصة بإعداد قاعدة البيانات ووجهات فلاسك اللازمة لعمل التطبيق:

(env)user@localhost:$ nano app.py

سيتصل هذا الملف بقاعدة بيانات من نوع SQLite باسم database.db، كما يحتوي على صنف يدعى Student يمثّل جدول الطلاب في قاعدة البيانات المُستخدم لتخزين معلوماتهم، إضافةً إلى وجهات فلاسك. سنضيف الاستدعاءات التالية باستخدام التعليمة import إلى بداية الملف app.py:

import os
from flask import Flask, render_template, request, url_for, redirect
from flask_sqlalchemy import SQLAlchemy

from sqlalchemy.sql import func

استوردنا في الشيفرة السابقة الوحدة os التي تمكنّنا من الوصول إلى واجهات نظام التشغيل المختلفة، والتي سنستخدمها في بناء مسار ملف قاعدة البيانات database.db، كما استوردنا من حزمة فلاسك كافّة المُساعدات اللازمة للتطبيق، مثل الصنف فلاسك المُستخدم في إنشاء النسخة الفعلية من التطبيق، والدالة ()render_template لتصيير قوالب HTML، والكائن request المسؤول عن التعامل مع الطلبيات، والدالة ()url_for لبناء روابط الوجهات، والدالة ()redirect لإعادة توجيه المُستخدمين من صفحة لأُخرى.

بعد ذلك، استوردنا الصنف SQLAlchemy من الإضافة Flask-SQLAlchemy، والذي يسمح لنا بالوصول إلى جميع الدوال والأصناف الخاصة بالإضافة SQLAlchemy، إضافةً إلى المُساعدات والآليات التي تدعم عمل فلاسك مع هذه الإضافة، والتي سنستخدمها لإنشاء كائن قاعدة بيانات يتصل مع تطبيق فلاسك سامحًا لنا بإنشاء وتعديل الجداول باستخدام أصناف وكائنات ودوال بايثون دون الحاجة لاستخدام لغة SQL.

كما استوردنا المساعد func من الوحدة sqlalchemy.sql للوصول إلى دوال SQL، والتي سنستخدمها في نظام إدارة الطلاب لضبط الوقت والتاريخ افتراضيًا لدى إنشاء سجل طالب جديد.

وبعد الانتهاء من الاستدعاءات، سنعيّن مسار ملف قاعدة البيانات، ونستنسخ تطبيق فلاسك، كما سنضبط ونؤسس اتصالًا للتطبيق مع الإضافة SQLAlchemy، ومن ثمّ سنضيف الشيفرة التالية:

basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
        'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

ثمّ أنشأنا نسخةً فعليةً من تطبيق فلاسك باسم app لنستخدمها في ضبط مفتاحي الضبط الخاصين بالإضافة Flask-SQLAlchemy، وهما:

SQLALCHEMY_DATABASE_URI: وهو معرّف الموارد الموحّد الخاص بقاعدة البيانات database URI المسؤول عن تحديد قاعدة البيانات المراد إنشاء اتصال معها، وفي هذه الحالة تكون صيغة هذا المعرّف بالشكل sqlite:///path/to/database.db، إذ نستخدم الدالة ()op.path.join لتحقيق الربط المدروس بين المجلد الأساسي الذي أنشاناه وخزنّا مساره في المتغير basedir، وبين اسم الملف database.db، الأمر الذي يسمح بالاتصال مع ملف قاعدة البيانات database.db الموجود في المجلد flask.app، إذ سيُنشأ هذا الملف فور تهيئة قاعدة البيانات.
SQLALCHEMY_TRACK_MODIFICATIONS: وهو إعداد لتمكين أو إلغاء تمكين ميزة تتبع تغيرات الكائنات، وقد عيّناه إلى القيمة false لإلغاء التتبع وبالتالي تحقيق استخدام أقل لموارد الذاكرة.

ملاحظة: من الممكن استخدام أي محرّك قواعد بيانات آخر، مثل PostgreSQL، أو MySQL، وفي هذه الحالة يجب استخدام معرّف الموارد الموحد URI المناسب؛ ففي حال استخدام PostgreSQL، سيتّبع الصيغة:

postgresql://username:password@host:port/database_name

أمّا في حال استخدام MySQL:

mysql://username:password@host:port/database_name

وبعد الانتهاء من ضبط الإضافة SQLAIchemy من خلال تعيين معرّف الموارد الموحّد لقاعدة البيانات وإلغاء تمكين ميزة تتبّع التغييرات، سننشئ كائن قاعدة بيانات باستخدام صنف الإضافة SQLAIchemy، ممررين إليه نسخة التطبيق بغية ربط تطبيق فلاسك مع الإضافة SQLAIchemy، وسنخزّن كائن قاعدة البيانات هذا ضمن متغير باسم db، والذي سنستخدمه في التخاطب مع قاعدة البيانات.

التصريح عن الجداول

بعد تأسيس الاتصال مع قاعدة البيانات وإنشاء كائن قاعدة البيانات، سنستخدم هذا الكائن لإنشاء جدول للطلاب في قاعدة البيانات، والمُمثّل بنموذج model، وهو صنف بايثون يرث من صنف رئيسي توفرّه الإضافة Flask-SQLAlchemy من خلال نسخة قاعدة البيانات db التي أنشأناها مُسبقًا، لذا وبغية تعريف جدول الطلاب مثل نموذج، سنضيف الصنف التالي إلى الملف app.py على النحو التالي:

# ...

class Student(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    firstname = db.Column(db.String(100), nullable=False)
    lastname = db.Column(db.String(100), nullable=False)
    email = db.Column(db.String(80), unique=True, nullable=False)
    age = db.Column(db.Integer)
    created_at = db.Column(db.DateTime(timezone=True),
                           server_default=func.now())
    bio = db.Column(db.Text)

    def __repr__(self):
        return f''

أنشأنا في الشيفرة السابقة النموذج Student الممثّل لجدول الطلاب والذي يرث من الصنف db.Model، كما استخدمنا الصنف db.Column لتعريف أعمدة الجدول، إذ يمثّل الوسيط الأوّل نوع العمود، أمّا باقي الوسطاء فتمثّل إعدادات العمود.

وقد عرفنا الأعمدة التالية للنموذج Student:

id: وهو معرّف الطالب، ويحتوي على بياناتٍ من نوع رقم صحيح وذلك باستخدام db.Integer و primary_key=True التي تعرّفه مفتاحًا أساسيًا، الذي يخصّص قيمةً فريدةً في قاعدة البيانات من أجل كل سجل (والسجل هو الطالب في حالتنا).
firstname: الاسم الأول للطالب، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100، وتشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
lastname: الاسم الأخير للطالب، وهو سلسلة نصية بعدد محارف أعظمي يساوي 100، وتشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
email: عنوان البريد الإلكتروني للطالب، وهو سلسلة نصية بعدد محارف أعظمي يساوي 80، وتشير التعليمة unique=True إلى أنّ البريد الإلكتروني يجب أن يكون فريدًا لكل طالب، كما تشير التعليمة nullable=False إلى أن هذا العمود لا يجب أن يحتوي على قيمٍ فارغة.
age: عمر الطالب.
created_at: يحتوي على تاريخ ووقت إنشاء سجل الطالب في قاعدة البيانات، إذ استخدمنا الوحدة db.DateTime لتعريفه مثل كائن وقت وتاريخ datetime في بايثون. تمكّن التعليمة timezone=True خاصية دعم المنطقة الزمنية، وتعيّن الوحدة server_default القيمة الزمنية الافتراضية في قاعدة البيانات لحظة إنشاء الجدول وبذلك تتعامل قاعدة البيانات مع القيم الافتراضية عوضًا عن النموذج، الذي نمرّر إليه الدالة ()func.now التي تستدعي دالة ()now المسؤولة عن تحديد الوقت والتاريخ بلغة SQL، لتُصيّر في SQLite بالشّكل CURRENT_TIMESTAMP عند إنشاء جدول الطلاب.
bio: السيرة الذاتية للطالب، إذ تشير ()db.Text إلى أنّ هذا العمود يضم نصوصًا طويلة.

تمكننا الدالة الخاصة __repr__ من تمثيل كل كائن بصيغة سلسلة نصية، الأمر الذي يساعد في التعرّف على هذا الكائن لأغراض التنقيح، واستخدمنا في حالتنا الاسم الأوّل للطالب لهذا الغرض.

وبذلك سيبدو الملف app.py حاليًا بالشّكل التالي:

import os
from flask import Flask, render_template, request, url_for, redirect
from flask_sqlalchemy import SQLAlchemy

from sqlalchemy.sql import func


basedir = os.path.abspath(os.path.dirname(__file__))

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] =\
        'sqlite:///' + os.path.join(basedir, 'database.db')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)


class Student(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    firstname = db.Column(db.String(100), nullable=False)
    lastname = db.Column(db.String(100), nullable=False)
    email = db.Column(db.String(80), unique=True, nullable=False)
    age = db.Column(db.Integer)
    created_at = db.Column(db.DateTime(timezone=True),
                           server_default=func.now())
    bio = db.Column(db.Text)

    def __repr__(self):
        return f''

نحفظ الملف ونغلقه.

إنشاء قاعدة بيانات

الآن وبعد الانتهاء من إعداد كل من الاتصال مع قاعدة البيانات ونموذج الطالب، سنستخدم صدفة فلاسك لإنشاء كل من قاعدة البيانات وجدول الطالب اعتمادًا على النموذج المسمّى Student.

نستخدم -بعد التأكّد من تفعيل البيئة الافتراضية- متغير البيئة FLASK_APP لتحديد الملف app.py على أنه يمثّل تطبيق فلاسك، ومن ثمّ نفتح صَدفة فلاسك باستخدام الأمر التالي وذلك أثناء وجودنا ضمن المجلد flask_app:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ flask shell

فتُفتح صَدفة بايثون تفاعلية خاصّة، تعمل على تشغيل الأوامر ضمن تطبيق فلاسك، وبذلك نضمن انّ دوال Flask-SQLAlchemy التي سنستدعيها ستتصل مع تطبيق فلاسك.

الآن، سنستورد كائن قاعدة البيانات ونماذج الطلاب، ومن ثمّ سنشغّل الدالة ()db.create_all بغية إنشاء الجداول الموافقة لتلك النماذج، ولكن في حالتنا لا يوجد سوى نموذج واحد، ما يعني أنّ استدعاء الدالة سينتج عنه إنشاء جدول وحيد في قاعدة البيانات على النحو التالي:

>>> from app import db, Student
>>> db.create_all()

نبقي الصدفة في حالة تشغيل، ونفتح نافذة طرفية جديدة وننتقل إلى المجلد flask_app، فنجد ملفًا جديدًا باسم database.db ضمنه.

ملاحظة: لا تنشئ الدالة ()db.create_all أو تحدّث جدولًا موجودًا أصلًا، فمثلًا لو عدلنا النموذج الذي أنشأناه بإضافة عمود جديد إليه، ومن ثمّ شغلنا الدالة ()db.create_all، فلن تُطبّق التغييرات التي أجريناها على النموذج على الجدول في حال كان الجدول موجودًا أصلًا في قاعدة البيانات، ويكون الحل لهذه المشكلة بحذف كافّة الجداول الموجودة في قاعدة البيانات باستخدام الدالة ()db.drop_all ومن ثمّ إعادة إنشائها باستخدام الدالة ()db.create_all، كما يلي:

>>> db.drop_all()
>>> db.create_all()

ستعمل هذه الشيفرة على تطبيق التعديلات على النماذج، كما ستحذف كافّة البيانات الموجودة في قاعدة البيانات، فلو أردت تحديث قاعدة البيانات مع الحفاظ على البيانات الموجودة فيها، لا بدّ من استخدام أداة ترحيل ملف تخطيط قاعدة البيانات schema migration، ويمكن باستخدامها تعديل الجداول مع الحفاظ على البيانات. لاستخدام هذه الأداة من الممكن الاستعانة بالإضافةFlask-Migrate لتنفيذ ترحيل ملف تخطيط قاعدة البيانات باستخدام الإضافة SQLAIchemy من خلال واجهة أسطر الأوامر في فلاسك.

وفي حال ظهور رسالة خطأ، يجب التأكّد من كون التصريح عن كل من النموذج ومعرّف الموارد الموحّد لقاعدة البيانات صحيحًا.

ملء الجدول

الآن وبعد إنشاء كلٍ من قاعدة البيانات وجدول الطالب، سنستخدم صدفة فلاسك لإضافة بعض الطلاب إلى قاعدة البيانات من خلال النموذج Student.

سنستخدم نفس صدفة فلاسك المُشغَّلة أصلًا، كما من الممكن فتح صَدفة جديدة بعد التأكد من تشغيل البيئة الافتراضية ضمن المجلد flask_app:

(env)user@localhost:$ flask shell

لإضافة طالب إلى قاعدة البيانات، لا بُدّ من استيراد كل من كائن قاعدة البيانات والنموذج Student، ثمّ بعد ذلك استنساخ النموذج لنمرر إليه بيانات الطالب عبر وسطائه الأساسية، على النحو التالي:

>>> from app import db, Student
>>> student_john = Student(firstname='john', lastname='doe',
>>>                        email='jd@example.com', age=23,
>>>                        bio='Biology student')

إذ يمثّل الكائن student_john الطالب المُراد إضافته إلى قاعدة البيانات، إلّا أنّ هذا الكائن لم يُنسخ إلى قاعدة البيانات بعد، لذا سنتحقّق من هذا الكائن في صدفة فلاسك للحصول على السلسلة النصية المُمثّلة له والتي أنشأناها باستخدام التابع ()__repr__:

>>> student_john

فيظهر لنا خرج بالشّكل:

 john>

ومن الممكن الحصول على قيم الأعمدة باستخدام سمات الصنف المُعرّفة أصلًا في النموذج Student:

>>> student_john.firstname
>>> student_john.bio

ويكون الخرج:

'john'
'Biology student'

بما أن هذا الطالب لم يُضاف إلى قاعدة البيانات بعد، ستكون قيمة مُعرّفه None:

>>> print(student_john.id)

ويكون الخرج:

None

لإضافة هذا الطالب إلى قاعدة البيانات، يجب إضافته أولًا إلى جلسة قاعدة بيانات database session التي تدير إجراءات قاعدة البيانات، إذ توفّر الإضافة Flask-SQLAlchemy الكائن db.session، الذي ندير تغيرات قاعدة البيانات من خلاله.

نضيف الكائن student_john إلى الجلسة باستخدام التابع ()db.session.add الذي يجهّزه للنسخ على قاعدة البيانات:

>>> db.session.add(student_john)

سيتطلّب إدخال الطالب في قاعدة البيانات استخدام التعليمة INSERT، ولكن لن يُخصَّص معرّف قبل تأكيد إجراءات قاعدة البيانات، ولتأكيد الإجراءات وحفظ تغيرات قاعدة البيانات، سنستخدم التابع ()db.session.commit كما يلي:

>>> db.session.commit()

والآن وبعد إضافة الطالب John إلى قاعدة البيانات، أصبح من الممكن الحصول على معرّفه، بالشّكل:

>>> print(student_john.id)

ويكون الخرج:

كما من الممكن استخدام التابع ()db.session.add لتحرير عنصر ما في قاعدة البيانات، فعلى سبيل المثال، من الممكن تعديل البريد الإلكتروني الخاص بالطالب على النحو التالي:

>>> student_john.email = 'john_doe@example.com'
>>> db.session.add(student_john)
>>> db.session.commit()

سنضيف الآن باستخدام صدفة فلاسك بضعة طلاب إلى قاعدة البيانات:

>>> sammy = Student(firstname='Sammy',
>>>                lastname='Shark',
>>>                email='sammyshark@example.com',
>>>                age=20,
>>>                bio='Marine biology student')

>>> carl = Student(firstname='Carl',
>>>                lastname='White',
>>>                email='carlwhite@example.com',
>>>                age=22,
>>>                bio='Marine geology student')

>>> db.session.add(sammy)
>>> db.session.add(carl)
>>> db.session.commit()

من الممكن الآن الاستعلام عن كافّة السجلات في جدول الطلاب باستخدام السمة query مع التابع ()all، كما يلي:

>>> Student.query.all()

فيظهر الخرج التالي:

[, , ]

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

الخطوة 3 – عرض جميع السجلات

سنعمل في هذه الخطوة على إنشاء وجهة وقالب لعرض كافّة الطلاب الموجودين في قاعدة البيانات ضمن الصفحة الرئيسية للتطبيق. لذلك، نبقي صَدفة فلاسك قيد التشغيل، ونفتح نافذة طرفية جديدة.

نفتح ملف app.py لنضيف إليه وجهةً للصفحة الرئيسية:

(env)user@localhost:$ nano app.py

ونضيف الوجهة التالية إلى نهاية الملف:

# ...

@app.route('/')
def index():
    students = Student.query.all()
    return render_template('index.html', students=students)

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة المُزخرف ()app.route لإنشاء دالة عرض باسم ()index، والتي نستعلم فيها ضمن قاعدة البيانات لجلب كافّة الطلاب باستخدام السمة query من النموذج Student، التي تمكننا من جلب عنصر أو أكثر من قاعدة البيانات باستخدام توابع مُختلفة، واستخدمنا التابع ()all لجلب كافّة مُدخلات الطلاب من قاعدة البيانات، لنخزّن نتائج الاستعلام ضمن متغير باسم students ممررين إياه إلى ملف قالب باسم index.html والذي سنصيّره باستخدام الدالة المساعدة ()render_template.

الآن، وقبل إنشاء ملف القالب index.htmlالمسؤول عن عرض الطلاب الموجودين ضمن قاعدة البيانات في الصفحة الرئيسية للتطبيق، سننشئ ملف قالب رئيسي ليتضمّن كافة شيفرات HTML الأساسية اللازمة لترثها لاحقًا القوالب الأُخرى وهذا ما يجنبنا تكرار الشيفرات، ثمّ سننشئ ملف قالب الصفحة الرئيسية index.html المُصيّر أصلًا باستخدام الدالة ()index.

لذا سننشئ مجلدًا للقوالب باسم templates، وسننشئ ضمنه ملف قالب باسم base.html، الذي سيمثّل القالب الأساسي لبقية القوالب:

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html

وسنكتب فيه الشيفرة التالية:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">Create
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

يتضمّن القالب الأساسي هذا كافّة الشيفرات المتداولة التي سنحتاجها في القوالب الأُخرى.

ستُستبدل كتلة العنوان title لاحقًا بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن ثلاثة روابط، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for، والثاني إلى صفحة إضافة طالب جديد Create، أمّا الأخير لصفحة المعلومات حول التطبيق About في حال قررت تضمينها في تطبيقك، مع ملاحظة أنّنا سنعدّل هذا الملف لاحقًا بعد إنشاء صفحة إضافة طالب جديد بغية جعل الرابط إلى هذه الصفحة فعّالًا.

الآن، سننشئ ملف قالب باسم index.html وهو الاسم الذي حددناه في الملف app.py:

(env)user@localhost:$ nano templates/index.html

ونضيف ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1 class="title">{% block title %} Students {% endblock %}h1>
    <div class="content">
        {% for student in students %}
            <div class="student">
                <p><b>#{{ student.id }}b>p>
                <b>
                    <p class="name">{{ student.firstname }} {{ student.lastname }}p>
                b>
                <p>{{ student.email }}p>
                <p>{{ student.age }} years old.p>
                <p>Joined: {{ student.created_at }}p>
                <div class="bio">
                    <h4>Bioh4>
                    <p>{{ student.bio }}p>
                div>
            div>
        {% endfor %}
    div>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب base.html من خلال تعليمة extends، واستبدلنا محتوى كتلة المحتوى content مُستخدمين تنسيق العنوان من المستوى الأوّل

الذي يفي أيضًا بالغرض عنوانًا للصفحة.

استخدمنا في السطر البرمجي {% for post in posts %} حلقة for من تعليمات محرّك القوالب جينجا jinja، والهدف من استخدام هذه الحلقة هو المرور على كل طالب ضمن المتغير students المُمرّر من الدالة ()index إلى هذا القالب، إذ سنعرض معرّف الطالب واسمه الأوّل والأخير وتاريخ إضافته إلى قاعدة البيانات وسيرته الذاتية.

الآن ومع وجودنا ضمن المجلد flask_app ومع كون البيئة الافتراضية مُفعّلة، سنُعلم فلاسك بالتطبيق المُراد تشغيله (وهو في حالتنا الملف app.py) باستخدام متغير البيئة FLASK_APP، في حين يحدّد متغير البيئة FLASK_ENV وضع التشغيل وهنا قد اخترنا الوضع development ما يعني أنّ التطبيق سيعمل في وضع التطوير مع تشغيل مُنقّح الأخطاء. لمزيدٍ من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

والآن سنشغّل التطبيق باستخدام الأمر flask run:

(env)user@localhost:$ flask run

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

http://127.0.0.1:5000/

فيظهر لنا الطلاب المُضافين إلى قاعدة البيانات في صفحة مشابهة للصورة التالية:

عرضنا في هذه الخطوة كافّة الطلاب الموجودين ضمن قاعدة البيانات في الصفحة الرئيسية للتطبيق، أمّا في الخطوة التالية فسنعمل على إنشاء وجهة لصفحة كل طالب، وسنعرض فيها تفاصيل كل طالب بصورةٍ منفردة.

الخطوة 4 – عرض سجل مفرد

سنستخدم في هذه الخطوة صدفة فلاسك للاستعلام عن الطلاب من خلال معرّفاتهم، كما سننشئ وجهة وقالب لعرض التفاصيل الخاصة بكل طالب في صفحة مُخصّصة لذلك.

سيعرض الرابط http://127.0.0.1:5000/1 في نهاية هذه الخطوة صفحةً تعرض الطالب الأول (لأن الرابط يحوي على المعرّف رقم 1)، بينما يعرض الرابط http://127.0.0.1:5000/ID الطالب ذو المعرّف ID الموافق له إن وُجد.

نبقي خادم التطوير قيد التشغيل، ونفتح نافذة طرفية جديدة.

الآن سنفتح صدفة فلاسك لنبيّن كيفيّة الاستعلام عن الطلاب، كما يلي:

(env)user@localhost:$ flask shell

توفّر الإضافة Flask-SQLAlchemy السمة query ضمن صنف النموذج للاستعلام عن السجلات وجلب البيانات الموافقة من قاعدة البيانات، ويمكن استخدام توابع هذه السمة لجلب السجلات وفقًا لمُرشّح مُعيّن. على سبيل المثال، من الممكن استخدام تابع الترشيح ()filter_by مع معامل مثل firstname الذي يوافق عمودًا معينًا في الجدول مع استخدام وسيط لجلب طالب معيّن:

>>> from app import db, Student
>>> Student.query.filter_by(firstname='Sammy').all()

فيكون الخرج على النحو التالي:

[]

جلبنا في الشيفرة السابقة جميع الطلاب الذين يحملون القيمة Sammy في الاسم الأوّل، كما استخدمنا التابع ()all للحصول على قائمة بجميع النتائج الموافقة، أمّا للحصول على النتيجة الأولى فقط (وهي النتيجة الوحيدة في حالتنا)، نستخدم التابع ()first كما يلي:

>>> Student.query.filter_by(firstname='Sammy').first()

فيكون الخرج بالشّكل:

يمكننا استخدام التعليمة (filter_by(id=ID للحصول على الطالب من خلال معرّفه على النحو التالي:

>>> Student.query.filter_by(id=3).first()

أو يمكننا استخدام التابع الأقصر ()get والذي يمكنّنا من جلب عنصر معين باستخدام مفتاحه الأساسي، كما يلي:

>>> Student.query.get(3)

ستعطي كلا الطريقتين الخرج نفسه:

أصبح من الممكن الآن الخروج من الصدفة:

>>> exit()

لجلب بيانات طالب من خلال معرّفه، أنشأنا وجهةً جديدةً تُصيّر صفحةً لكل طالب، إذ استخدمنا التابع ()get_or_404 الذي توفرّه الإضافة Flask-SQLAlchemy بديلًا للتابع ()get التقليدي؛ إذ يكمن الفرق بينهما في أنّ التابع ()get يعيد القيمة None في حال عدم وجود نتيجة موافقة للمعرّف المطلوب، في حين يعيد التابع ()get_or_404 خطأ HTTP من النوع ‎404 Not Found، لذا سنفتح الملف app.py لتعديله، بالشّكل:

(env)user@localhost:$ nano app.py

ونضيف الوجهة التالية إلى نهاية الملف:

# ...

@app.route('//')
def student(student_id):
    student = Student.query.get_or_404(student_id)
    return render_template('student.html', student=student)

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة الوجهة //، إذ يمثّل المعامل :int محوّلًا لتحويل السلسلة النصية الافتراضية في الرابط إلى نوع عدد صحيح، ويمثل student_id متغير الرابط الذي سيُحدّد الطالب المطلوب عرضه في الصفحة.

مررنا المعرّف من الرابط إلى دالة العرض ()student من خلال المعامل student_id، التي نستعلم فيها عن مجموعة الطلاب لنجلب منها الطالب من خلال المعرّف الخاص به باستخدام التابع ()get_or_404، الأمر الذي يؤدي إلى حفظ بيانات الطالب (في حال وجوده) ضمن المتغير student، وإلّا ستُعرض استجابة خطأ HTTP من النوع ‎404 Not Found في حال عدم وجود طالب موافق للمعرّف المطلوب في قاعدة البيانات، ثمّ صيّرنا أخيرًا قالبًا باسم student.html ممررين إليه بيانات الطالب المُستخرجة.

لذا، سنفتح ملف قالب جديد باسم student.html:

(env)user@localhost:$ nano templates/student.html

ونكتب فيه الشيفرة التالية، والأمر مشابه للقالب index.html باستثناء أنّ هذا الملف سيعرض طالبًا واحدًا كل مرة:

{% extends 'base.html' %}

{% block content %}
    <span class="title">
        <h1>{% block title %} {{ student.firstname }} {{ student.lastname }}{% endblock %}h1>
    span>
    <div class="content">
            <div class="student">
                <p><b>#{{ student.id }}b>p>
                <b>
                    <p class="name">{{ student.firstname }} {{ student.lastname }}p>
                b>
                <p>{{ student.email }}p>
                <p>{{ student.age }} years old.p>
                <p>Joined: {{ student.created_at }}p>
                <div class="bio">
                    <h4>Bioh4>
                    <p>{{ student.bio }}p>
                div>
            div>
    div>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب base.html من خلال تعليمة extends، وجعلنا اسم الطالب الكامل عنوانًا للصفحة، كما عرضنا كلًا من معرّف الطالب واسمه الأول والأخير وبريده الإلكتروني وتاريخ إنشاء السجل وسيرته الذاتية.

ننتقل الآن باستخدام متصفح الويب إلى رابط الطالب الثاني كما يلي:

http://127.0.0.1:5000/2

فتظهر صفحةٌ مشابهةٌ لما يلي:

ومن ثمّ سنحرّر ملف القالب index.html لنربط اسم كل طالب مع الصفحة الخاصة به:

(env)user@localhost:$ nano templates/index.html

ونعدّل حلقة for التكرارية على النحو التالي:

{% for student in students %}
    <div class="student">
        <p><b>#{{ student.id }}b>p>
        <b>
            <p class="name">
                <a href="{{ url_for('student', student_id=student.id)}}">
                    {{ student.firstname }} {{ student.lastname }}
                a>
            p>
        b>
        <p>{{ student.email }}p>
        <p>{{ student.age }} years old.p>
        <p>Joined: {{ student.created_at }}p>
        <div class="bio">
            <h4>Bioh4>
            <p>{{ student.bio }}p>
        div>
    div>
{% endfor %}

نحفظ الملف ونغلقه.

أضفنا في الشيفرة السابقة وسم الرابط إلى الاسم الكامل للطالب، بغية ربطه مع صفحة الطالب الموافقة باستخدام الدالة ()url_for، ممررين معرّف الطالب ID المُخزّن في الكائن student.id إلى دالة العرض ()student.

ننتقل إلى الصفحة الرئيسية للتطبيق ونحدّثها:

http://127.0.0.1:5000/

وبذلك نلاحظ أنّ اسم كل طالب أصبح مرتبطًا بصفحة الطالب الموافقة.

الآن، وبعد الانتهاء من إنشاء صفحة لكل طالب، سنعمل في الخطوة التالية على إنشاء صفحة لإضافة طلاب جدد إلى قاعدة البيانات.

الخطوة 5 – إنشاء سجل جديد

سنعمل في هذه الخطوة على إضافة وجهة جديدة للتطبيق بغية إضافة طلاب جدد إلى قاعدة البيانات باستخدام نماذج ويب، إذ سنعمل على تصيير صفحة تتضمّن نموذج ويب يمكّن المستخدمين من إدخال بيانات الطالب، ثم سنوفّر الآليات اللازمة للتعامل مع النموذج المُرسل، وسننشئ كائنًا للطالب الجديد المضاف باستخدام النموذج Student لنضيفه إلى الجلسة، ونهايةً سنحفظ الإجراءات بما يشبه الآلية المُتبعة لدى إضافة مُدخلات الطالب في الخطوة 2 من هذا المقال.

سنفتح نافذة طرفية جديدة مع بقاء خادم التطوير قيد التشغيل، وسنفتح منها بدايةً الملف app.py:

(env)user@localhost:$ nano app.py

وسنضيف في نهايته الوجهة التالية:

# ...


@app.route('/create/', methods=('GET', 'POST'))
def create():
    return render_template('create.html')

نحفظ الملف ونغلقه.

نمرّر في هذه الوجهة متغير صف tuple يحتوي على القيم ('GET', 'POST') إلى المعامل methods بغية السماح بكلا نوعي طلبيات HTTP وهما GET و POST، إذ تتخصّص الطلبيات من النوع GET بجلب البيانات من الخادم، أمّا الطلبيات من النوع POST فهي مُتخصّصة بإرسال البيانات إلى وجهة مُحدّدة، مع ملاحظة أنّ الطلبيات من النوع GET هي الوحيدة المسموحة افتراضيًا، وحالما يطلب المستخدم الوجهة create/ باستخدام طلبية من النوع GET، سيُصيّر ملف قالب باسم "create.html". سنعدّل هذه الوجهة لاحقًا لتتعامل أيضًا مع الطلبيات POST اللازمة لدى ملء المُستخدمين للنماذج وإرسالها بغية إضافة طلاب جدد.

الآن، سننشئ ملفًا باسم "create.html" داخل مجلد القوالب "templates" على النحو التالي:

(env)user@localhost:$ nano templates/create.html

ونكتب ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1 style="width: 100%">{% block title %} Add a New Student {% endblock %}h1>
    <form method="post">
        <p>
            <label for="firstname">First Namelabel>
            <input type="text" name="firstname"
                   placeholder="First name">
            input>
        p>

        <p>
            <label for="lastname">Last Namelabel>
            <input type="text" name="lastname"
                   placeholder="Last name">
            input>
        p>

        <p>
            <label for="email">Emaillabel>
            <input type="email" name="email"
                   placeholder="Student email">
            input>
        p>

        <p>
            <label for="age">Agelabel>
            <input type="number" name="age"
                   placeholder="Age">
            input>
        p>

        <p>
        <label for="bio">Biolabel>
        <br>
        <textarea name="bio"
                  placeholder="Bio"
                  rows="15"
                  cols="60"
                  >textarea>
        p>
        <p>
            <button type="submit">Submitbutton>
        p>
    form>
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب base.html من خلال تعليمة extends، كما عيّنا ترويسة لتكون عنوانًا، واستخدمنا الوسم وفيه ضبطنا السمة method التي تُحدّد نوع طلبية HTTP لتكون من النوع post، ما يعني أنّ نموذج الويب هذا سيرسل طلب من النوع "POST".

كما أضفنا صندوقي حقل نصي باسم firstname و lastname، إذ سنستخدم هذه الأسماء لاحقًا للوصول إلى بيانات النموذج الذي أرسلها المستخدم في دالة العرض، كما أضفنا حقلًا نصيًا للبريد الالكتروني باسم email، وحقل بيانات عددية لإدخال عمر الطالب، وحقلاً نصياً مُتعدّد الأسطر لإضافة السيرة الذاتية للطالب، وأخيراً أضفنا زرًا لتأكيد النموذج وإرساله Submit إلى نهاية النموذج.

الآن، وأثناء عمل خادم التطوير، نستخدم المتصفح للانتقال إلى الوجهة ‎/create:

http://127.0.0.1:5000/create

فستظهر صفحة إضافة طالب جديد Add a New Student تتضمّن نموذج ويب، وزرًا لتأكيد إرسال هذا النموذج Submit، كما في الشّكل:

يرسل نموذج الإدخال هذا طلبًا من النوع POST إلى الخادم، ولكن حتى هذه اللحظة لا يوجد شيفرة مسؤولة عن معالجة هذا الطلب في الوجهة create/، وبالتالي لن يحدث شيء في حال ملء النموذج الآن وإرساله.

الآن، سنفتح الملف app.py بهدف تعديله ليتعامل مع الطلبات من النوع POST المُرسلة من قبل المستخدم:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة create/ لتصبح كما يلي:

@app.route('/create/', methods=('GET', 'POST'))
def create():
    if request.method == 'POST':
        firstname = request.form['firstname']
        lastname = request.form['lastname']
        email = request.form['email']
        age = int(request.form['age'])
        bio = request.form['bio']
        student = Student(firstname=firstname,
                          lastname=lastname,
                          email=email,
                          age=age,
                          bio=bio)
        db.session.add(student)
        db.session.commit()

        return redirect(url_for('index'))

    return render_template('create.html')

نحفظ الملف ونغلقه.

تُعامل الطلبيات من النوع POST ضمن العبارة الشرطية if request.method == 'POST'، إذ يُستخرج كل من اسم الطالب الأوّل والأخير وبريده الإلكتروني وعمره وسيرته الذاتية التي أرسلها المُستخدم، من الكائن request.form، ليُحوّل العمر المُمرّر مثل سلسة نصيّة إلى نوع عدد صحيح باستخدام دالة بايثون()int، ليُبنى بعدها كائن للطالب باسم student باستخدام النموذج Student، ومن ثم نضيف هذا الكائن إلى جلسة قاعدة البيانات، ونحفظ التغييرات.

ونهايةً، نعيد توجيه المستخدم إلى الصفحة الرئيسية للتطبيق فيظهر الطالب المُضاف أسفل الطلاب الموجودين أصلًا.

الآن وأثناء عمل خادم التطوير، نستخدم المتصفح للانتقال إلى الوجهة ‎/create:

http://127.0.0.1:5000/create

نملأ النموذج ببعض البيانات ونرسله، فيُعاد التوجيه إلى الصفحة الرئيسية، إذ سنجد الطالب المُضاف للتو، وبذلك أصبحت لدينا الآلية اللازمة لإضافة طلاب جدد، الآن، لا بدّ من إضافة رابط إلى صفحة الإضافة Create في شريط التصفح، لذا نفتح ملف القالب base.html:

(env)user@localhost:$ nano templates/base.html

سنحرّر جزء الوسم بتعديل قيمة سمة الرابط href لتصبح مساوية لرابط صفحة الإنشاء Create.


    
         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('create') }}">Create
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

وبتحديث الصفحة الرئيسية للتطبيق نلاحظ أنّ الرابط Create في شريط التصفّح بات فعّالًا.

ومع نهاية هذه الخطوة أصبح لدينا صفحة تتضمّن نموذج ويب لإضافة طلاب جدد، وللمزيد حول نماذج الويب ننصحك بقراءة المقال كيفية استخدام نماذج الويب في تطبيقات فلاسك، ولمزيدٍ من المعلومات المتقدمة ولتتعرّف على كيفية إدارة نماذج الويب بأمان ننصحك بقراءة المقال استخدام والتحقق من نماذج الويب ذات واجهة المستخدم التفاعلية في فلاسك باستخدام الإضافة Flask-WTF.

سنعمل في الخطوة التالية على إضافة صفحة لتعديل بيانات الطلاب الموجودين أصلًا في قاعدة البيانات.

الخطوة 6 – تعديل سجل

سنعمل في هذه الخطوة على إضافة صفحة جديدة إلى التطبيق بغية تعديل بيانات الطلاب الموجودة أصلًا في قاعدة البيانات. إذ سنضيف وجهة جديدة /ID/edit/ لتعديل بيانات الطلاب بناءً على معرّف ID كل منهم.

بدايةً، نفتح الملف app.py:

(env)user@localhost:$ nano app.py

ثمّ نضيف الوجهة التالية إلى نهاية الملف، والتي ستجلب المُدخل المراد تعديله من بيانات الطالب باستخدام المعرّف الموافق، لتستخرج البيانات الجديدة المُرسلة من نموذج ويب مُخصّص لهذا الغرض سننشئه لاحقًا، لتعدّل بيانات الطالب ومن ثمّ تعيد توجيه المستخدم إلى صفحة التطبيق الرئيسية:

# ...


@app.route('//edit/', methods=('GET', 'POST'))
def edit(student_id):
    student = Student.query.get_or_404(student_id)

    if request.method == 'POST':
        firstname = request.form['firstname']
        lastname = request.form['lastname']
        email = request.form['email']
        age = int(request.form['age'])
        bio = request.form['bio']

        student.firstname = firstname
        student.lastname = lastname
        student.email = email
        student.age = age
        student.bio = bio

        db.session.add(student)
        db.session.commit()

        return redirect(url_for('index'))

    return render_template('edit.html', student=student)

نحفظ الملف ونغلقه.

تتعامل الوجهة /int:student_id>/edit>/ مع طلبيات HTTP من النوع POST و GET، إذ تستخدم student_id مثل متغير رابط مسؤول عن تمرير المعرّف ID إلى دالة العرض ()edit.

استخدمنا تابع الاستعلام ()get_or_404 على النموذج Student للحصول على الطالب الموافق للمعرّف المطلوب، والذي سيستجيب بخطأ من النوع "‎404 Not Found" في حال عدم تطابق أي طالب في قاعدة البيانات مع المعرّف المطلوب؛ أمّا في حال وجود طالب موافق للمعرّف المطلوب، فسيُستكمل تنفيذ الشيفرة وصولًا إلى العبارة الشرطية 'if request.method == 'POST، فإذا كانت الطلبية من النوع GET فهذا يعني أنّ المُستخدم لم يملأ نموذج التعديل ويرسله، وبالتالي لن يتحقق الشرط السابق وسنتخطى التعليمات الواردة ضمنه وصولًا إلى السطر البرمجي:

 return render_template('edit.html', student=student)

المسؤول عن تصيير القالب "edit.html" الذي سننشئة لاحقًا، مُمرّرًا إليه كائن الطالب المستخرج من قاعدة البيانات لتُعرض بيانات الطالب الحالية في نموذج الويب.

في حال عدّل المستخدم بيانات الطالب في نموذج التعديل وأرسله، فعندها سيتحقق الشرط if request.method == 'POST' وبالتالي ستُنفّذ التعليمات الواردة ضمنه، إذ ستُستخرج بيانات الطالب المُرسلة من الكائن request.form إلى المتغير الموافق لكل منها، لتُضبط كل سمة من سمات كائن الطالب student لتوافق القيم الجديدة المُرسلة من النموذج عبر تعديل قيم الأعمدة بنفس الآلية المُتبعة في الخطوة 2 من هذا المقال؛ وفي حال عدم تعديل أي من حقول نموذج الويب، ستبقى قيم الأعمدة في قاعدة البيانات على حالها.

بعد ضبط بيانات الطالب إلى تلك الجديدة المرسلة، سنضيف الكائن student إلى جلسة قاعدة البيانات ونحفظ التغييرات، ونهايةً سنعيد توجيه المستخدم إلى الصفحة الرئيسية للتطبيق.

والآن سنعمل على إنشاء صفحة تسمح للمستخدمين بإجراء التعديلات، لذا سننشئ ملف القالب edit.html:

user@localhost:$ nano templates/edit.html

سيحتوي هذا الملف الجديد على نموذج ويب مشابه لذلك الموجود في ملف القالب create.html، بحيث يُملأ افتراضيًا بالبيانات الحالية للطالب، لذا سنكتب ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1 style="width: 100%">
        {% block title %} Edit {{ student.firstname }}
                               {{ student.lastname }}'s Details
        {% endblock %}
    
    
        
            First Name
            
            
        

        
            Last Name
            
            
        

        
            Email
            
            
        

        
            Age
            
            
        

        
        Bio
        

        {{ student.bio }}
        
        
            
        
    
{% endblock %}

نحفظ الملف ونغلقه.

يضم العنوان كلًا من الاسم الأوّل والأخير للطالب، وتُضبط خاصية القيمة value لكل حقل إدخال وللصندوق النصي المُتعدّد الأسطر المُخصّص للسيرة الذاتية لتساوي القيمة الموافقة من كائن الطالب student المُمرر من الدالة ()edit إلى ملف القالب "edit.html".

سننتقل الآن إلى الرابط التالي لنعدّل تفاصيل أوّل طالب:

http://127.0.0.1:5000/1/edit

فتظهر صفحة مشابه للشكل التالي:

نعدّل بيانات الطالب ونرسل النموذج، فيُعاد توجيهنا إلى الصفحة الرئيسية للتطبيق فنلاحظ أنّ معلومات الطالب قد حُدثّت فعلًا، ثم سنضيف زر تعديل Edit أسفل كل طالب في الصفحة الرئيسية لنربط كل منهم بصفحة التعديل الخاصة به، لذا نفتح ملف القالب index.html:

(env)user@localhost:$ nano templates/index.html

نعدل حلقة for التكرارية في هذا الملف لتبدو تمامًا كما يلي:

{% for student in students %}
    <div class="student">
        <p><b>#{{ student.id }}b>p>
        <b>
            <p class="name">
                <a href="{{ url_for('student', student_id=student.id)}}">
                    {{ student.firstname }} {{ student.lastname }}
                a>
            p>
        b>
        <p>{{ student.email }}p>
        <p>{{ student.age }} years old.p>
        <p>Joined: {{ student.created_at }}p>
        <div class="bio">
            <h4>Bioh4>
            <p>{{ student.bio }}p>
        div>
        <a href="{{ url_for('edit', student_id=student.id) }}">Edita>
    div>
{% endfor %}

نحفظ الملف ونغلقه.

أضفنا في الشيفرة السابقة وسم الرابط للربط مع دالة العرض ()edit ممررين إليها القيمة student.id للربط مع صفحة التعديل لكل طالب باستخدام رابط تعديل صفحة Edit.

ومع نهاية هذه الخطوة أصبح لدينا صفحة لتعديل بيانات الطلاب الموجودين في قاعدة البيانات، وسنعمل فيما يلي على إضافة زر حذف Delete لحذف طلاب من قاعدة البيانات.

الخطوة 7– حذف سجل

سنعمل في هذه الخطوة على إضافة وجهة جديدة وزر حذف Delete يسمح بحذف الطلاب الموجودين أصلًا في قاعدة البيانات.

بدايةً، سنضيف وجهةً جديدةً للحذف، وهي ‎/id/delete تتعامل مع الطلبات من النوع POST، إذ ستستقبل دالة الحذف الجديدة delete()‎ رقم معرّف الطالب ID المراد حذفه ممرّرة إياه إلى تابع الاستعلام ()get_or_404 في النموذج Student لمعرفة ما إذا كان موجودًا، للاستجابة بصفحة خطأ من النوع "‎404 Not Found" في حال عدم وجود طالب موافق للمعرّف المُمرّر في قاعدة البيانات.

الآن، افتح الملف app.py:

(env)user@localhost:$ nano app.py

أضِف الوجهة التالية إلى نهاية الملف:

# ...

@app.post('//delete/')
def delete(student_id):
    student = Student.query.get_or_404(student_id)
    db.session.delete(student)
    db.session.commit()
    return redirect(url_for('index'))

نحفظ الملف ونغلقه.

استخدمنا المزخرف app.post المُقدّم في الإصدار 2.0.0 من فلاسك بدلًا من استخدام المزخرف app.route المعتاد، لإضافة اختصارات للعديد من توابع HTTP الشائعة، فعلى سبيل المثال الأمر:

@app.post("/login")

هو اختصار للأمر:

@app.route("/login", methods=["POST"])

ما يعني أن دالة العرض هذه تتعامل فقط مع طلبيات من النوع POST، وبزيارة الوجهة ID/delete/ في المتصفّح سيظهر الخطأ "‎405 Method Not Allowed" لأن المتصفحات تستخدم طريقة GET افتراضيًا للطلبات، لذا بغية حذف طالب ما، سنضيف زر أوامر عندما يضغط المستخدم عليه، تُرسَل إلى الوجهة طلبًا من النوع POST.

تستقبل دالة العرض ()delete في الشيفرة السابقة معرّف الطالب المراد حذفه من خلال متغير الرابط student_id، إذ يُستخدم التابع ()get_or_404 لجلب بيانات الطالب وحفظها في متغير باسم student، أو الاستجابة بخطأ من النوع ‎404 Not Found في حال عدم وجود طالب موافق.

كما استخدمنا التابع delete في الجلسة المفتوحة مع قاعدة البيانات في السطر البرمجي (db.session.delete(student ممررين إليه الكائن الممثل للطالب، وهذا ما يجعل الجلسة بالنتيجة تحذف الطالب الموافق بمجرّد تأكيد الإجراءات، إذ ما من حاجة لإجراء أي تعديلات إضافية كون الإجراءات تُؤكَّد مباشرةً باستخدام الأمر ()db.session.commit، ونهايةً أعدنا توجيه المستخدم إلى الصفحة الرئيسية للتطبيق.

سنعدّل القالب index.html بإضافة زر لحذف طالب Delete Student:

user@localhost:$ nano templates/index.html

وسنعدّل حلقة for التكرارية بإضافة وسم نموذج

مباشرةً أسفل رابط التعديل Edit:

{% for student in students %}
    <div class="student">
        <p><b>#{{ student.id }}b>p>
        <b>
            <p class="name">
                <a href="{{ url_for('student', student_id=student.id)}}">
                    {{ student.firstname }} {{ student.lastname }}
                a>
            p>
        b>
        <p>{{ student.email }}p>
        <p>{{ student.age }} years old.p>
        <p>Joined: {{ student.created_at }}p>
        <div class="bio">
            <h4>Bioh4>
            <p>{{ student.bio }}p>
        div>
        <a href="{{ url_for('edit', student_id=student.id) }}">Edita>

        <hr>
        <form method="POST"
                action="{{ url_for('delete', student_id=student.id) }}">
            <input type="submit" value="Delete Student"
                onclick="return confirm('Are you sure you want to delete this entry?')">
        form>

    div>
{% endfor %}

نحفظ الملف ونغلقه.

أنشأنا في الملف السابق نموذج ويب يُرسل طلبًا من النوع POST إلى دالة العرض ()delete ممررين القيمة student.id وسيطًا للمعامل student_id لتحديد مُدخل الطالب المراد حذفه، كما استخدمنا التابع confirm()‎ المتوفّر في متصفحات الويب لعرض رسالة تأكيد قبل إرسال الطلب.

الآن وبتحديث الصفحة الرئيسية للتطبيق، سيظهر زر أوامر لحذف الطالب Delete Student أسفل كل مُدخل طالب، وبالنقر عليه ستظهر رسالة لتأكيد عملية الحذف، ومن ثمّ سيعيد التطبيق التوجيه إلى صفحته الرئيسية فنلاحظ حذف الطالب فعلًا.

وبذلك أصبح لدينا آلية لحذف الطلاب من قاعدة البيانات في تطبيق إدارة الطلاب هذا.

الخاتمة

عملنا في هذا المقال على بناء تطبيق ويب مُصغّر في فلاسك لإدارة الطلاب باستخدام كل من إطار عمل فلاسك والإضافة Flask-SQLAlchemy مع قاعدة بيانات SQLite، كما تعلمنا كيفية الاتصال مع قاعدة البيانات وإعداد نماذج قاعدة البيانات التي تمثل الجداول، وكيفية إضافة العناصر إلى قاعدة البيانات وإنشاء الاستعلامات ضمن جدول معين، وكيفيّة تعديل البيانات في قاعدة البيانات.

مكنّنا استخدام الإضافة SQLAlchemy في التطبيق من استخدام أصناف وكائنات بايثون لإدارة قاعدة بيانات SQL، وكان من الممكن استخدام أي محرّك قواعد بيانات بدلًا من SQLite، وفي هذه الحالة لن نضطر إلى تغيير أي شيء في شيفرة التطبيق الرئيسية باستثناء ضبط SQLALCHEMY_DATABASE_URI المسؤول عن عملية الاتصال، ما يسمح لنا بالانتقال من محرّك قواعد البيانات SQL إلى أي محرّك آخر بأقل تعديلات على الشيفرة البرمجية.

ترجمة -وبتصرف- للمقال How to Use Flask-SQLAlchemy to Interact with Databases in a Flask Application لصاحبه Abdelhadi Dyouri.

استخدام قاعدة البيانات MongoDB في تطبيق فلاسك

Sat, 28 Jan 2023 16:00:00 +0000

نحتاج عادةً إلى قاعدة بيانات في تطبيقات الويب، وهي مجموعةٌ مُنطمّةٌ من البيانات نستخدمها لتخزين وتنظيم البيانات الدائمة، موفّرةً لنا إمكانية استرجاع هذه البيانات ومعالجتها بفعالية، إذ نحتاج مثلًا في تطبيق ما للتواصل الاجتماعي إلى قاعدة بيانات لتخزين بيانات المستخدم (من معلومات شخصية ومنشورات وتعليقات ومتابعين) لنتمكّن من معالجتها بفعالية، إذ توفّر قاعدة البيانات إمكانية إضافة بيانات جديدة إليها، أو استرجاع بيانات مُخزّنة أصلًا، أو التعديل عليها، أو حذفها بكل مرونة وذلك اعتمادًا على المتطلبات والشروط والظروف المُختلفة، ففي تطبيق ويب ما قد تكون هذه المتطلبات مثلًا هي حالة إضافة المُستخدم لمنشور جديد، أو حذف منشور سابق، أو حذف حسابه مع كافّة منشوراته أو مع الإبقاء عليها، بمعنى أنّ طريقة معالجة البيانات تعتمد أولًا وأخيرًا على الميزات التي يتيحها التطبيق، فمثلًا قد لا ترغب بالسماح لمُستخدمي تطبيقك بإضافة منشورات غير معنونة.

يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا عدد أدوات وميزات من شأنها إنشاء تطبيقات ويب في لغة بايثون.

أمّا MongoDB، فهو برنامج قواعد بيانات عام الأغراض ومستندي التوجّه document-oreiented من نوع NoSQL، الذي يستخدم المستندات المشابهة لصيغة JSON لتخزين البيانات. تتيح قواعد البيانات المُعتمدة على المستندات المشابهة لصيغة JSON تخطيطًا ديناميكيًا مرنًا لقاعدة البيانات مع الحفاظ على بساطتها على عكس العلاقات المتعددة بين الجداول المُستخدمة في قواعد البيانات العلّاقية، فعمومًا تتميز قواعد البيانات من النوع NoSQL بالتوسّع الأفقي، ما يجعلها مناسبةً للبيانات الضخمة وتطبيقات الوقت الحقيقي.

سنعمل في هذا المقال على بناء تطبيق ويب مصغر لإنشاء قوائم المهام ومن خلاله سنوضّح كيفية استخدام المكتبة PyMongo، وهي محرك قواعد بيانات يتيح إمكانية التخاطب مع قاعدة بيانات MongoDB باستخدام لغة بايثون، وسنستخدمها ضمن فلاسك Flask لتأدية مهام التطبيق الأساسية، مثل الاتصال بخادم قاعدة البيانات وإنشاء التجميعات Collections التي من شأنها تخزين مجموعة من المستندات في قاعدة البيانات MongoDB وإدخال البيانات ضمن تجميعة ما، إضافةً إلى جلب وحذف البيانات من التجميعات.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بُدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو flask_app.
توفّر محرّك قواعد بيانات MongoDB مثبّتٍ على حاسوبك، وفي هذا الصدد ننصحك بقراءة المقال كيفية تثبيت وتأمين MongoDB على أوبونتو 18.04 للمزيد حول كيفية إعداد قاعدة بيانات MongoDB.
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض والقوالب، وفي هذا الصدد يمكنك الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.

الخطوة 1 - إعداد مكتبة PyMongo وإطار فلاسك

سنعمل في هذه الخطوة على تثبيت كل من فلاسك والمكتبة PyMongo.

لذا، وبعد التأكّد من تفعيل البيئة الافتراضية، نستخدم أمر تثبيت الحزم pip لتثبيت كل من فلاسك ومكتبة PyMongo على النحو التالي:

(env)user@localhost:$ pip install Flask pymongo

وبمجرّد انتهاء التثبيت بنجاح، سيظهر في نهاية الخرج سطر شبيه بما يلي مؤكدًا نجاح العملية:

Successfully installed Flask-2.0.2 Jinja2-3.0.3 MarkupSafe-2.0.1 Werkzeug-2.0.2 click-8.0.3 itsdangerous-2.0.1 pymongo-4.0.1

وبذلك نكون قد ثبتنا حزم بايثون اللازمة، وفيما يلي سنعمل على الاتصال بخادم قاعدة البيانات MongoDB وإنشاء تجميعة.

الخطوة 2 - الاتصال بخادم MongoDB وإنشاء تجميعة

سنستخدم في هذه الخطوة مكتبة PyMongo لإنشاء عميل سنستخدمه في التخاطب مع خادم MongoDB، وإنشاء قاعدة بيانات، ومن ثم إنشاء تجميعة لتخزين المهام ضمنها.

الآن وبعد التأكّد من تفعيل البيئة الافتراضية، ننشئ ملفًا جديدًا باسم app.py لتحريره ضمن المجلد flask_app على النحو التالي:

(env)user@localhost:$ nano app.py

سيستورد هذا الملف الصنف والمساعدات الضرورية من حزمة فلاسك ومن مكتبة PyMongo، إذ سنتخاطب مع خادم MongoDB بغية إنشاء قاعدة بيانات وتجميعة لتخزين المهام، لذلك سنكتب الشيفرات التالية ضمن الملف app.py:

from flask import Flask
from pymongo import MongoClient

app = Flask(__name__)

client = MongoClient('localhost', 27017)

db = client.flask_db
todos = db.todos

نحفظ الملف ونغلقه.

استوردنا في الشيفرة السابقة الصنف Flask الذي سنستخدمه في إنشاء نسخة فعلية من التطبيق باسم app، كما استوردنا الوحدة MongoClient التي سنستخدمها لإنشاء كائن عميل باسم client لنسخة قاعدة البيانات MongoDB، والذي يسمح لنا بالاتصال والتخاطب مع خادم MongoDB. عند استنساخ الدالة ()MongoClient فإننا نمرّر لها كل من اسم مضيف خادم MongoDB وهو في حالتنا الحاسوب نفسه localhost، ورقم المنفذ وهو هنا 27017.

ملاحظة: من الضروري اتباع إجراءات أمان صارمة لدى تثبيت MongoDB وذلك باتباع الخطوات الواردة في المقال كيفية تثبيت وتأمين MongoDB على أوبونتو 18.04، وبمجرد تأمينها يمكنك البدء بضبط إعداداتها للتعامل مع الاتصالات عن بعد. بمجرّد تمكين خاصية الاستيثاق في MongoDB، سيتوجّب علينا لدى إنشاء نسخة من دالة ()MongoClient بتمرير معاملين إضافيين لاسم المستخدم وكلمة المرور، وهما: username و password على النحو التالي:

client = MongoClient('localhost', 27017, username='username', password='password')

ثمّ استخدمنا في الشيفرة نسخة كائن العميل client لإنشاء قاعدة بيانات MongoDB باسم flask_db، وحفظ مرجع لها ضمن متغير باسم db.

بعدها أنشأنا تجميعة باسم todos ضمن قاعدة البيانات flask_db باستخدام المتغير db، إذ تُعد التجميعات مسؤولة عن تخزين مجموعة من المستندات في قاعدة البيانات MongoDB على غرار مبدأ الجداول في قواعد البيانات العلاقية.

نلاحظ إنشاء كل من قواعد البيانات والتجميعات في MongoDB اعتماديًا، بمعنى أنّه حتى لو جرى تنفيذ الملف app.py، فلن تُنفّذ أي من الشيفرات الخاصة بقاعدة البيانات فعليًا إلى أن يُنشَأ المستند الأول.

سننشئ في الخطوة التالية تطبيق فلاسك مُصغّر يحتوي على صفحة تمكّن المستخدمين من إدخال مستندات مهامهم ضمن التجميعة المسماة todos، حيث سيُنشأ ملف قاعدة البيانات flask_db والتجميعة todos ضمن خادم MongoDB بمجرّد إضافة أوّل مستند مهام.

وللحصول على قائمة بقواعد البيانات الموجودة حاليًا، نفتح نافذة طرفية terminal جديدة ونشغّل صدفة mongo باستخدام الأمر التالي:

(env)user@localhost:$ mongo

فتظهر نافذة موجه أوامر، سنستخدم فيها الأمر التالي للتحقّق من قواعد البيانات الموجودة:

> show dbs

وفي حال كون MongoDB مُثبّتة حديثًا فلن يظهر ضمن القائمة في الخرج سوى قواعد البيانات admin و config و local، كما نلاحظ عدم ظهور قاعدة البيانات flask_db في هذه المرحلة.

أمّا الآن فسنترك صدفة mongo قيد التشغيل ضمن نافذة الطرفية وننتقل إلى الخطوة التالية.

الخطوة 3 - إنشاء صفحة ويب لإضافة واستعراض المهام

سنعمل في هذه الخطوة على إنشاء صفحة ويب تسمح للمستخدمين بإضافة المهام واستعراضها ضمن نفس الصفحة.

لذا، سننشئ ملفًا باسم app.py لتحريره وذلك أثناء كون البيئة البرمجية مُفعّلة، كما يلي:

(env)user@localhost:$ nano app.py

وفيه سنضيف بدايةً الاستدعاءات التالية من حزمة فلاسك:

from flask import Flask, render_template, request, url_for, redirect
from pymongo import MongoClient

# ...

استدعينا في الشيفرة السابقة الدالة المساعدة ()render_template والتي سنستخدمها في تصيير قالب HTML، كما استدعينا الكائن request لاستخدامه في الوصول إلى البيانات التي سيرسلها المستخدم عبر التطبيق؛ أما الدالة ()url_for فستنشئ عناوين URLs، وستعيد الدالة ()redirect توجيه المستخدم إلى صفحة التطبيق الرئيسية بعد إضافته مهمّةً جديدة.

والآن سنضيف الوجهة التالية إلى نهاية الملف app.py، على النحو التالي:

# ...


@app.route('/', methods=('GET', 'POST'))
def index():
    return render_template('index.html')

نحفظ الملف ونغلقه.

نمرّر في هذه الوجهة متغير صف tuple يحتوي على القيم ('GET', 'POST') إلى المعامل methods بغية السماح بكلا نوعي طلبيات HTTP وهما GET و POST؛ إذ تتخصّص الطلبيات من النوع GET بجلب البيانات من الخادم؛ أمّا الطلبيات من النوع POST فهي مُتخصّصة بإرسال البيانات إلى وجهة مُحدّدة، مع ملاحظة أنّ الطلبيات من النوع GET هي الوحيدة المسموحة افتراضيًا، وحالما يطلب المستخدم الوجهة / باستخدام طلبية من النوع GET، سيُصيّر ملف قالب باسم index.html.

سنعدّل هذه الوجهة لاحقًا لتتعامل أيضًا مع الطلبيات من نوع POST اللازمة لدى ملء المُستخدمين نموذج الويب وإرساله بغية إنشاء مهام جديدة، ثمّ سننشئ مجلدًا للقوالب ضمن المجلد flask_app، وسنفتح ضمنه ملف القالب index.html كما يلي:

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/index.html

وسنكتب الشيفرة التالية ضمن ملف القالب index.html:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">FlaskApp</span><span class="tag">
    


    FlaskTODO
    
     class="content">
     method="post">
        
             for="content">Todo content
        
        
             type="text" name="content"
                placeholder="Todo Content">
        

        
             for="degree">Degree
        
        
             id="degree-0" name="degree" required type="radio" value="Important">
             for="degree-0">Important
        
        
             id="degree-1" name="degree" required type="radio" value="Unimportant">
             for="degree-1">Unimportant
        
         type="submit">Submit

نحفظ الملف ونغلقه.

وبذلك أصبح لدينا صفحة HTML أساسية تحتوي على عنوان وبعض التنسيقات وترويسة ونموذج ويب، إذ ضبطنا الخاصية method في نموذج الويب لتكون post للدلالة على كون نموذج الويب سيرسل إلى الخادم طلبيات من النوع POST، كما أضفنا إلى نموذج الويب هذا حقل إدخال نصي باسم content، وهو مُخصّص لإدخال محتوى المهمّة، والذي سنستخدمه لاحقًا للوصول إلى بيانات العنوان في الوجهة /، كما أضفنا للنموذج زري انتقاء باسم degree ليحدّد من خلالهما المستخدم درجة أهمية كل عنصر مهام، بحيث يمكّنه من انتقاء خيار أهمية المهمّة عند إنشائها (مهمة Important أو غير مهمة Unimportant)، وأضفنا في نهاية النموذج زر أوامر Submit لتأكيد النموذج وإرساله.

سنعلم بعد ذلك فلاسك بموقع التطبيق (وهو الملف app.py في هذه الحالة) باستخدام متغير البيئة FLASK_APP وذلك أثناء وجودنا ضمن المجلد flask_app ومع تفعيل البيئة الافتراضية، كما سنضبط متغير البيئة FLASK_ENV المسؤول عن تحديد وضع التشغيل، وهنا قد اخترنا الوضع development ما يعني أنّ التطبيق سيعمل في وضع التطوير مع تشغيل مُنقّح الأخطاء. لمزيدٍ من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

والآن سنشغّل التطبيق باستخدام الأمر flask run:

(env)user@localhost:$ flask run

ملاحظة:لدى محاولة تشغيل التطبيق قد تظهر لك الرسالة 'ModuleNotFoundError: No module named 'pymongo والتي تفيد بعدم وجود وحدة باسم pymongo، ولإصلاح هذا الخطأ ما عليك سوى إلغاء تفعيل البيئة الافتراضية وإعادة تفعيلها مجدّدًا، وبعدها أعد تشغيل الأمر flask run من جديد.

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

http://127.0.0.1:5000/

فستظهر لك الصفحة الرئيسية للتطبيق متضمّنةً حقلًا لإدخال محتوى المهمّة وزريّ انتقاء لاختيار درجة الأهمية وزر أوامر لإرسال النموذج، كما في الشكل أدناه:

ولمزيدٍ من المعلومات المتقدمة ولتتعرّف على كيفية إدارة نماذج الويب بأمان ننصحك بقراءة مقال استخدام والتحقق من نماذج الويب ذات واجهة المستخدم التفاعلية في فلاسك باستخدام الإضافة Flask-WTF.

يرسل نموذج الإدخال هذا طلبًا من النوع POST إلى الخادم، ولكن حتى هذه اللحظة لا توجد شيفرة مسؤولة عن معالجة هذا الطلب في الوجهة /، وبالتالي لن يحدث شيء في حال ملء النموذج الآن وإرساله.

نفتح نافذة طرفية جديدة أثناء تشغيل الخادم، ثمّ نفتح الملف app.py لتعديله ليتعامل مع الطلبات من النوع POST المُرسلة من قبل المستخدم، بحيث يرسلها إلى تجميعة تخزين المهام ليعرضها ضمن صفحة التطبيق الرئيسية:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة / لتصبح كما يلي:

@app.route('/', methods=('GET', 'POST'))
def index():
    if request.method=='POST':
        content = request.form['content']
        degree = request.form['degree']
        todos.insert_one({'content': content, 'degree': degree})
        return redirect(url_for('index'))

    all_todos = todos.find()
    return render_template('index.html', todos=all_todos)

احفظ الملف واغلقه.

وبعد هذه التغييرات، سيجري التعامل مع الطلبيات من النوع POST باستخدام العبارة الشرطية 'if request.method == 'POST، ففي حال تحقق الشرط سيُستخرج من الكائن request.form كلًا من محتوى المهمّة ودرجة الأهمية التي أرسلها المستخدم.

استخدمنا التابع ()insert_one على تجميعة المهام بغية إضافة مستند مهام إليها، كما وفرّنا بيانات المهمة ضمن قاموس بايثون عبر ضبط قيمة المفتاح المسمّى 'content' لتساوي القيمة التي أدخلها المستخدم أصلًا ضمن الحقل النصي المُخصّص لمحتوى المهمّة في النموذج، كما ضبطنا قيمة المفتاح المسمّى 'degree' لتساوي قيمة زر الانتقاء الذي اختاره المُستخدم. بعد ذلك، نعيد توجيه المُستخدم إلى الصفحة الرئيسية للتطبيق، إذ تُحدَّث هذه الصفحة لتعرض عنصر المهام الجديد المضاف.

استخدمنا التابع ()find بغية عرض المهام المحفوظة خارج الجزء المسؤول عن التعامل مع الطلبيات من النوع POST من الشيفرة، والذي يعيد كافّة مستندات المهام المتوفرّة ضمن التجميعة todos، إذ تُحفظ المهام المُستخرجة من قاعدة البيانات ضمن متغير باسم all_todos، ثمّ عدلنا استدعاء التابع ()render_template بحيث يمرر قائمة مستندات المهام إلى ملف القالب index.html، والتي ستتواجد ضمن هذا القالب في متغير باسم todos.

إذا حدّثت الصفحة الرئيسية للتطبيق، سيعرض المتصفح رسالة يطلب فيها تأكيد إعادة إرسال النموذج، وفي حال التأكيد سيُضاف عنصر المهام الذي حاولنا إرساله قبل إضافة الشيفرة المسؤولة عن التعامل مع الطلبيات من النوع POST إلى قاعدة البيانات، وذلك نظرًا لكون الشيفرة اللازمة للتعامل مع الطلبيات POST أصبحت متوفرّةً في الوجهة، ولكن بما أنّنا لم نضف حتى الآن شيفرة خاصّة بعرض عناصر المهام، فلن يظهر العنصر الذي أضفناه، ومن الممكن رؤية العنصر الأخير المُضاف عبر فتح صدفة mongo والاتصال مع قاعدة البيانات flask_db باستخدام الأمر التالي:

> use flask_db

سنستخدم بعد ذلك الدالة ()find لجلب كافّة عناصر المهام الموجودة في قاعدة البيانات:

> db.todos.find()

ففي حال إرسال أي بيانات ستظهر في الخرج هنا.

الآن، سنفتح ملف القالب index.html لتعديله بغية عرض محتويات قائمة المهام todos التي مررناها مُسبقًا إليه، على النحو التالي:

(env)user@localhost:$ nano templates/index.html

نعدّل الملف بإضافة وسم فاصل أفقي

وحلقة تكرارية for من تعليمات جينجا jinja وذلك بعد الجزء الخاص بالنموذج، بحيث يصبح الملف كما يلي:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">FlaskApp</span><span class="tag">
    


    FlaskTODO
    
     class="content">
     method="post">
        
             for="content">Todo content
        
        
             type="text" name="content"
                placeholder="Todo Content">
        

        
             for="degree">Degree
        
        
             id="degree-0" name="degree" required type="radio" value="Important">
             for="degree-0">Important
        
        
             id="degree-1" name="degree" required type="radio" value="Unimportant">
             for="degree-1">Unimportant
        
         type="submit">Submit
    
    
    {% for todo in todos %}
         class="todo">
            {{ todo['content'] }} ({{ todo['degree']}})
        
    {% endfor %}

نحفظ الملف ونغلقه.

أضفنا في الملف السابق وسم الفاصل الأفقي

بغية فضل نموذج الويب عن قائمة المهام المعروضة، كما استخدمنا حلقة for التكرارية ضمن السطر البرمجي الآتي:

{% for todo in todos %}

بغية المرور على كافة عناصر المهام في قائمة todos، لتُعرض محتويات المهمّة ودرجة أهميتها ضمن وسم فقرة

بتحديث صفحة التطبيق الرئيسية وملء النموذج وإرساله، ستظهر المهمّة الجديدة المُضافة أسفل النموذج، أمّا في الخطوة التالية فسنعمل على إضافة زر أوامر يتيح للمستخدم إمكانية حذف إحدى المهام الموجودة أصلًا.

الخطوة 4 - حذف مهام

سنعمل في هذه الخطوة على إضافة وجهة تمكّن المستخدمين من حذف المهام باستخدام زر أوامر مُخصّص لهذا الغرض.

بدايةً، سنضيف وجهةً جديدةً للحذف، وهي ‎/id/delete تتعامل مع الطلبات من النوع POST، إذ ستستقبل دالة الحذف الجديدة delete()‎ رقم معرّف التدوينة ID المراد حذفها من خلال الرابط URL لتستخدم هذا المعرّف لحذف المهمّة الموافقة.

لحذف مهمة ما، سنجلب بدايةً معرّفها مثل سلسلة نصية والتي لا بُدّ من تحويلها إلى النوع ObjectId (نمط البيانات BSON وهو التمثيل الثنائي للنمط JSON) قبل تمريره إلى تابع الحذف من التجميعة، لذا يجب استيراد الصنف ()ObjectId من الوحدة bson، وهي المسؤولة عن التعامل مع ترميز وفك ترميز نمط البيانات BSON (أي JSON الثنائي).

الآن، سنفتح الملف app.py لتحريره:

(env)user@localhost:$ nano app.py

وبدايةً سنضيف الاستدعاء التالي إلى بداية الملف، على النحو التالي:

from bson.objectid import ObjectId

# ...

استُدعي الصنف ()ObjectId لاستخدامه في تحويل المعرفات IDs إلى كائنات من النوع ObjectId.

سنضيف الآن الوجهة التالية إلى نهاية الملف app.py:

# ...


@app.post('//delete/')
def delete(id):
    todos.delete_one({"_id": ObjectId(id)})
    return redirect(url_for('index'))

نحفظ الملف ونغلقه.

استخدمنا في الشيفرة السابقة المزخرف app.post المُقدّم في الإصدار 2.0.0 من فلاسك بدلًا من استخدام المزخرف app.route المعتاد، والذي أضاف اختصارات للعديد من توابع HTTP الشائعة، فعلى سبيل المثال الأمر ("app.post("/login@ هو اختصار للأمر:

@app.route("/login", methods=["POST"])

ما يعني أن دالة العرض هذه تتعامل فقط مع طلبيات من النوع POST، وبزيارة الوجهة ‎/ID/delete في المتصفّح سيظهر الخطأ ‎405 Method Not Allowed لأن المتصفحات تستخدم طريقة GET افتراضيًا للطلبات. لذلك، بغية حذف مهمة ما، سنضيف زر أوامر عندما يضغط المستخدم عليه، تُرسَل إلى الوجهة طلبية من النوع POST.

تستقبل الدالة معرّف مستند المهمّة المراد حذفها، ليُمرّر إلى التابع ()delete_one المُطبّق على التجميعة todos، ليُحوّل المعرّف المُستقبل من نوع سلسلة نصية إلى كائن من النوع ObjectId باستخدام الصنف ()ObjectId المستورد سابقًا.

وبعد حذف مستند المهمة، نعيد توجيه المستخدم إلى الصفحة الرئيسية للتطبيق، أمّا الآن فسنعمل على تحرير ملف القالب index.html لإضافة زر الأوامر الخاص بحذف المهام، على النحو التالي:

(env)user@localhost:$ nano templates/index.html

سنعدّل حلقة for التكرارية بإضافة وسم نموذج

جديد، كما يلي:

{% for todo in todos %}
        <div class="todo">
            <p>{{ todo['content'] }} <i>({{ todo['degree']}})i>p>
            <form method="POST" action="{{ url_for('delete', id=todo['_id']) }}" >
                <input type="submit" value="Delete Todo"
                       onclick="return confirm('Are you sure you want to delete this entry?')">
            form>
        div>
    {% endfor %}

نحفظ الملف ونغلقه.

وبذلك يكون لدينا نموذج ويب يُرسل طلبيةً من النوع POST إلى دالة العرض ()delete، إذ مررنا المعامل ['todo['_id لتحديد المهمّة المطلوب حذفها، كما استخدمنا التابع ()confirm المتوفّر في متصفّح الويب لعرض رسالة تأكيد قبل إرسال الطلب.

الآن، بعد تحديث الصفحة الرئيسية للتطبيق، سيظهر زر أوامر لحذف المهمة أسفل كل عنصر مهام، وعند النقر عليه ستظهر رسالة لتأكيد عملية الحذف، ومن ثمّ سيعيد التطبيق التوجيه إلى صفحته الرئيسية فنلاحظ حذف المهمة فعلًا.

وبذلك أصبح تطبيق فلاسك يوفّر طريقةً لحذف المهام غير المرغوبة من قاعدة البيانات mongoDB.

ولتأكيد الحذف، نفتح صدفة mongo ونستخدم الدالة ()find على النحو التالي:

> db.todos.find()

وعندها سنلاحظ أنّ العناصر المحذوفة لم تعد موجودةً في التجميعة todos.

الخاتمة

أنشأنا في هذا المقال تطبيق ويب في فلاسك لإدارة المهام، إذ يتخاطب هذا التطبيق مع قاعدة بيانات MongoDB، وتعرفنا على كيفية الاتصال مع خادم قاعدة البيانات MongoDB، وأنشأنا تجميعات تُخزّن مجموعة من المستندات، واستعرضنا كيفية إدخال البيانات إلى تجميعة وجلبها أو حذفها منها.

ترجمة -وبتصرف- للمقال How To Use MongoDB in a Flask Application لصاحبه Abdelhadi Dyouri.

استخدام قاعدة بيانات PostgreSQL في تطبيق فلاسك

Tue, 24 Jan 2023 16:02:00 +0000

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

أمّا PostgreSQL أو Postgres فهو نظام لإدارة قواعد البيانات العلاقية، ويوفّر تطبيقًا للغة الاستعلامات SQL، ومتوافق مع معاييرها، ناهيك عن امتلاكه العديد من الميزات المتطورة من عمليات موثوقة وتحكّم متزامن مُتعدّد النسخ دون قيود على قراءة البيانات من القاعدة.

سنعمل في هذا المقال على بناء تطبيق ويب مُصغّر لتقييم الكتب والذي سنوضّح من خلاله كيفية استخدام المكتبة psycopg2 ومحوّل قاعدة بيانات PostgreSQL، الذي يسمح لنا بالتخاطب والتفاعل مع قاعدة بيانات PostgreSQL باستخدام لغة بايثون، إذ سنبني التطبيق باستخدام إطار العمل فلاسك ليؤدّي بعض المهام الأساسية من اتصال بخادم قاعدة البيانات وإنشاء الجداول وإدخال بيانات في جدول، إضافةً إلى جلب بيانات من جدول.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بُدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض والقوالب، وفي هذا الصدد يمكنك الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.
توفّر PostgreSQL مثبت على حاسوبك مع وصول إلى نافذة أسطر الأوامر الخاصة به.

الخطوة 1 - إنشاء كل من قاعدة بيانات ومستخدم PostgreSQL

سنعمل في هذه الخطوة على إنشاء قاعدة بيانات باسم "flask_db" ومستخدم لها باسم user وذلك لاستخدامهما لاحقًا في تطبيق فلاسك المراد إنشاؤه.

يُنشأ خلال تثبيت postgres مستخدم بصلاحيات على مستوى نظام التشغيل باسم postgres ليتوافق مع حساب المستخدم المسؤول كامل الصلاحيات postgres الخاص بنظام PostgreSQL، إذ سنستخدم هذا الحساب في المهام التي تتطلّب صلاحيات مسؤول، فحينها سنستخدم الأمر sudo ممرّرين بعده اسم المستخدم مع استخدام الخيار iu-.

لذا، سجّل دخولك الآن إلى جلسة عمل تفاعلية في Postgres مُستخدمًا الأمر التالي:

user@localhost:$ sudo -iu postgres psql

فستظهر لك طرفية PostgreSQL والتي من الممكن إعداد المتطلبات من خلالها.

بدايةً، سننشئ قاعدة بيانات لمشروعنا:

postgres=# CREATE DATABASE flask_db;

ملاحظة: يجب أن تنتهي كل تعليمة من تعليمات Postgres بفاصلة منقوطة، ففي حال ظهور أي أخطاء، تأكّد من انتهاء كل سطر برمجي بفاصلة منقوطة.

ومن ثمّ سننشئ حساب مستخدم لقاعدة البيانات، وهنا لا بدّ من اختيار كلمة مرور آمنة:

postgres=# CREATE USER user WITH PASSWORD 'password';

والآن سنعطي هذا المستخدم صلاحيات المسؤول على قاعدة البيانات:

postgres=# GRANT ALL PRIVILEGES ON DATABASE flask_db TO sammy;

وللتأكّد من إتمام إنشاء قاعدة البيانات، نكتب الأمر التالي المسؤول عن إظهار قائمة بقواعد البيانات المُنشأة:

postgres=# \l

فستظهر قاعدة البيانات المسماة "flask_db" ضمن القائمة السابقة.

وعند الانتهاء نغلق نافذة طرفية PstgreSQL باستخدام الأمر:

postgres=# \q

ومع نهاية هذه الخطوة نكون قد أعددنا sPostgre وأصبح من الممكن الاتصال وإدارة المعلومات المخزّنة في قواعد بياناته باستخدام لغة بايثون معتمدين على المكتبة psycopg2، أمّا في الخطوة التالية فسنعمل على تثبيت هذه المكتبة جنبًا إلى جنب مع حزمة فلاسك.

الخطوة 2 - تثبيت فلاسك ومكتبة psycopg2

سنعمل في هذه الخطوة على تثبيت كل من فلاسك ومكتبة psycopg2 مما يمكننا من التخاطب مع قاعدة البيانات باستخدام لغة بايثون.

لذا، وبعد التأكّد من كون البيئة الافتراضية مُفعّلة، نستخدم أمر تثبيت الحزم pip لتثبيت كل من فلاسك ومكتبة psycopg2 على النحو التالي:

(env)user@localhost:$ pip install Flask psycopg2-binary

وبمجرّد انتهاء التثبيت بنجاح، سيظهر في نهاية الخرج سطر شبيه بما يلي مؤكدًا نجاح العملية:

Successfully installed Flask-2.0.2 Jinja2-3.0.3 MarkupSafe-2.0.1 Werkzeug-2.0.2 click-8.0.3 itsdangerous-2.0.1 psycopg2-binary-2.9.2

مع انتهاء هذه الخطوة، نكون قد ثبتنا كافّة الحزم اللازمة في البيئة الافتراضية، وسنعمل في الخطوة التالية على إعداد قاعدة البيانات والاتصال بها.

الخطوة 3 - إعداد قاعدة بيانات

سننشئ في هذه الخطوة -ضمن مجلد المشروع المسمّى "flask_app"- ملف بايثون وظيفته الاتصال مع قاعدة البيانات "flask_db"، كما سننشئ ضمن قاعدة البيانات هذه جدولًا لتخزين الكتب، وسندخل ضمنه يدويًا بعض الكتب مع نبذة عن كل منها.

الآن وبعد التأكّد من كون البيئة الافتراضية مُفعّلة، نفتح ملفًا جديدًا باسم "init_db.py" ضمن المجلد "flask_app" على النحو التالي:

(env)user@localhost:$ nano init_db.py

سيفتح هذا الملف الاتصال مع قاعدة البيانات "flask_db"، مُنشئًا فيها جدولًا للكتب باسم "books"، مالئًا إياه ببيانات تجريبية، ولإنجاز ذلك نكتب الشيفرة التالية ضمن الملف "init_db.py":

import os
import psycopg2

conn = psycopg2.connect(
        host="localhost",
        database="flask_db",
        user=os.environ['DB_USERNAME'],
        password=os.environ['DB_PASSWORD'])

# Open a cursor to perform database operations
cur = conn.cursor()

# Execute a command: this creates a new table
cur.execute('DROP TABLE IF EXISTS books;')
cur.execute('CREATE TABLE books (id serial PRIMARY KEY,'
                                 'title varchar (150) NOT NULL,'
                                 'author varchar (50) NOT NULL,'
                                 'pages_num integer NOT NULL,'
                                 'review text,'
                                 'date_added date DEFAULT CURRENT_TIMESTAMP);'
                                 )

# Insert data into the table

cur.execute('INSERT INTO books (title, author, pages_num, review)'
            'VALUES (%s, %s, %s, %s)',
            ('A Tale of Two Cities',
             'Charles Dickens',
             489,
             'A great classic!')
            )


cur.execute('INSERT INTO books (title, author, pages_num, review)'
            'VALUES (%s, %s, %s, %s)',
            ('Anna Karenina',
             'Leo Tolstoy',
             864,
             'Another great classic!')
            )

conn.commit()

cur.close()
conn.close()

نحفظ الملف ونغلقه.

استوردنا في الشيفرة السابقة الوحدة os المُستخدمة في الوصول إلى متغيرات البيئة التي خزّنا فيها سابقًا كل من اسم المستخدم وكلمة المرور الخاصين بقاعدة البيانات، وهذا يضمن عدم ظهورهما ضمن الشيفرة المصدرية.

كما استوردنا المكتبة psycopg2، ومن ثمّ فتحنا اتصالًا مع قاعدة البيانات flask_db باستخدام الدالة ()psycopg2.connect، وفيها حددنا المضيف وهو الحاسوب المحلي في حالتنا، كما مرّرنا اسم قاعدة البيانات إلى المُعامل database.

وقد وفرّنا كل من اسم المستخدم وكلمة المرور اللازمين للدخول إلى قاعدة البيانات باستخدام الكائن os.environ الذي يُمكنّنا من الوصول إلى متغيرات البيئة التي أعددناها سابقًا ضمن البيئة البرمجية، ليُخزّن اسم المستخدم ضمن متغير بيئة باسم DB_USERNAME وكلمة المرور ضمن متغير بيئة باسم DB_PASSWORD، وبهذا نكون قد خزّنا كل من اسم المستخدم وكلمة المرور خارج الشيفرة المصدرية، ما يضمن أمان هذه المعلومات الحساسة ويمنع كشفها لدى حفظ نسخة من الشيفرة المصدرية في المتحكّم المركزي، أو لدى رفعها على خادم عامل على شبكة الإنترنت.

كما أنشأنا مؤشر cur باستخدام التابع ()connection.cursor، الذي يمكّن شيفرات بايثون من تنفيذ أوامر PostgreSQL خلال جلسات عمل قاعدة البيانات.

استخدمنا تابع المؤشر ()execute لحذف أي جداول موجودةٍ مسبقًا باسم "books" في حال وجودها، وذلك لتجنُّب أي تضاربٍ، أو نتائج عشوائية ناتجةٍ عن تشابه أسماء الجداول (مثل حالة وجود جدولين بنفس الاسم وبأعمدة مُختلفة في قاعدة البيانات)، ولكن وفي حالتنا الآن وكوننا لم ننشئ أي جداول بعد، فلن يُنفَّذ هذا السطر في الوقت الراهن، ومن الجدير بالملاحظة أنّ هذا الأمر سيحذِف كل المحتويات في قاعدة البيانات في كل مرة تشغِّل فيها الملف "init_db.py"، ولكن في حالة مثالنا سننفذ هذا الملف لمرّة واحدة فقط لتهيئة قاعدة البيانات، إلّا أنّك قد ترغب مُستقبلًا بتنفيذه مُجدّدًا بغية تفريغ قاعدة البيانات من كافّة محتوياتها والبدء من جديد بقاعدة بيانات فارغة.

ثمّ استخدمنا الأمر CREATE TABLE books لإنشاء جدول للكتب ضمن قاعدة البيانات باسم books يحتوي على الأعمدة التالية:

'id': يحتوي على بياناتٍ من نمط رقم تسلسلي serial، أي أعداد صحيحة متزايدة تلقائيًا، ويمثّل هذا العمود مفتاحًا أساسيًا والذي قد حدّدناه باستخدام الكلمات المفتاحية PRIMARY KEY. وستُخصّص قاعدة البيانات قيمة فريدة لهذا المفتاح من أجل كل سجل مُدخل (والسجل هو الكتاب في حالتنا).
"title": يمثّل عنوان الكتاب، ويحتوي على بيانات من النوع varchar، وهو نوع بيانات يحتوي على محارف بطول معين، وفي حالتنا (varchar (150 تعني أنّ عدد المحارف المتاحة للعنوان هي حتى 150 محرف، أمّا التعليمة NOT NULL فتعني أنّه من غير المسموح ترك هذا العمود فارغًا.
author: يحتوي على اسم مؤلف الكتاب، على ألّا يتجاوز 50 محرف، أمّا التعليمة NOT NULL فتعني أنّه من غير المسموح ترك هذا العمود فارغًا.
pages_num: يحتوي على عدد صحيح يمثّل عدد صفحات الكتاب، وتعني التعليمة NOT NULL أنّه من غير المسموح ترك هذا العمود فارغًا.
review: يحتوي على نبذة عن الكتاب، وبياناته من النوع text، ما يعني أنّ محتويات هذا العمود هي سلاسل نصية بأي طول.
'date_added': يحتوي على تاريخ إضافة الكتاب إلى الجدول، والقيمة DEFAULT تعني ضبط القيمة الافتراضية إلى CURRENT_TIMESTAMP، التي تمثِّل وقت إضافة الكتاب إلى قاعدة البيانات، وكما هو الحال في عمود id، لا يتوجب عليك تحديد قيم لهذا العمود، إذ أنها تُملأ تلقائيًا.

بعد الانتهاء من إنشاء الجدول، استخدمنا تابع المؤشّر ()execute لإدخال كتابين في الجدول، الأول بعنوان "A Tale of Two Cities" للكاتب "Charles Dickens"، والثاني بعنوان "Anna Karenina" للمؤلف "Leo Tolstoy"، وقد استخدمنا الموضع المؤقت s% لتمرير القيم إلى تعليمات SQL، إذ تتعامل مكتبة psycopg2 مع عمليات الإدخال في الخلفية بطريقة تضمن الحماية من هجمات حقن تعليمات SQL.

بعد الانتهاء من إدخال بيانات الكتب إلى الجدول، استخدمنا التابع ()connection.commit لتأكيد العملية وتطبيق التغييرات على قاعدة البيانات، ونهايةً أغلقنا كل من المؤشر والاتصال باستخدام التابعين ()cur.close و ()conn.close على التوالي.

الآن، سنشغّل الأوامر التالية لتأسيس الاتصال مع قاعدة البيانات، وإعداد كل من متغيري البيئة DB_USERNAME و DB_PASSWORD، ولكن استخدم اسم المستخدم وكلمة المرور الخاصين بك:

(env)user@localhost:$ export DB_USERNAME="user"
(env)user@localhost:$ export DB_PASSWORD="password"

والآن، سنشغّل الملف "init_db.py" ضمن نافذة الطرفية باستخدام الأمر python كما يلي:

(env)user@localhost:$ python init_db.py

وفور انتهاء تنفيذ الملف بنجاح، سيُضاف جدول جديد باسم "books" إلى قاعدة البيانات "flask_db".

والآن سجّل الدخول إلى جلسة Postgres تفاعلية للتحقّق من الجدول الجديد المُسمّى "books"، على النحو التالي:

(env)user@localhost:$ sudo -iu postgres psql

نتصل مع قاعدة البيانات "flask_db" باستخدام الأمر c\:

postgres=# \c flask_db

سنستخدم الآن التعليمة SELECT للحصول على عناوين الكتب وأسماء مؤلفيها من جدول الكتب books على النحو التالي:

postgres=# SELECT title, author FROM books;

فيظهر الخرج كما يلي:

       title         |      author
----------------------+------------------
 A Tale of Two Cities | Charles Dickens
 Anna Karenina        | Leo Tolstoy

نُغلق الجلسة التفاعلية باستخدام الأمر q\.

سنعمل في الخطوة التالية على إنشاء تطبيق فلاسك مُصغّر، يتصل بقاعدة البيانات ليجلب منها نبذةً عن كلا الكتابين اللذين أدخلناهما سابقًا في قاعدة البيانات ليعرضهما في صفحته الرئيسية.

الخطوة 4 - عرض الكتب

سنعمل في هذه الخطوة على إنشاء تطبيق فلاسك ذو صفحة رئيسية مسؤولة عن عرض الكتب الموجودة في قاعدة البيانات بعد جلبها منها.

لذا وأثناء كون البيئة البرمجية مُفعّلة وبعد تثبيت فلاسك، سنفتح ملف "app.py" ضمن المجلد "flask_app" لتحريره:

(env)user@localhost:$ nano app.py

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

import os
import psycopg2
from flask import Flask, render_template

app = Flask(__name__)

def get_db_connection():
    conn = psycopg2.connect(host='localhost',
                            database='flask_db',
                            user=os.environ['DB_USERNAME'],
                            password=os.environ['DB_PASSWORD'])
    return conn


@app.route('/')
def index():
    conn = get_db_connection()
    cur = conn.cursor()
    cur.execute('SELECT * FROM books;')
    books = cur.fetchall()
    cur.close()
    conn.close()
    return render_template('index.html', books=books)

نحفظ الملف ونغلقه.

استوردنا بدايةً في الشيفرة السابقة كل من الوحدة os والمكتبة psycopg2 والصنف Flask ودالة تصيير القوالب ()render_template من حزمة فلاسك، كما أنشأنا نسخة من التطبيق باسم "app"، ثمّ عرفنا دالةً باسم ()get_db_connection لإنشاء اتصال مع قاعدة البيانات "flask_db" باستخدام اسم المستخدم وكلمة المرور المخزنيْن في متغيرات البيئة DB_USERNAME و DB_PASSWORD على التوالي، ويعيد التابع كائن الاتصال conn، الذي سنستخدمه للوصول إلى قاعدة البيانات.

استخدمنا بعد ذلك المُزخرف ()app.route لإنشاء وجهة رئيسية / ودالة عاملة في فلاسك باسم ()index، وفتحنا اتصالًا مع قاعدة البيانات باستخدام الدالة get_db_connection()‎، ثم أنشأنا مؤشرًا ونفذنا التعليمة ;SELECT * FROM books من تعليمات SQL بغية الحصول على كل الكتب الموجودة في قاعدة البيانات، إذ أنّنا نستدعي التابع fetchall()‎ لحفظ البيانات ضمن متغير باسم books، ومن ثم نغلق كل من المؤشر والاتصال مع قاعدة البيانات. ونهايةً نجعل القيمة المعادة استدعاءً للدالة ()render_template لإخراج ملف قالب باسم "index.html" ممررين له قائمة الكتب التي جلبناها من قاعدة البيانات إلى المتغير books.

الآن، وبغية عرض الكتب المُخزنة ضمن قاعدة البيانات في الصفحة الرئيسية للتطبيق، سننشئ بدايةً ملف قالب ليتضمّن كافة شيفرات HTML الأساسية اللازمة لتستخدمها لاحقًا القوالب الأُخرى، وهذا ما يجنبنا تكرار الشيفرات، ثمّ سننشئ ملف قالب الصفحة الرئيسية "index.html" المُصيّر أصلًا باستخدام الدالة ()index.

سننشئ مجلدًا للقوالب باسم "templates" وننشئ ضمنه ملف قالب باسم "base.html"، والذي سيمثّل القالب الأساسي لبقية القوالب على النحو التالي:

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html

وسنكتب ضمنه الشيفرة التالية:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %}- FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

احفظ الملف واغلقه.

يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي سنحتاجها في القوالب الأُخرى.

ستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن رابطين، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for لتحقيق الربط مع دالة العرض ()index، والآخر لصفحة المعلومات حول التطبيق About في حال قررت تضمينها في تطبيقك.

الآن، سنفتح ملف القالب باسم "index.html" وهو الاسم الذي حددناه في الملف "app.py":

(env)user@localhost:$ nano templates/index.html

ونضيف ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Books {% endblock %}h1>
    {% for book in books %}
        <div class='book'>
            <h3>#{{ book[0] }} - {{ book[1] }} BY {{ book[2] }}h3>
            <i><p>({{ book[3] }} pages)p>i>
            <p class='review'>{{ book[4] }}p>
            <i><p>Added {{ book[5] }}p>i>
        div>
    {% endfor %}
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب "base.html" من خلال تعليمة extends، واستبدلنا محتوى كتلة المحتوى content مُستخدمين تنسيق العنوان من المستوى الأوّل

الذي يفي أيضًا بالغرض مثل عنوان للصفحة.

استخدمنا في السطر البرمجي {% for book in books %} حلقة for من تعليمات محرّك القوالب جينجا jinja، والهدف من استخدام هذه الحلقة هو المرور على كل عنصر في القائمة books، إذ نظهر بدايةً رقم معرّف الكتاب ID والذي يمثّل العنصر الأوّل باستخدام الأمر [book[0، ثمّ نظهر كلًا من عنوان الكتاب واسم مؤلفه وعدد صفحاته والنبذة التعريفية عنه وتاريخ إضافته.

الآن ومع وجودنا ضمن المجلد flask_app ومع كون البيئة الافتراضية مُفعّلة، نُعلم فلاسك بالتطبيق المراد تشغيله (وهو في حالتنا الملف "app.py") باستخدام متغير البيئة FLASK_APP، ومن ثمّ نعيّن وضع التشغيل من خلال متغير البيئة FLASK_ENV واخترنا هنا العمل في وضع التطوير development، مع تشغيل مُنقّح الأخطاء. للمزيد من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك. لتنفيذ ما سبق سنشغّل الأوامر التالية:

(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development

وهنا لا بُدّ من التأكد من تعيين متغيرات البيئة DB_PASSWORD و DB_USERNAME في حال عدم إعدادها مُسبقًا:

(env)user@localhost:$ export DB_USERNAME="user"
(env)user@localhost:$ export DB_PASSWORD="password"

والآن سنشغّل التطبيق باستخدام الأمر التالي:

(env)user@localhost:$ flask run

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

http://127.0.0.1:5000/

وعندها ستظهر لك الكتب التي أضفتها بدايةً إلى قاعدة البيانات بالشّكل التالي:

ومع نهاية هذه الخطوة نكون قد تمكنّا من عرض الكتب المُخزنة ضمن قاعدة البيانات مُسبقًا في الصفحة الرئيسية للتطبيق، أمّا في الخطوة التالية فسنعمل على إضافة وجهة جديدة من شأنها السماح للمُستخدمين بإضافة كتب جديدة إلى قاعدة البيانات.

الخطوة 5 - إضافة كتب جديدة

سنعمل في هذه الخطوة على إضافة وجهة جديدة للسماح للمُستخدمين بإضافة كتب جديدة ونبذات عنها إلى قاعدة البيانات. لذلك، سنضيف للتطبيق صفحة جديدة تتضمّن نموذج ويب لإدخال كل من عنوان الكتاب واسم مؤلفه وعدد صفحاته ونبذة عنه من قبل المستخدم.

سنفتح نافذة طرفية جديدة مع بقاء خادم التطوير قيد التشغيل، ثمّ سنفتح الملف "app.py":

(env)user@localhost:$ nano app.py

للتعامل مع نموذج الويب، لا بُد أولًا من استيراد التالي من حزمة فلاسك:

الكائن request العام المسؤول عن الوصول إلى بيانات الطلب المُرسَل من قبل المُستخدم.
الدالة url_for()‎ لتوليد عناوين الروابط.
الدالة redirect()‎ لإعادة توجيه المستخدم إلى صفحة التطبيق الرئيسية بعد إضافة كتاب إلى قاعدة البيانات.

أضِف هذه الاستيرادات إلى السطر الأوّل من الملف "app.py" كما يلي:

from flask import Flask, render_template, request, url_for, redirect

# ...

ثمّ أضِف الوجهة التالية إلى نهايته:

# ...


@app.route('/create/', methods=('GET', 'POST'))
def create():
    return render_template('create.html')

نحفظ الملف ونغلقه.

مرّرنا في هذه الوجهة صفًا tuple، يحتوي على القيم ('GET', 'POST') إلى المعامل methods بغية السماح بكلا نوعي طلبات HTTP وهما GET و POST، إذ تتخصّص الطلبات من النوع GET بجلب البيانات من الخادم، أمّا الطلبات من النوع POST فهي مُتخصّصة بإرسال البيانات إلى وجهة مُحدّدة، مع ملاحظة أنّ الطلبات من النوع GET هي الوحيدة المسموحة افتراضيًا.

وحالما يطلب المستخدم الوجهة create/ باستخدام طلب من النوع GET، سيُصيّر ملف قالب باسم "create.html"، وسنعدّل هذه الوجهة لاحقًا لتتعامل أيضًا مع الطلبات POST اللازمة لدى ملء المُستخدمين للنماذج وإرسالها بغية إضافة كتب جديدة.

الآن، افتح ملف "create.html" الجديد داخل مجلد القوالب "templates" على النحو التالي:

(env)user@localhost:$ nano templates/create.html

واكتب ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Add a New Book {% endblock %}h1>
    <form method="post">
        <p>
            <label for="title">Titlelabel>
            <input type="text" name="title"
                   placeholder="Book title">
            input>
        p>

        <p>
            <label for="author">Authorlabel>
            <input type="text" name="author"
                   placeholder="Book author">
            input>
        p>

        <p>
            <label for="pages_num">Number of pageslabel>
            <input type="number" name="pages_num"
                   placeholder="Number of pages">
            input>
        p>
        <p>
        <label for="review">Reviewlabel>
        <br>
        <textarea name="review"
                  placeholder="Review"
                  rows="15"
                  cols="60"
                  >textarea>
        p>
        <p>
            <button type="submit">Submitbutton>
        p>
    form>
{% endblock %}

احفظ الملف واغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب "base.html" من خلال تعليمة extends، وعيّنا وسم ترويسة ليكون عنوانًا؛ واستخدمنا الوسم وضبطنا فيه السمة method التي تحدّد نوع طلب HTTP لتكون من النوع POST، ما يعني أنّ نموذج الويب هذا سيرسل طلبًا من النوع POST؛ كما أضفنا صندوقًا نصيًا باسم title لنستخدمه للوصول إلى بيانات عنوان الكتاب في الوجهة create/؛ وأضفنا صندوقًا نصيًا مخصصًا لاسم مؤلف الكتاب، وصندوق عددي مخصص لعدد صفحات الكتاب؛ كما أضفنا حقلًا نصيًا مُتعدّد الأسطر مُخصّص للنبذة حول الكتاب، ونهايةً أضفنا إلى نهاية النموذج زر Submit لتأكيد إرساله.

الآن، وأثناء خادم التطوير، استخدم المتصفح للانتقال إلى الوجهة ‎/create:

http://127.0.0.1:5000/create

فستظهر لك صفحة إضافة كتاب جديد مع صندوق نصي لإدخال عنوان الكتاب، وآخر لإدخال اسم مؤلفه، ومربع لإدخال عدد صفحاته وحقل نصي مُتعدّد الأسطر لإدخال نبذة حول الكتاب، وزر لتأكيد إرسال النموذج، كما في الشّكل التالي:

يرسل نموذج الإدخال هذا طلبًا من النوع "POST" إلى الخادم، ولكن حتى هذه اللحظة لا يوجد شيفرة مسؤولة عن معالجة هذا الطلب في الوجهة create/، وبالتالي لن يحدث شيء في حال ملء النموذج الآن وإرساله.

الآن، افتح الملف "app.py" لتعديله بحيث يتعامل مع الطلبات من النوع "POST" المُرسلة من قبل المستخدم:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة create/ لتصبح كما يلي:

# ...

@app.route('/create/', methods=('GET', 'POST'))
def create():
    if request.method == 'POST':
        title = request.form['title']
        author = request.form['author']
        pages_num = int(request.form['pages_num'])
        review = request.form['review']

        conn = get_db_connection()
        cur = conn.cursor()
        cur.execute('INSERT INTO books (title, author, pages_num, review)'
                    'VALUES (%s, %s, %s, %s)',
                    (title, author, pages_num, review))
        conn.commit()
        cur.close()
        conn.close()
        return redirect(url_for('index'))

    return render_template('create.html')

احفظ الملف واغلقه.

تَمكَّنا باستخدام العبارة الشرطية if request.method == 'POST' التي تقارن قيمة request.method مع القيمة POST من التحقُّق بأنّ التعليمات التالية لها لن تُنفّذ إلّا إذا كان الطلب الحالي هو فعلًا بطريقة POST، ومن ثمّ قرأنا قيم كل من عنوان الكتاب واسم مؤلفه وعدد صفحاته والنبذة المرسلة عنه من الكائن request.form الذي يمكِّننا من الوصول إلى بيانات نموذج الإدخال المُضمّنة في الطلب.

فتحنا بعد ذلك اتصالًا مع قاعدة البيانات باستخدام الدالة get_db_connection()‎، وأنشأنا مؤشرًا، ونفّذنا الأمر INSERT INTO من أوامر SQL باستخدام التابع ()execute لإدخال كل من عنوان الكتاب واسم مؤلفه وعدد صفحاته ونبذة عنه إلى جدول الكتب books في قاعدة البيانات وفق ما أُدخل أصلًا من قبل المُستخدم في النموذج.

نهايةً، حفظنا التغييرات باستخدام الدالة ()connection.commit، وأُغلق الاتصال مع قاعدة البيانات باستخدام الدالة ()connection.close، ثم أعدنا توجيه المًستخدم إلى الصفحة الرئيسية من التطبيق ليرى الكتاب الجديد المُضاف أسفل الكتب السابقة الموجودة أصلًا.

الآن وأثناء عمل خادم التطوير، استخدم المتصفح للانتقال إلى الوجهة ‎/create باستخدام الرابط:

http://127.0.0.1:5000/create

املأ النموذج بالبيانات التي تريد، وحال إرسال النموذج سيُعاد توجيهك إلى الصفحة الرئيسية للتطبيق لترى الكتاب الجديد فيها.

سنفتح الآن ملف القالب الأساسي base.html لإضافة رابط في شريط التصفّح للوصول إلى صفحة إضافة كتاب جديد:

(env)user@localhost:$ nano templates/base.html

ونعدّل الملف ليصبح كما يلي:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('create') }}">Create
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

أضفنا في الشيفرة السابقة وسم رابط جديد إلى شريط التصفُّح والذي يشير إلى صفحة إضافة كتاب جديد، إذ سيظهر الرابط الجديد بتحديث الصفحة الرئيسية للتطبيق ضمن شريط التصفُّح.

ومع نهاية هذه الخطوة أصبح لدينا صفحة ذات نموذج إدخال لإضافة نبذات عن كتب جديدة، ولمزيدٍ من المعلومات حول النماذج وكيفية جعلها آمنة، ننصحك بقراءة المقال استخدام والتحقق من نماذج الويب ذات واجهة المستخدم التفاعلية في فلاسك باستخدام الإضافة Flask-WTF والمقال كيفية استخدام نماذج الويب في تطبيقات فلاسك.

الخاتمة

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

ترجمة -وبتصرف- للمقال How To Use a PostgreSQL Database in a Flask Application لصاحبه Abdelhadi Dyouri.

استخدام قاعدة بيانات SQLite في تطبيق فلاسك

Fri, 20 Jan 2023 16:02:00 +0000

نحتاج عادةً إلى قاعدة بيانات في تطبيقات الويب، وهي مجموعةٌ مُنظمّةٌ من البيانات نستخدمها لتخزين وتنظيم البيانات الدائمة، موفّرةً لنا إمكانية استرجاع هذه البيانات وإدارتها بفعالية، إذ نحتاج مثلًا في تطبيق ما للتواصل الاجتماعي إلى قاعدة بيانات لتخزين بيانات المستخدم (من معلومات شخصية ومنشورات وتعليقات ومتابعين) بحيث نتمكّن من معالجة هذه البيانات بفعالية، إذ توفّر قاعدة البيانات إمكانية إضافة بيانات جديدة إليها، أو استرجاع بيانات مُخزّنة أصلًا، أو التعديل عليها، أو حذفها بكل مرونة وذلك اعتمادًا على المتطلبات والشروط والظروف المُختلفة؛ ففي تطبيق ويب ما قد تكون هذه المتطلبات مثلًا هي حالة مُستخدم يضيف منشورًا جديدًا، أو يحذف منشورًا سابقًا، أو يحذف حسابه مع كافّة منشوراته أو مع الإبقاء عليها، بمعنى أنّ طريقة معالجة البيانات تعتمد أولًا وأخيرًا على الميزات التي يتيحها التطبيق، فمثلًا قد لا ترغب بالسماح لمُستخدمي تطبيقك بإضافة منشورات غير معنونة.

أمّا SQLite فهو محّرك قواعد بيانات مفتوح المصدر، يمتاز ببساطته وسرعته ويُستخدم مع بايثون لتخزين بيانات التطبيق ومعالجتها، إذ يعمل مع بايثون بكفاءة، نظرًا لكون مكتبة بايثون المعيارية توفّر الوحدة sqlite3 المُختصّة بالتخاطب مع أي قاعدة بيانات SQLite دون الحاجة لتثبيت أي أدوات إضافية، فاستخدام قواعد بيانات SQLite تحديدًا مع بايثون يتطلّب كمًّا قليلًا من التثبيتات مقارنةً بمحركات قواعد البيانات الأُخرى.

سنعمل في هذا المقال على إنشاء تطبيق ويب مُصغّر لنبيّن من خلاله كيفية استخدام قواعد بيانات SQLite في فلاسك لإجراء عمليات المعالجة الأساسية للبيانات من إنشاء Create وقراءة Read وتحديث Update وحذف Delete، أو ما يسمّى اختصارًا CRUD، إذ سيكون تطبيق الويب مدونة تعرض التدوينات ضمن صفحتها الرئيسية متيحةً لمستخدميها إمكانية إنشاء وتعديل وحذف أي تدوينة.

مستلزمات العمل

قبل المتابعة في هذا المقال لا بُدّ من:

توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات ودوال العرض والقوالب، ويمكنك في هذا الصدد الاطلاع على المقالين كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون وكيفية استخدام القوالب في تطبيقات فلاسك Flask لفهم مبادئ فلاسك.
فهم أساسيات لغة HTML.
فهم أساسيات استخدام SQLite.

الخطوة الأولى - إعداد قاعدة البيانات

سنعمل في هذه الخطوة على إعداد قاعدة بيانات من النوع SQLite والتي سنخزّن فيها بيانات التطبيق (وهي التدوينات في حالة تطبيقنا)، ثم سنملؤها ببعض المُدخلات التجريبية، وسنستخدم الوحدة sqlite3 المتوفرة بسهولة في مكتبة بايثون المعيارية بغية التخاطب والتفاعل مع قاعدة البيانات.

بدايةً، وبما أنّ تخزين البيانات في SQLite يكون ضمن جداول وأعمدة، وكون بيانات تطبيقنا هي تدوينات، سننشئ جدولًا باسم "posts" يحتوي على كافّة الأعمدة اللازمة، إذ سننشئ ملفًا بلاحقة sql. يحتوي على أوامر SQL اللازمة لإنشاء الجدول "posts" وأعمدته اللازمة، ثم سنستخدم ملف تخطيط قاعدة البيانات هذا لإنشاء قاعدة البيانات.

لذا، افتح ملف تخطيط قاعدة البيانات المُسمى "schema.sql" الموجود في المجلد "flask_app":

$ nano schema.sql

واكتب تعليمات SQL التالية داخل هذا الملف:

DROP TABLE IF EXISTS posts;

CREATE TABLE posts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL,
    content TEXT NOT NULL
);

احفظ الملف واغلقه.

يعمل أوّل أمر من أوامر SQL -في ملف تخطيط قاعدة البيانات السابق- على حذف أي جداول موجودةٍ مسبقًا باسم "posts" لتجنُّب أي تضارب، أو نتائج عشوائية ناتجةٍ عن تشابه أسماء الجداول (مثل حالة وجود جدولين بنفس الاسم وبأعمدة مُختلفة في قاعدة البيانات)، ولكن وفي حالتنا الآن وكوننا لم ننشئ أي جداول بعد، فلن يُنفَّذ هذا السطر في الوقت الراهن، ومن الجدير بالملاحظة أنّ هذا الأمر سيحذِف كل المحتويات في قاعدة البيانات في كل مرة تُشغِّل فيها أوامر SQL هذه، ولكن في حالة مثالنا سننفذ هذا الملف لمرّة واحدة فقط، إلّا أنّك قد ترغب مُستقبلًا بتنفيذه مُجدّدًا بغية تفريغ قاعدة البيانات من كافّة محتوياتها والبدء من جديد بقاعدة بيانات فارغة.

بينما ينشئ الأمر الثاني من أوامر SQL وهو:

CREATE TABLE posts

جدولًا باسم "posts" له الأعمدة التالية:

'id': ويحتوي على بياناتٍ من نوع رقم صحيح ويمثّل مفتاحًا أساسيًا يحتوي على قيمةٍ فريدة في قاعدة البيانات من أجل كل سجل (والسجل هو التدوينة في حالتنا). أمّا الأمر AUTOINCREMENT فيعمل على زيادة قيمة المُعرّف "ID" للتدوينات تلقائيًا، بمعنى أنّ قيمة المعرّف ID للتدوينة الأولى ستكون "1"، وستكون للتدوينة المُضافة بعدها تلقائيًا "2"، وهكذا، وستحافظ كل تدوينة على رقم معرّفها حتى في حال حذف تدوينات سابقة أو لاحقة لها.
'created': يحتوي على تاريخ ووقت إنشاء التدوينة، وتشير NOT NULL إلى أن هذا العمود يجب ألا يحتوي على قيمٍ فارغة، أما القيمة الافتراضية فهي CURRENT_TIMESTAMP، والتي تمثِّل تاريخ ووقت إضافة التدوينة إلى قاعدة البيانات، وكما هو الحال في عمود id، لا يتوجب عليك تحديد قيم لهذا العمود، إذ أنها تُملأ تلقائيًا.
title: عنوان التدوينة.
content: محتوى التدوينة.

والآن سنستخدم ملف تخطيط قاعدة البيانات "schema.sql" لإنشاء قاعدة البيانات، لذا سنُنشئ ملف بايثون سيبني بدوره ملف قاعدة بيانات SQLite بلاحقة db. اعتمادًا على الملف schema.sql.

افتح الملف "init_db.py" ضمن المجلد "flask_app" لتحريره (باستخدام محرِّر النصوص المفضل لديك، وهو محرر نانو nano هنا):

$ nano init_db.py

ثم اكتب ضمنه الشيفرة التالية:

import sqlite3

connection = sqlite3.connect('database.db')


with open('schema.sql') as f:
    connection.executescript(f.read())

cur = connection.cursor()

cur.execute("INSERT INTO posts (title, content) VALUES (?, ?)",
            ('First Post', 'Content for the first post')
            )

cur.execute("INSERT INTO posts (title, content) VALUES (?, ?)",
            ('Second Post', 'Content for the second post')
            )

connection.commit()
connection.close()

استوردنا في الشيفرة السابقة وحدة sqlite3، ثم أنشأنا اتصالًا مع ملف قاعدة بيانات باسم "database.db"، والذي يُنشأ تلقائيًا فور تشغيل ملف بايثون هذا، ومن ثم استخدمنا الدالة ()open لفتح الملف schema.sql، ثم نفّذنا باستخدام التابع ()executescript محتويات هذا الملف، الذي ينفِّذ عدة عبارات SQL معًا، وهكذا يُنشأ الجدول "posts"، كما استخدمنا كائن المؤشر Cursor، الذي يمكِّننا من معالجة السجلات، وفي حالتنا استخدمنا تابعه ()execute لتنفيذ تعليمتي إدخال INSERT في SQL لإضافة تدوينتين معًا إلى جدول التدوينات "posts"، وفي النهاية أُرسلت هذه الأوامر إلى قاعدة البيانات وأُغلِق الاتصال المفتوح معها.

اِحفظ الملف وأغلقه، ثم شغِّله من موجّه الأوامر باستخدام أمر بايثون التالي:

$ python init_db.py

وحالما ينتهي التنفيذ، سيكون لديك ملفٌ جديدٌ باسم "database.db" ضمن مجلد "flask_app"، وهذا يدل على نجاح عملية إعداد قاعدة البيانات. سنعمل في الخطوة التالية على إنشاء تطبيق فلاسك مُصغّر لقراءة التدوينات المُضافة إلى قاعدة البيانات وعرضها في صفحته الرئيسية.

الخطوة 2 – عرض كل التدوينات

سنعمل في هذه الخطوة على إنشاء تطبيق فلاسك ذو صفحة رئيسية مسؤولة عن عرض التدوينات الموجودة في قاعدة البيانات. بعد تفعيل البيئة البرمجية وتثبيت فلاسك، سنفتح ملفًا باسم "app.py" ضمن المجلد "flask_app" لتحريره:

(env)user@localhost:$ nano app.py

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

import sqlite3
from flask import Flask, render_template

app = Flask(__name__)

def get_db_connection():
    conn = sqlite3.connect('database.db')
    conn.row_factory = sqlite3.Row
    return conn


@app.route('/')
def index():
    conn = get_db_connection()
    posts = conn.execute('SELECT * FROM posts').fetchall()
    conn.close()
    return render_template('index.html', posts=posts)

نحفظ الملف ونغلقه.

استوردنا بدايةً في الشيفرة السابقة وحدة sqlite3 لاستخدامها في إنشاء الاتصال مع قاعدة البيانات، ومن ثمّ استوردنا كل من الصنف Flask ودالة تصيير القوالب ()render_template من حزمة فلاسك، كما أنشأنا نسخةً فعليةً من التطبيق باسم app، ومن ثمّ عرفنا دالةً باسم ()get_db_connection لإنشاء اتصال مع ملف قاعدة البيانات "database.db" المُنشأ مُسبقًا، وتحدّد بعد ذلك قيمة السمة row_factory لتكون sqlite3.Row لنتمكّن من الوصول إلى الأعمدة باستخدام أسمائها، ما يعني أنّ اتصال قاعدة البيانات سيعيد سجلات يمكننا التعامل معها كما هو الحال مع قواميس بايثون النمطية، ونهايةً تعيد الدالة كائن الاتصال conn، الذي سنستخدمه للوصول إلى قاعدة البيانات.

استخدمنا بعد ذلك المُزخرف ()app.route لإنشاء دالة عرض view في فلاسك باسم ()index، وبعدها نفتح اتصالًا مع قاعدة البيانات باستخدام الدالة get_db_connection()‎ التي عرفناها للتو. إذ سننفذ استعلام SQL للحصول على كل المدخلات الموجودة في الجدول "posts"، وسنستدعي التابع fetchall()‎ لجلب كل الأسطر الناتجة عن الاستعلام، وهذا سيعيد بالنتيجة قائمةً بالتدوينات المُدخلة إلى قاعدة البيانات في الخطوة السابقة.

يمكنك إغلاق الاتصال بقاعدة البيانات باستخدام التابع close()‎ وإعادة نتيجة تصيير القالب index.html، كما يمكنك تمرير الكائن posts وسيطًا، فهو الكائن الحاوي على النتائج المُستخلصة من قاعدة البيانات، ويساعدنا هذا التمرير على الوصول إلى التدوينات برمجيًا داخل قالب "index.html".

الآن وبغية عرض التدوينات المُخزنة ضمن قاعدة البيانات في الصفحة الرئيسية للتطبيق، سننشئ بدايةً ملف قالب ليتضمّن كافة شيفرات HTML الأساسية اللازمة لترثها لاحقًا القوالب الأُخرى ما يجنبنا تكرار الشيفرات، ومن ثمّ سننشئ ملف قالب الصفحة الرئيسية index.html المُصيّر أصلًا باستخدام الدالة ()index.

لذا سننشئ مجلدًا للقوالب باسم "templates"، وسننشئ ضمنه ملف قالب باسم "base.html"، والذي سيمثّل القالب الأساسي لبقية القوالب، كما يلي:

(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html

وسنكتب فيه الشيفرة التالية:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %}- FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}

احفظ الملف واغلقه.

يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي سنحتاجها في القوالب الأُخرى.

ستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن رابطين، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for لتحقيق الربط مع دالة العرض ()index، والآخر لصفحة المعلومات حول التطبيق في حال قررت تضمينها في تطبيقك.

الآن، سننشئ ملف قالب باسم "index.html" وهو الاسم الذي حددناه في الملف "app.py":

(env)user@localhost:$ nano templates/index.html

ونضيف ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Posts {% endblock %}h1>
    {% for post in posts %}
        <div class='post'>
            <p>{{ post['created'] }}p>
            <h2>{{ post['title'] }}h2>
            <p>{{ post['content'] }}p>
        div>
    {% endfor %}
{% endblock %}

نحفظ الملف ونغلقه.

اعتمدنا في الشيفرة السابقة على الوراثة من ملف القالب "base.html" من خلال تعليمة extends، واستبدلنا محتوى كتلة المحتوى content مُستخدمين تنسيق عنوان من المستوى الأوّل

الذي يفي أيضًا بالغرض ويكون عنوانًا للصفحة.

استخدمنا في السطر البرمجي {% for post in posts %} حلقة for من تعليمات محرّك القوالب جينجا jinja، والهدف من استخدام هذه الحلقة هو المرور على كل عنصر في القائمة posts، وبما أنّ كل عنصر (تدوينة post) في القائمة سيكون مشابهًا لما هو عليه في قاموس بايثون، فمن الممكن الوصول إلى تاريخ إنشاء التدوينة باستخدام الأمر {{ post['created']‎ }}، وإلى عنوانها من خلال post['title'] }}‎ }}، وإلى محتواها من خلال {{ post['content']‎ }}.

الآن ومع وجودنا ضمن المجلد "flask_app" ومع كون البيئة الافتراضية مُفعّلة، سنُعلم فلاسك بالتطبيق المراد تشغيله (وهو في حالتنا الملف app.py) باستخدام متغير البيئة FLASK_APP على النحو التالي:

(env)user@localhost:$ export FLASK_APP=app

نضبط متغير البيئة FLASK_ENV على القيمة development لتشغيل التطبيق في وضع التطوير مع تشغيل مُنقّح الأخطاء، ولمزيدٍ من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export?

(env)user@localhost:$ export FLASK_ENV=development

والآن سنشغّل التطبيق باستخدام الأمر flask run:

(env)user@localhost:$ flask run

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

http://127.0.0.1:5000/

وعندها ستظهر لك التدوينتان المُضافتان سابقًا إلى قاعدة البيانات بالشّكل التالي:

ومع نهاية هذه الخطوة نكون قد تمكنّا من عرض التدوينات المُخزنة ضمن قاعدة البيانات مُسبقًا في الصفحة الرئيسية للتطبيق، أمّا في الخطوة التالية فسنعمل على إضافة وجهة جديدة من شأنها السماح للمُستخدمين بإضافة تدوينات جديدة إلى قاعدة البيانات.

الخطوة 3 - إنشاء تدوينات

سنضيف في هذه الخطوة وجهة جديدة للسماح للمُستخدمين بإضافة تدوينات جديدة إلى قاعدة البيانات، لتظهر لاحقًا ضمن الصفحة الرئيسية للتطبيق، إذ سنضيف للتطبيق صفحةً جديدةً تتضمّن نموذج ويب لإدخال كل من عنوان ومحتوى التدوينة من قبل المستخدم، وسيجري التحقّق من هذه المُدخلات للتأكد من عدم إرسال المُستخدم نموذجًا فارغًا، وفي حال وجود خطأ ما في البيانات المُدخلة، سيُعلم المُستخدم بالخطأ الحاصل من خلال الرسائل الخاطفة التي تُعرض لمرة واحدة وتختفي بمجرّد إنشاء أي طلب جديد (مثل الانتقال إلى صفحة أُخرى من التطبيق).

لذلك، سنفتح نافذة أسطر أوامر جديدة مع بقاء خادم التطوير قيد التشغيل، ثمّ سنفتح الملف "app.py":

(env)user@localhost:$ nano app.py

للتعامل مع نموذج الويب، لا بُد أولًا من استيراد التالي من حزمة فلاسك:

الكائن request العام المسؤول عن الوصول إلى بيانات الطلب والتي ستُرسل من خلال نموذج HTML.
الدالة url_for()‎ لتوليد عناوين الروابط.
الدالة flash()‎ لعرض رسالةٍ خاطفة في حال ورود طلب غير صحيح.
الدالة redirect()‎ لإعادة توجيه المستخدم إلى صفحة التطبيق الرئيسية بعد إضافة التدوينات الجديدة إلى قاعدة البيانات.

أضِف هذه الاستيرادات إلى السطر الأوّل من ملف "app.py" كما يلي:

from flask import Flask, render_template, request, url_for, flash, redirect

# ...

تخزّن الدالة flash()‎ الرسائل في جلسة المتصفح لدى المستخدم، وهذا ما يتطلّب إعداد مفتاح أمان Secret Key، إذ سيُستخدم هذا المفتاح لجعل الجلسات آمنة، وبذلك يتمكّن فلاسك من الحفاظ على المعلومات عند الانتقال من طلبٍ إلى آخر، ولا يجب أن تسمح لأي أحدٍ بالوصول إلى مفتاح الأمان الخاص بك.

لإعداد مفتاح أمان، سنضيف ضبط SECRET_KEY إلى التطبيق من خلال الكائن app.config، الذي سنضيفه مباشرةً بعد تعريف الكائن app على النحو التالي:

# ...
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your secret key'

تذكّر أنّ مفتاح الأمان يجب أن يكون سلسلةً نصيةً عشوائية بطولٍ مناسب، وللمزيد حول نماذج الويب وضبط مفتاح الأمان الخاص به، ننصحك بقراءة المقال كيفية استخدام نماذج الويب في تطبيقات فلاسك.

بعد ذلك، سنضيف الوجهة التالية إلى نهاية الملف app.py :

# ...

@app.route('/create/', methods=('GET', 'POST'))
def create():
    return render_template('create.html')

نحفظ الملف ونغلقه.

نمرّر في هذه الوجهة صفًا tuple يحتوي على القيم ('GET', 'POST') إلى المعامل methods بغية السماح بكلا نوعي طلبيات HTTP وهما GET و POST؛ إذ تتخصّص الطلبيات من النوع GET بجلب البيانات من الخادم؛ أمّا الطلبيات من النوع POST فهي مُتخصّصة بإرسال البيانات إلى وجهة مُحدّدة، مع ملاحظة أنّ الطلبيات من النوع GET هي الوحيدة المسموحة افتراضيًا، وحالما يطلب المستخدم الوجهة create/ باستخدام طلبية من النوع GET، سيُصيّر ملف قالب باسم "create.html".

سنعدّل هذه الوجهة لاحقًا لتتعامل أيضًا مع الطلبيات من نوع POST اللازمة لدى ملء المُستخدمين للنماذج وإرسالها بغية إنشاء تدوينات جديدة.

والآن، افتح ملف "create.html" الجديد داخل مجلد القوالب "templates" على النحو التالي:

(env)user@localhost:$ nano templates/create.html

واكتب ضمنه الشيفرة التالية:

{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Add a New Post {% endblock %}h1>
    <form method="post">
        <label for="title">Titlelabel>
        <br>
        <input type="text" name="title"
               placeholder="Post title"
               value="{{ request.form['title'] }}">input>
        <br>

        <label for="content">Post Contentlabel>
        <br>
        <textarea name="content"
                  placeholder="Post content"
                  rows="15"
                  cols="60"
                  >{{ request.form['content'] }}textarea>
        <br>
        <button type="submit">Submitbutton>
    form>
{% endblock %}

احفظ الملف واغلقه.

وبذلك نكون قد ورثنا خصائص القالب "base.html"، واستخدمنا الوسم وفيه ضبطنا سمة نوع طلبية HTTP لتكون من النوع POST ما يعني أنّ نموذج الويب هذا سيرسل طلب من النوع POST، كما أضفنا صندوق نصي باسم title لنستخدمه في الوصول إلى بيانات عنوان التدوينة في الوجهة create/، وضبطنا القيمة داخل الصندوق النصي هذا الخاص بعنوان التدوينة إلى {{ request.form['title']‎ }} والتي قد تكون فارغةً، أو نسخةً محفوظةً مؤقتًا من العنوان في حال كون النموذج المرسل خاطئًا، وهذا ما يحافظ على البيانات المدخلة في الأداة عند حدوث خطأ ما.

أضفنا بعد الصندوق النصي المُخصّص للعنوان حقلًا نصيًا مُتعدّد الأسطر مُخصّص لمحتوى التدوينة باسم content والقيمة داخله هي {{ request.form['content']‎ }} للحفاظ على البيانات المدخلة فيه في حال كون النموذج المرسل خاطئًا، لأنّ المعلومات المدخلة سيُحتفظ بها في الكائن العام request، ونهايةً أضفنا إلى نهاية النموذج زرًا لتأكيد إرساله.

الآن وأثناء عمل خادم التطوير، استخدم المتصفح للانتقال إلى الوجهة ‎/create:

http://127.0.0.1:5000/create

فستظهر لك صفحة إنشاء تدوينة جديدة مع صندوق نصي لإدخال العنوان، وحقل نصي مُتعدّد الأسطر لإدخال المحتوى، وزر لتأكيد إرسال النموذج Submit، كما في الشّكل التالي:

يرسل نموذج الإدخال هذا طلبًا من النوع POST إلى الخادم، ولكن حتى هذه اللحظة لا يوجد شيفرة مسؤولة عن معالجة هذا الطلب في الوجهة create/، وبالتالي لن يحدث شيء في حال ملء النموذج الآن وإرساله.

لذا، فيما يلي ستعالج الدالة create()‎ الطلبات الواردة بطريقة POST عند إرسال محتويات نموذج الإدخال وذلك بعد التحقق من قيمة تابع الطلب request.method؛ فإذا كانت قيمته 'POST'، تستمر بمتابعة قراءة البيانات المرسلة والتحقق منها وإدخالها في قاعدة البيانات.

الآن، افتح الملف "app.py" بهدف تعديله ليتعامل مع الطلبات من النوع POST المُرسلة من قبل المستخدم:

(env)user@localhost:$ nano app.py

ونعدّل الوجهة create/ لتصبح كما يلي:

# ...

@app.route('/create/', methods=('GET', 'POST'))
def create():
    if request.method == 'POST':
        title = request.form['title']
        content = request.form['content']

        if not title:
            flash('Title is required!')
        elif not content:
            flash('Content is required!')
        else:
            conn = get_db_connection()
            conn.execute('INSERT INTO posts (title, content) VALUES (?, ?)',
                         (title, content))
            conn.commit()
            conn.close()
            return redirect(url_for('index'))

    return render_template('create.html')

احفظ الملف واغلقه.

تَمكَّنا باستخدام العبارة الشرطية if request.method == 'POST' التي تقارن قيمة request.method مع القيمة POST من التحقُّق بأنّ التعليمات التالية لها لن تُنفّذ إلّا إذا كان الطلب الحالي هو فعلًا بطريقة POST، ومن ثمّ قرأنا قيم العنوان والمحتوى المرسلين من الكائن request.form، الذي يمكِّننا من الوصول إلى بيانات نموذج الإدخال المُضمّنة في الطلب.

في حال عدم إدخال قيمةٍ للعنوان ستظهر رسالة خاطفة للمستخدم نعلمه من خلالها باستخدام الدالة ()flash بأن العنوان مطلوب !Title is required، وسيحدث الأمر ذاته في حال عدم ملء حقل المحتوى؛ أمّا في حال وجود كل من العنوان والمحتوى، فسيُفتَح اتصال مع قاعدة البيانات باستخدام الدالة get_db_connection()‎، وسيُنفّذ الأمر INSERT INTO من أوامر SQL باستخدام التابع ()execute وذلك لإضافة التدوينة الجديدة إلى جدول التدوينات "posts" في قاعدة البيانات وفق العنوان والمحتوى المُدخلان أصلًا من قِبل المُستخدم في النموذج.

استخدمنا الموضع المؤقت ? بما يضمن إدخال البيانات في الجدول بأمان، ثمّ حفظنا التغييرات باستخدام الدالة ()connection.commit، وأُغلق الاتصال مع قاعدة البيانات باستخدام الدالة ()connection.close، ونهايةً أعدنا توجيه المًستخدم إلى الصفحة الرئيسية من التطبيق ليرى تدوينته الجديدة أسفل التدوينات السابقة الموجودة أصلًا.

تنبيه: لا تستخدم عمليات بايثون المحرفية بغية إنشاء سلسلة تعليمات SQL ديناميكيًا، بل استخدم دائمًا الموضع المؤقت ? في تعليمات SQL لتعويض القيم ديناميكيًا، فمن الممكن تمرير صف tuple من القيم مثل وسيط ثانٍ ضمن التابع ()execute لربط هذه القيم مع تعليمة SQL، وهذا ما يمنع هجمات حقن استعلامات SQL (إحدى أكثر طرق الاختراق خطرًا على كل من المواقع والأنظمة، وتتضمن هذه الطريقة إدخال استعلامات SQL في حقول الإدخال).

الآن وأثناء عمل خادم التطوير، استخدم المتصفح للانتقال إلى الوجهة ‎/create باستخدام الرابط:

http://127.0.0.1:5000/create

املأ النموذج بالعنوان والمحتوى الذي تريد، وحال إرسال النموذج سيُعاد توجيهك إلى الصفحة الرئيسية للتطبيق، حيث سترى التدوينة الجديدة فيها؛ أمّا في حال إرسال النموذج مع حقل عنوان أو محتوى فارغ، فلن تُضاف التدوينة إلى قاعدة البيانات، ولن يُعاد التوجيه إلى الصفحة الرئيسية للتطبيق، وكل ذلك دون الحصول على أي معلومات حول ماهية ما حصل وسببه، وذلك لأننا لم نُعدّ الرسائل الخاطفة للعرض حتى الآن.

لذلك، سنفتح الآن ملف القالب الأساسي base.html لإضافة رابط في شريط التصفح للوصول إلى صفحة إنشاء تدوينة جديدة، ولإظهار الرسائل الخاطفة أسفله:

(env)user@localhost:$ nano templates/base.html

ونعدل الملف ليصبح كما يلي:


 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('create') }}">Create
         href="#">About
    
    
     class="content">
        {% for message in get_flashed_messages() %}
             class="alert">{{ message }}
        {% endfor %}

        {% block content %} {% endblock %}

نحفظ الملف ونغلقه.

أضفنا في الشيفرة السابقة وسم رابط جديد إلى شريط التصفُّح والذي يشير إلى صفحة إنشاء تدوينة جديدة.

استخدمنا حلقة for التكرارية من تعليمات جينجا للمرور على الرسائل الخاطفة، إذ يوفّر فلاسك هذه الرسائل من خلال دالة فلاسك الخاصة get_flashed_messages()‎ لتُعرض ضمن وسم

ذو صنف CSS يدعى alert، ونسقنا مظهر الوسم

من خلال الوسم




    
         href="{{ url_for('index') }}">FlaskApp
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}






	إذ يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي ستحتاجها في القوالب الأُخرى.



	ستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة، وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن رابطين، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for لتحقيق الربط مع دالة العرض ()index، والآخر لصفحة المعلومات حول التطبيق في حال قررت تضمينها في تطبيقك.



	نحفظ الملف ونغلقه.



	الآن، سننشئ ملف قالب باسم "index.html" وهو الاسم الذي حددناه في الملف "app.py":


(env)user@localhost:$ nano templates/index.html


	سيتضمّن هذا الملف نموذج الويب المُمرر إلى القالب "index.html" عن طريق المتغير form، وسنضيف ضمنه الشيفرات التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Add a New Course {% endblock %}h1>

    <form method="POST" action="/">
        {{ form.csrf_token }}
        <p>
            {{ form.title.label }}
            {{ form.title(size=20) }}
        p>

        {% if form.title.errors %}
            <ul class="errors">
                {% for error in form.title.errors %}
                    <li>{{ error }}li>
                {% endfor %}
            ul>
        {% endif %}

        <p>
            {{ form.description.label }}
        p>
        {{ form.description(rows=10, cols=50) }}

        {% if form.description.errors %}
            <ul class="errors">
                {% for error in form.description.errors %}
                    <li>{{ error }}li>
                {% endfor %}
            ul>
        {% endif %}

        <p>
            {{ form.price.label }}
            {{ form.price() }}
        p>

        {% if form.price.errors %}
            <ul class="errors">
                {% for error in form.price.errors %}
                    <li>{{ error }}li>
                {% endfor %}
            ul>
        {% endif %}

        <p>
            {{ form.available() }} {{ form.available.label }}
        p>

        {% if form.available.errors %}
            <ul class="errors">
                {% for error in form.available.errors %}
                    <li>{{ error }}li>
                {% endfor %}
            ul>
        {% endif %}

        <p>
            {{ form.level.label }}
            {{ form.level() }}
        p>

        {% if form.level.errors %}
            <ul class="errors">
                {% for error in form.level.errors %}
                    <li>{{ error }}li>
                {% endfor %}
            ul>
        {% endif %}

        <p>
            <input type="submit" value="Add">
        p>
    form>

{% endblock %}


	نحفظ الملف ونغلقه.



	امتد القالب الرئيسي في بداية الشيفرة، وعيّنا عنوانًا للصفحة ضمن تنسيق عنوان من المستوى الأوّل باستخدام الوسم 
، ثمّ صيّرنا حقول نموذج الويب ضمن الوسم ، وضبطنا نوع طلبات HTTP الخاصّة به لتكون من النوع POST، والحدث المرتبط به ليكون الانتقال إلى الوجهة الرئيسية / المُتمثّلة بالصفحة الرئيسية للتطبيق. صيّرنا بدايةً المفتاح المساعد token الذي تستخدمه نماذج WTForms لحماية النموذج من هجمات CSRF باستخدام التعليمة {{ form.csrf_token }}، إذ يُرسل هذا المفتاح إلى الخادم مع بقية بيانات النموذج، ومن المهم جدًا تصيّير المفتاح المساعد لجعل النماذج آمنة.



	صيّرنا كل حقل من النموذج باستخدام الصيغة ()form.field، كما صيّرنا عنوان كل منها باستخدام الصيغة form.field.label، وهنا من الممكن تمرير وسطاء إلى كل حقل والتي من شأنها التحكّم بطريقة عرضه، فمثلًا عيّنا حجم الصندوق النصي الخاص بالعنوان بالشّكل {{ form.title(size=20) }}، كما عيّنا عدد الأسطر والأعمدة ضمن الحقل النصي مُتعدّد الأسطر والخاص بوصف الدورة بالشّكل من خلال المعاملين rows و cols وبنفس الطريقة التقليدية المُتبعة في لغة HTML، وبذلك من الممكن إضافة ما نشاء من سمات HTML إلى الحقول، مثل سمة class مثلًا بغية تعيّين صنفٍ لشيفرات CSS.



	استخدمنا الصيغة if form.field.errors للتحقّق من وجود أخطاء في المُصادقة، ففي حال وجود أخطاء في حقلٍ ما، سيجري المرور عليها باستخدام حلقة for تكرارية لتُعرض ضمن قائمة أسفل الحقل.



	الآن، ومع وجودنا ضمن المجلد "flask_app" ومع كون البيئة الافتراضية مُفعّلة، سنُعلم فلاسك بالتطبيق المراد تشغيله (وهو في حالتنا الملف app.py) باستخدام متغير البيئة FLASK_APP، ثم نضبط متغير البيئة FLASK_ENV لتشغيل التطبيق في وضع التطوير development، مع إمكانية الوصول إلى مُنقّح الأخطاء؛ ولمزيدٍ من المعلومات حول مُنقّح الأخطاء في فلاسك ننصحك بقراءة المقال كيفية التعامل مع الأخطاء في تطبيقات فلاسك، ولتنفيذ ما سبق سنشغّل الأوامر التالية (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export?


(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development


	والآن سنشغّل التطبيق باستخدام الأمر التالي:


(env)user@localhost:$ flask run


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


http://127.0.0.1:5000/


	فيظهر نموذج الويب ضمن الصفحة الرئيسية للتطبيق كما هو موضح في الشكل التالي:



	



	ولو جرّبنا إرسال النموذج مع ترك حقل العنوان فارغًا، ستظهر رسالة خطأ تعلمنا بأن العنوان مطلوب، وهنا من الجيد تجربة إرسال نماذج ببيانات لا تحقق الشروط بغية التعرّف على رسائل الخطأ المُختلفة، مثل إدخال عنوان بأقل من 10 محارف، أو وصف يتجاوز 200 محرف، أمّا إذا ملأنا النموذج ببيانات صحيحة وأرسلناه فلن يحدث شيء حاليًا، والسبب أنّنا لم نضف حتى الآن الشيفرة اللازمة للتعامل مع النماذج المُرسلة، الأمر الذي سنفعله لاحقًا.



	سنعمل الآن على إضافة صفحة لعرض الدورات الموجودة في القائمة، وسنضيف فيما بعد ما يلزم للتعامل مع البيانات الآتية من نموذج الويب، والتي ستضيف بالنتيجة دورة جديدة إلى القائمة، ليُعاد بعدها توجيه المُستخدم إلى صفحة عرض الدورات ليرى أنّ الدورة الجديدة قد أُضيفت فعلًا.



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


(env)user@localhost:$ nano app.py


	وسنضيف الوجهة التالية إلى نهاية الملف:


# ...

@app.route('/courses/')
def courses():
    return render_template('courses.html', courses_list=courses_list)


	نحفظ الملف ونغلقه.



	تُخرج الوجهة السابقة قالبًا باسم "courses.html" ممرّرة له قائمة الدورات courses_list.



	أمّا الآن فسننشئ القالب "courses.html" المسؤول عن عرض الدورات:


(env)user@localhost:$ nano templates/courses.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Courses {% endblock %}h1>
    <hr>
    {% for course in courses_list %}
        <h2> {{ course['title'] }} h2>
        <h4> {{ course['description'] }} h4>
        <p> {{ course['price'] }}$ p>
        <p><i>({{ course['level'] }})i>p>
        <p>Availability:
            {% if course['available'] %}
                Available
            {% else %}
                Not Available
            {% endif %}p>
        <hr>
    {% endfor %}
{% endblock %}


	نحفظ الملف ونغلقه.



	عيّنا في الشيفرة السابقة عنوانًا، ثمّ مررنا على كافّة عناصر القائمة courses_list، إذ سيُعرض العنوان ضمن تنسيق عنوان من المستوى الثاني باستخدام الوسم 
، والوصف ضمن تنسيق عنوان من المستوى الرابع ، أمّا كل من السعر والمستوى فسيُعرضان ضمن تنسيق فقرة باستخدام الوسم ، ويجري التحقّق من كون الدورة مُتاحة باستخدام العبارة الشرطية ['if course['available، لتُعرض العبارة "Available"، والتي تعني أن الدورة مُتاحة في حال توفرها، والعبارة "Not Available" في حال عدم توفرها.



	وبالانتقال إلى صفحة الدورات باستخدام الرابط التالي في المتصفح:


http://127.0.0.1:5000/courses/


	ستظهر الصفحة مُتضمّنةً دورةً تدريبيةً واحدةً وهي تلك التي أضفناها يدويًا إلى قائمة بايثون سابقًا، كما هو موضح في الشّكل التالي:



	



	أمّا الآن، سنفتح ملف القالب الأساسي "base.html" لتعديله بغية إضافة رابط مباشر ينقلنا إلى صفحة عرض الدورات وذلك ضمن شريط التصفّح:


(env)user@localhost:$ nano templates/base.html


	ونعدله ليبدو على النحو التالي:



 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('courses') }}">Courses
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}






	نحفظ الملف ونغلقه.



	الآن سيظهر رابط الانتقال إلى صفحة عرض الدورات ضمن شريط التصفّح عند تحديث الصفحة الرئيسية للتطبيق في المتصفّح.



	ومع نهاية هذه الخطوة نكون قد أنشأنا الصفحات اللازمة للتطبيق، وهي: الصفحة الرئيسية "index.html" المُتضمّنة نموذج ويب لإضافة دورات جديدة، وصفحة لعرض الدورات المُخزّنة ضمن قائمة الدورات "courses.html".



	لجعل التطبيق يعمل فعليًا، سنعالج في الخطوة التالية البيانات التي يرسلها المُستخدم عبر نموذج الويب من حيث التحقّق من صحتها وإضافتها إلى قائمة الدورات.



	الخطوة الرابعة - الوصول إلى بيانات النموذج



	سنعمل في هذه الخطوة على الوصول إلى البيانات التي أرسلها المُستخدم عبر النموذج للتأكّد من صحتها ومن ثمّ إضافتها إلى قائمة الدورات. لذلك، سنفتح الملف "app.py" لتعديله بإضافة الشيفرات اللازمة للتعامل مع بيانات نموذج الويب وذلك ضمن الدالة ()index:


(env)user@localhost:$ nano app.py


	وسنعدّل الدالة ()index لتصبح كما يلي:


# ...
@app.route('/', methods=('GET', 'POST'))
def index():
    form = CourseForm()
    if form.validate_on_submit():
        courses_list.append({'title': form.title.data,
                             'description': form.description.data,
                             'price': form.price.data,
                             'available': form.available.data,
                             'level': form.level.data
                             })
        return redirect(url_for('courses'))
    return render_template('index.html', form=form)


	نحفظ الملف ونغلقه.



	استدعينا في الشيفرة السابقة التابع ()validate_on_submit من الكائن form، إذ يتحقّق هذا التابع من كون طلب HTTP من النوع POST، ثمّ شغلنا المدققات التي أعددناها سابقًا لكل حقل من الحقول، فإذا أعاد أي منها خطأ ما لن يتحقق الشرط أي ستكون قيمته False، وسيظهر كل خطأ أسفل الحقل الذي تسبب بحدوثه.



	أمّا في حال كانت كافّة البيانات المُدخلة صحيحة، سيتحقق الشرط أي ستكون قيمته True وبالتالي سيُنفّذ جزء الشيفرة التالي لتعليمة if، وفيها نبني قاموس بايثون للدورة الجديدة ومن ثمّ نستخدم التابع append لإضافة هذه الدورة إلى قائمة الدورات courses_list، إذ استخدمنا الصيغة form.field.data للوصول إلى قيمة كل حقل في النموذج، ونهايةً وبعد إضافة الدورة الجديدة إلى قائمة الدورات، نعيد توجيه المُستخدم إلى صفحة عرض الدورات.



	الآن، سننتقل إلى الصفحة الرئيسية للتطبيق مع كون خادم التطوير قيد التشغيل، باستخدام الرابط:


http://127.0.0.1:5000/


	وبملء النموذج ببيانات صحيحة وإرساله، نلاحظ إضافة الدورة الجديدة فعلًا، وسنُوجّه تلقائيًا إلى صفحة عرض الدورات من التطبيق والتي ستظهر فيها الدورة الجديدة المُضافة.



	الخلاصة



	أنشأنا في هذه المقال تطبيق فلاسك ذا نموذج ويب مبني باستخدام الإضافة Flask-WTF والمكتبة WTForms، إذ ضمّنا في نموذج الويب هذا العديد من أنواع الحقول التي من شأنها استقبال البيانات من المُستخدم وتحقّقنا من صحتها بالاعتماد على المُدققين الخاصين بمكتبة WTForms، لنضيف هذه البيانات بالنتيجة إلى مخزن البيانات وهو قائمة بايثون في مثالنا.



	ترجمة -وبتصرف- للمقال How To Use and Validate Web Forms with Flask-WTF لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا



	
		كيفية استخدام نماذج الويب في تطبيقات فلاسك Flask
	
	
		مدخل إلى استخدام مكتبة WTForms للتعامل مع نماذج HTML في تطبيقات Flask
	
	
		إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask من لغة بايثون



كيفية استخدام نماذج الويب في تطبيقات فلاسك Flask
Wed, 05 Oct 2022 07:35:09 +0000




	تمنح نماذج الويب web forms من صناديقٍ نصيّة وحقول نصوص مُتعدّدة الأسطر المستخدمين القدرة على إرسال البيانات إلى التطبيق لاستخدامها في تنفيذ أمرٍ ما، أو حتّى لإرسال محتوًى نصي كبير، فمثلًا يُمنح المستخدم في تطبيقات التواصل الاجتماعي حيزًا يمكِّنه من إضافة محتوًى جديد إلى صفحته الشخصية؛ كما يوجد أيضًا في صفحة تسجيل الدخول حقلٌ لإدراج اسم المستخدم وحقلٌ لإدراج كلمة المرور، إذ يستخدم الخادم (تطبيق فلاسك في حالتنا) هذه البيانات التي أدخلها المستخدم ليسجّل دخوله إذا كانت البيانات صحيحة أو يستجيب برسالة خطأ مثل "!Invalid credentials" لإعلام المستخدم بأن البيانات التي أدخلها خاطئة.



	يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا عدّة أدوات وميزات من شأنها جعل إنشاء تطبيقات الويب في لغة بايثون أسهل.



	سننشئ في هذا المقال تطبيق ويب مُصغّر لبيان كيفيّة استخدام نماذج الويب، إذ سيتضمّن صفحةً لإظهار رسائل مُخزّنةٍ مُسبقًا ضمن قائمة باستخدام بايثون، وصفحةً أُخرى لإضافة رسائل جديدة، كما سنستخدم الرسائل الخاطفة message flashing لإبلاغ المستخدمين بوجود خطأ لدى إدخالهم لبيانات غير صحيحة.



	#مستلزمات العمل



	قبل المتابعة في هذا المقال لا بُدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
	
	
		الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات routes ودوال العرض view في فلاسك، وفي هذا الصدد يمكنك الاطلاع على المقال كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون لفهم مبادئ فلاسك.
	
	
		فهم أساسيات لغة HTML.
	


	الخطوة الأولى - عرض الرسائل



	سننشئ في هذه الخطوة تطبيق فلاسك بصفحة رئيسية لعرض رسائل مُخزنة أصلًا في قائمة من قواميس بايثون.



	لذا سنفتح ملف جديد باسم "app.py" للتعديل عليه:


(env)user@localhost:$ nano app.py


	وسنضيف الشيفرة التالية ضمنه، بغية إنشاء خادم فلاسك ذو وجهةٍ واحدة:


from flask import Flask, render_template

app = Flask(__name__)

messages = [{'title': 'Message One',
             'content': 'Message One Content'},
            {'title': 'Message Two',
             'content': 'Message Two Content'}
            ]

@app.route('/')
def index():
    return render_template('index.html', messages=messages)


	ثمّ نحفظ الملف ونغلقه.



	استوردنا في الشيفرة السابقة كلًا من الصنف Flask الذي سنستخدمه لإنشاء نسخة من التطبيق باسم app، ودالة تصيّير القوالب ()render_template من حزمة فلاسك flask، مُمررّين المتغير الخاص __name__ اللازم لتمكين فلاسك من إعداد بعض المسارات العاملة في الخلفية؛ أمّا عن تصيير القوالب، فننصحك بقراءة المقال كيفية استخدام القوالب في تطبيقات فلاسك Flask.



	ثمّ أنشأنا قائمةً عامّة في بايثون باسم messages، والتي تحتوي على قواميس بايثون، وفي كل قاموس أضفنا مفتاحين أساسيين، هما: title لتخزين عنوان الرسالة، و content لتخزين مضمونها، وما هذا إلّا مثال مُبسّط لآلية تخزين البيانات، إذ نستخدم في التطبيقات العملية الواقعية قاعدة بيانات لتُخزّن هذه البيانات بصورةٍ دائم سامحةً لنا بتعديلها واسترجاعها بسهولة وفعالية.



	وبعد إنشاء قائمة بايثون، أنشأنا دالة العرض ()index باستخدام المُزخرف ()app.route@ الذي يحوّل دوال بايثون الاعتيادية إلى دوال عاملة في فلاسك، وفيها تكون القيمة المعادة استدعاءً للدالة ()render_template التي تُعلم فلاسك بأنّ الوجهة الحالية يجب أن تعرض في النتيحة قالب HTML باسم index.html (سننشئ ملف القالب هذا في الخطوات اللاحقة) ممررين له قيمة المتغير المُسمّى messages والذي يحتوي على قائمة الرسائل messages التي صرحنا عنها للتو مُسندين لها القيم اللازمة، وجعلناها متاحةً للاستخدام من قبل قالب HTML.



	ننصحك في هذا الصدد بقراءة المقال How To Create Your First Web Application Using Flask and Python 3 لفهم أعمق لدوال العرض في فلاسك.



	الآن، سننشئ مجلدًا للقوالب باسم "templates" ضمن المجلد "flask_app"، إذ سيبحث فلاسك ضمنه عن القوالب، وبعدها سننشئ ملف القالب الأساسي باسم "base.html" وفيه سنكتب الشيفرة الأساسية التي سترثها بقية القوالب لتجنّب تكرار الشيفرات:


(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html


	ومن ثمّ نكتب الشيفرة التالية ضمن الملف base.html لإنشاء قالب HTML الأساسي مع شريط تنقل وجزء مُخصّص للمحتوى:


DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{% block title %} {% endblock %} - FlaskApptitle>
    <style>
        .message {
            padding: 10px;
            margin: 5px;
            background-color: #f3f3f3
        }
        nav a {
            color: #d64161;
            font-size: 3em;
            margin-left: 50px;
            text-decoration: none;
        }

    style>
head>
<body>
    <nav>
        <a href="{{ url_for('index') }}">FlaskAppa>
        <a href="#">Abouta>
    nav>
    <hr>
    <div class="content">
        {% block content %} {% endblock %}
    div>
body>
html>


	نحفظ الملف ونغلقه.



	يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي سنحتاجها في القوالب الأُخرى.



	ستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن رابطين، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for لتحقيق الربط مع دالة العرض ()index، والآخر لصفحة المعلومات حول التطبيق في حال قررت تضمينها في تطبيقك.



	لذا سنفتح ملف القالب المُسمى "index.html" وهو الاسم الذي حددناه في الملف app.py:


(env)user@localhost:$ nano templates/index.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Messages {% endblock %}h1>
    {% for message in messages %}
        <div class='message'>
            <h3>{{ message['title'] }}h3>
            <p>{{ message['content'] }}p>
        div>
    {% endfor %}
{% endblock %}


	ثمّ نحفظ الملف ونغلقه.



	وسّعنا في الشيفرة السابقة ملف القالب "base.html"، واستبدلنا محتوى كتلة المحتوى content مُستخدمين تنسيق العنوان من المستوى الأوّل 
 الذي يفي أيضًا بالغرض لعنوان الصفحة.



	كما استخدما حلقة for التكرارية وهي من ضمن تعليمات محرّك القوالب جينجا Jinja وذلك في السطر البرمجي {% for message in messages %} بهدف التنقل بين الرسائل في القائمة messages (والمُخزنة ضمن المتغير المسمّى message)؛ إذ سنعرض عناوين الرسائل ضمن تنسيق عنوان من المستوى الثالث باستخدام الوسم 
، ومحتواها ضمن تنسيق فقرة باستخدام الوسم ، وكلاهما ضمن حافظة عناصر HTML باستخدام الوسم 
.



	ولتشغيل تطبيق الويب الذي أنشأناه، وبعد التأكّد من وجودنا ضمن المجلد "flask_app" مع تفعيل البيئة الافتراضية، لا بُدّ من إرشاد فلاسك إلى موقع التطبيق (في حالتنا الملف ذو الاسم "app.py") وذلك باستخدام متغير بيئة فلاسك FLASK_APP:


(env)user@localhost:$ export FLASK_APP=app


	نضبط متغير بيئة فلاسك Flask_ENV على الوضع development لتشغيل التطبيق في وضع التطوير ما يمكنّنا من استخدام مُنقّح الأخطاء كما يلي (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export):


(env)user@localhost:$ export FLASK_ENV=development


	بعدها، سنشغل التطبيق باستخدام الأمر flask run:


(env)user@localhost:$ flask run


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


http://127.0.0.1:5000/


	فتظهر الرسائل المُخزّنة أصلًا ضمن القائمة "messages" في الصفحة الرئيسية للتطبيق كما يلي:



	



	ومع نهاية هذه الخطوة نكون قد أعددنا تطبيق الويب ليعرض الرسائل المُخزنة، أمّا في الخطوة التالية سنعدّ نماذج الويب اللازمة لنسمح للمستخدمين بإضافة رسائل جديدة إلى القائمة لعرضها في الصفحة الرئيسية للتطبيق.



	الخطوة الثانية - إعداد نماذج الويب



	سننشئ في هذه الخطوة صفحةً جديدةً في التطبيق تسمح للمستخدمين بإضافة رسائل جديدة إلى قائمة الرسائل من خلال نموذج ويب.



	لذا سنفتح نافذة طرفية جديدة مع بقاء خادم التطوير قيد التشغيل.



	ومنها نفتح الملف app.py:


(env)user@localhost:$ nano app.py


	ونضيف الوجهة التالية إلى نهاية الملف:


# ...

@app.route('/create/', methods=('GET', 'POST'))
def create():
    return render_template('create.html')


	نحفظ الملف ونغلقه.



	تتضمّن الوجهة ‎/create معامل طلبيات HTTP methods المتضمّن صفًا tuple هو ('GET', 'POST') للتعامل معها سواءً بطريقة GET، أو POST، إذ أن طريقة "GET" هي الطريقة الافتراضية المُستخدمة لجلب البيانات من الخادم، مثل حالة طلب عرض الصفحة الرئيسية أو صفحة المعلومات حول التطبيق؛ أمّا طريقة "POST" فتُستخدم من قبل المتصفح عند إرسال نماذج الإدخال إلى وجهةٍ مُحدّدة، الأمر الذي سيغيّر من البيانات المُخزّنة في الخادم.



	وفي مثالنا هذا سيُطلب عرض صفحة إنشاء رسائل جديدة "create" باستخدام طلب من النوع "GET"، إذ ستتضمّن هذه الصفحة نموذج ويب بحقول إدخال وزر إرسال، ولدى ملء النموذج من قبل المستخدم وإرساله، يُرسل طلب من النوع "POST" إلى الوجهة create/، الذي يتعامل مع الطلب من حيث التحقّق من صحة البيانات المُدخلة للتأكّد من كون المُستخدم لم يرسل نموذجًا فارغًا، لتُضاف عندها هذه البيانات إلى قائمة الرسائل "messages".



	تؤدي دالة فلاسك ()create حاليًا مهمةً واحدة، وهي تصيّير قالب HTML باسم "create.html" لدى استقبالها لطلب من نوع GET، لذا سننشئ الآن هذا القالب وسنعدّل الدالة ()create لتصبح قادرةً أيضًا على التعامل مع الطلبات من النوع POST اللازمة في الخطوة التالية.



	لذا سنفتح ملف القالب المُسمّى "create.html":


(env)user@localhost:$ nano templates/create.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Add a New Message {% endblock %}h1>
    <form method="post">
        <label for="title">Titlelabel>
        <br>
        <input type="text" name="title"
               placeholder="Message title"
               value="{{ request.form['title'] }}">input>
        <br>

        <label for="content">Message Contentlabel>
        <br>
        <textarea name="content"
                  placeholder="Message content"
                  rows="15"
                  cols="60"
                  >{{ request.form['content'] }}textarea>
        <br>
        <button type="submit">Submitbutton>
    form>
{% endblock %}


	ثمّ نحفظ الملف ونغلقه.



	وسّعنا في الشيفرة السابقة قالب base.html واستبدلنا كتلة المحتوى content بكائن عنوان من المستوى الأوّل 
 الذي سيعمل مثل عنوان للصفحة، وعيّنا في وسم كائن النموذج  قيمة السمة method لتكون post بمعنى أنّ بيانات النموذج ستُرسل إلى الخادم مثل طلب من نوع POST.



	وفي كائن النموذج أضفنا حقل إدخال نصي باسم title وهو الاسم الذي سنستخدمه في التطبيق للوصول إلى بيانات نموذج العنوان، كما أسندنا القيمة {{ request.form['title']‎ }} لسمة value من الوسم ، وهو أمرٌ مفيدٌ لتخزين البيانات التي يدخلها المستخدم مع إمكانية استعادتها في حال حدوث خطأ ما؛ فإذا نسي المستخدم مثلًا ملء الحقل النصي المُخصّص لمحتوى الرسالة content وهو حقل مطلوب، فسيُرسل طلب إلى الخادم لإرجاع رسالة خطأ في الاستجابة، ولكن البيانات في العنوان لن نفقدها لأنها محفوظة في الكائن العام request ويمكن الوصول لها من خلال القيمة ['request.from['title.



	أضفنا بعد حقل الإدخال المُخصّص لعنوان الرسالة، حقلًا نصيًا مُتعدّد الأسطر لمحتواها باسم content وأسندنا أيضًا القيمة {{ request.form['content']‎ }} لسمة value لنفس السبب آنف الذكر.



	ونهايةً أضفنا زر إرسال إلى نهاية النموذج.



	الآن وبعد التأكد من كون خادم التطوير ما يزال قيد التشغيل، ننتقل إلى الوجهة الجديدة create/ باستخدام المتصفح:


http://127.0.0.1:5000/create


	فتظهر صفحة إضافة رسالة جديدة “Add a New Message” مع حقل إدخال لعنوان الرسالة وحقل نصي مُتعدّد الأسطر لإدخال محتوى الرسالة، وزر لتقديم النموذج عند الانتهاء من إدخال البيانات.



	



	يُرسل هذا النموذج طلبًا من نوع "POST" إلى دالة فلاسك ()create، ولكن حتى الآن ما من شيفرة في الدالة للتعامل مع الطلب هذا، لذا لن يحدث شيء بعد تعبئة النموذج وإرساله> لذلك، سنكتب في الخطوة التالية الشيفرة اللازمة للتعامل مع طلب من النوع "POST" بعد إرسال النموذج، إذ سنتحقّق من صحة البيانات المرسلة (ليست فارغة)، كما سنضيف عنوان الرسالة ومحتواها إلى قائمة الرسائل "messages".



	الخطوة الثالثة - التعامل مع الطلبات الواردة من نماذج الويب



	سنتعامل في هذه الخطوة مع الطلبات الواردة من نماذج الإدخال إلى التطبيق، إذ سنعمل على الوصول إلى البيانات التي أرسلها المستخدم عبر نموذج الإدخال المُنشأ في الخطوة السابقة لإضافتها إلى قائمة الرسائل، كما سنستخدم الرسائل الخاطفة message flashing لإعلام المستخدم في حال إرسال بيانات غير صحيحة، فعندها ستظهر الرسالة لمرة واحدة وتختفي في الطلب التالي (مثل الانتقال إلى صفحة أُخرى) ومن هنا جاء سبب تسميتها بالخاطفة.



	لذا سنفتح الملف app.py لتحريره:


(env)user@localhost:$ nano app.py


	لا بُد أولًا من استيراد ما يلي من إطار العمل فلاسك:




		الكائن request العام المسؤول عن الوصول إلى بيانات الطلب والتي ستُرسل من خلال نموذج HTML المبني في الخطوة السابقة.
	
	
		الدالة url_for()‎ لتوليد عناوين الروابط.
	
	
		الدالة flash()‎ لعرض رسالةٍ وامضة عند انتهاء معالجة الطلب، لإعلام المُستخدم في حال سير الأمور على نحوٍ سليم أو في حال وجود مشاكل مثل كون البيانات المُدخلة خاطئة.
	
	
		الدالة redirect()‎ لإعادة توجيه المستخدم إلى موقعٍ آخر في المتصفح.
	


	سنضيف هذه الاستيرادات إلى السطر الأوّل من الملف كما يلي:


from flask import Flask, render_template, request, url_for, flash, redirect

# ...


	تخزّن الدالة flash()‎ الرسائل في جلسة المتصفح لدى المستخدم، وهذا ما يتطلّب إعداد مفتاح أمان Secret Key، إذ سيُستخدم هذا المفتاح لجعل الجلسات آمنة، وبذلك يتمكّن فلاسك من الحفاظ على المعلومات عند الانتقال من طلبٍ إلى آخر، مثل حالة الانتقال من صفحة إنشاء رسالة جديدة إلى الصفحة الرئيسية، مع ملاحظة أن المستخدم يستطيع الوصول إلى المعلومات المُخزّنة في الجلسة، ولكنه لا يستطيع تعديلها إلّا إذا كان لديه مفتاح الأمان، وبالتالي لا يجب أن تسمح لأي أحدٍ بالوصول إلى مفتاح الأمان الخاص بك.



	تذكّر أنّ مفتاح الأمان يجب أن يكون سلسلةً نصيةً عشوائية بطولٍ مناسب، إذ من الممكن توليد مفتاح أمان باستخدام التابع ()os.urandom من الوحدة os، إذ يعيد هذا التابع سلسلة من البايتات العشوائية المناسبة لاستخدامات التشفير (الحصول على سلسلة نصية خاصّة أو رقم خاص). للحصول على سلسلة نصية عشوائية باستخدام هذا التابع، سنفتح نافذة طرفية جديدة ومنها نفتح صَدفة بايثون التفاعلية باستخدام الأمر التالي:


(env)user@localhost:$ python


	وضمن صَدفة بايثون التفاعلية سنستورد الوحدة os من مكتبة بايثون المعيارية، وسنستدعي التابع ()os.urandom كما يلي:


>>> import os
>>> os.urandom(24).hex()


	فنحصل في الخرج على سلسلة مُشابهة لما يلي:


'df0331cefc6c2b9a5d0208a726a5d1c0fd37324feba25506'



	وبذلك يمكننا استخدام هذه السلسلة النصية مثل مفتاح أمان.



	ولإعداد مفتاح أمان، سنضيف ضبط SECRET_KEY إلى التطبيق من خلال الكائن app.config، الذي سنضيفه مباشرةً بعد تعريف الكائن app وقبل تعريف المتغير messages‎، على النحو التالي:


# ...
app = Flask(__name__)
app.config['SECRET_KEY'] = 'your secret key'


messages = [{'title': 'Message One',
             'content': 'Message One Content'},
            {'title': 'Message Two',
             'content': 'Message Two Content'}
            ]
# ...


	ومن ثمّ نعدّل دالة العرض ()create لتبدو كما يلي:


# ...

@app.route('/create/', methods=('GET', 'POST'))
def create():
    if request.method == 'POST':
        title = request.form['title']
        content = request.form['content']

        if not title:
            flash('Title is required!')
        elif not content:
            flash('Content is required!')
        else:
            messages.append({'title': title, 'content': content})
            return redirect(url_for('index'))

    return render_template('create.html')


	تَمكَّنا باستخدام العبارة الشرطية التي توازن قيمة request.method مع القيمة POST من التحقُّق بأنّ التعليمات التالية لها لن تُنفّذ إلّا إذا كان الطلب الحالي هو فعلًا بطريقة POST، ومن ثمّ قرأنا قيم العنوان والمحتوى المرسلين من الكائن request.form الذي يمكِّننا من الوصول إلى بيانات نموذج الإدخال المُضمّنة في الطلب؛ ففي حال عدم إدخال قيمةٍ للعنوان، فسيتحقق الشرط if not title وبالتالي ستظهر رسالة للمستخدم نعلمه من خلالها بأن العنوان مطلوب وذلك باستخدام الدالة ()flash، وهذا ما يضيف هذه الرسالة إلى قائمة للرسائل الخاطفة والتي سنعرضها لاحقًا ضمن الصفحة بوصفها جزءًا من القالب الرئيسي "base.html"؛ وعلى نحوٍ مُشابه فيما يتعلّق بقسم المحتوى، ففي حال كان فارغًا، فسيتحقق الشرط elif not content وبالتالي ستظهر رسالة للمستخدم نعلمه من خلالها بأن المحتوى مطلوب، وستُضاف هذه الرسالة أيضًا إلى قائمة الرسائل الخاطفة.



	أمّا في حال وجود عنوان ومحتوى سليمين، فسيُضاف قاموس بايثون جديد إلى القائمة messages بالعنوان والمحتوى المدخلين من قبل المستخدم وذلك اعتمادًا على السطر البرمجي ({messages.append({'title': title, 'content': content، ومن ثمّ نعيد توجيه الطلب إلى الصفحة الرئيسية باستخدام الدالة redirect()‎ بتمرير الرابط الناتج عن التابع url_for()‎ الذي قد مررنا له القيمة index وسيطًا.



	ثمّ نحفظ الملف ونغلقه.



	ننتقل إلى الوجهة create/ عن طريق المتصفح كما يلي:


http://127.0.0.1:5000/create


	وبملء النموذج بعنوان اختياري ومحتوى ما، وحالما نرسل النموذج، ستظهر الرسالة الجديدة في الصفحة الرئيسية للتطبيق.



	ونهايةً سنعرّض كافّة الرسائل الخاطفة ضمن الصفحة الرئيسية للتطبيق، كما سنضيف رابطًا في شريط التصفح للقالب الرئيسي base.html، للانتقال إلى صفحة إضافة رسالة جديدة مباشرةً وبسهولة، لذا سنفتح ملف القالب الرئيسي:


(env)user@localhost:$ nano templates/base.html


	الآن، سنعدّل الملف من خلال إضافة وسم رابط  جديد بعد رابط تطبيق فلاسك المتوضّع في شريط التصفُّح داخل الوسم 
، ثمّ سنضيف حلقة تكرارية أعلى كتلة المحتوى مباشرةً لعرض الرسائل الخاطفة أسفل شريط التصفح، إذ يوفّر فلاسك هذه الرسائل من خلال دالة فلاسك الخاصة get_flashed_messages()‎، وسنضيف ضمن الوسم 


    
         href="{{ url_for('index') }}">FlaskApp
         href="{{ url_for('create') }}">Create
         href="#">About
    
    
     class="content">
        {% for message in get_flashed_messages() %}
             class="alert">{{ message }}

        {% endfor %}
        {% block content %} {% endblock %}
    




	ثمّ نحفظ الملف ونغلقه، وبإعادة تحميل الرابط "https://127.0.0.1:5000" في المتصفح، ستظهر الصفحة الرئيسية للتطبيق بشريط تصفُّح مُتضمّن للعنصر "Create" الذي يرتبط بالوجهة create/ الخاصّة بصفحة إنشاء رسالة جديدة.



	ولنرى كيفية عمل الرسائل الخاطفة، ننتقل إلى صفحة "Create" ونضغط على زر الإرسال في النموذج دون ملء أي من حقلي العنوان أوالمحتوى، فتظهر رسالة كما هو مبين بالشكل:



	



	وبالعودة إلى الصفحة الرئيسية نلاحظ أنّ الرسالة الخاطفة أسفل شريط التنقل قد اختفت، رغم عرضها على أنها جزء من القالب الأساسي، وهنا تكمن ميزتها، فلو لم تكن رسالة خاطفة لكانت ستُعرض في الصفحة الرئيسية أيضًا لأنها ترث من القالب الأساسي.



	ولو أرسلنا النموذج مع عنوان ومحتوى فارغ، فستظهر رسالة تفيد بأن حقل المحتوى مطلوب "!Content is required"، وبالضغط على رابط تطبيق فلاسك FlaskApp في شريط التصفُّح نعود إلى الصفحة الرئيسية للتطبيق؛ وهنا إذا ضغطنا في المُتصفّح على زر الرجوع، سنجد أن الرسالة الخاطفة المُتعلقّة بكون المحتوى فارغ لا تزال موجودة، ذلك لأنّ الطلب السابق هو المحفوظ حاليًا؛ أما لو انتقلنا إلى صفحة إنشاء رسالة جديدة من شريط التصفّح فسيُرسل طلب جديد، وبذلك تُمحى مُدخلات النموذج القديمة ومعها الرسالة الخاطفة.



	وبذلك نكون قد تعرّفنا على كيفية استلام مُدخلات المُستخدم والتحقّق من صحتها وإضافتها إلى مصدر البيانات (وهو قائمة بايثون في حالتنا).



	ملاحظة: ستختفي الرسائل المُضافة إلى الفائمة "messages" في التطبيق بمجرّد توقّف الخادم، لأنّ قوائم بايثون تُحفظ فقط في الذاكرة (المؤقتة)، أمّا لحفظ الرسائل بصورةٍ دائمة فلا بدّ من استخدام قاعدة بيانات مثل SQLite، وفي هذا الصدد ننصحك بقراءة المقال كيفية استخدام علاقة نوع واحد-إلى-متعدد one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite لمزيد من التفاصيل حول هذه الفكرة.



	الخاتمة



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



	ترجمة -وبتصرف- للمقال How To Use Web Forms in a Flask Application لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا




		المقال السابق: كيفية التعامل مع الأخطاء في تطبيقات فلاسك Flask
	
	
		كيفية استخدام القوالب في تطبيقات فلاسك Flask
	
	
		استخدام أطر العمل في برمجة تطبيقات الويب: فلاسك نموذجا
	




كيفية التعامل مع الأخطاء في تطبيقات فلاسك Flask
Wed, 05 Oct 2022 07:00:50 +0000




	يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا عدة أدوات وميزات من شأنها إنشاء تطبيقات ويب في لغة بايثون.



	ستواجه خلال تطوير تطبيقات الويب حتمًا حالاتٍ يعطي فيها تطبيقك نتائجًا مخالفةً لتوقعاتك، وذلك بسبب أخطاء من قبيل الكتابة الخاطئة لاسم أحد المتغيرات، أو الاستخدام الخاطئ لحلقة "for" التكرارية أو بناء عبارة "if" الشرطية بطريقة خاطئة مسبّبةً وقوع أحد استثناءات بايثون، كما في حال استدعاء دالة ما قبل التصريح عنها، أو البحث عن صفحة غير موجودة أصلًا، فممّا لا شكّ فيه أنّك ستجد تطوير تطبيقات الويب باستخدام فلاسك أسهل وأكثر مرونة حال تعلمّك لكيفية التعامل مع الأخطاء والاستثناءات.



	سنبني في هذا المقال تطبيق ويب مُصغّر بهدف تبيان كيفيّة التعامل مع الأخطاء الشائعة التي قد تواجهك أثناء تطوير تطبيقات الويب، كما سننشئ صفحات أخطاء مُخصّصة، وسنستخدم منقّح الأخطاء في فلاسك لاستكشاف الاستثناءات في حال حدوثها وإصلاحها، كما سنستخدم سجل الأحداث logging لتتبّع الأحداث في التطبيق بحثًا عن مصادر الأخطاء.



	مستلزمات العمل



	قبل المتابعة في هذا المقال لا بُدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
	
	
		الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات routes ودوال العرض view في فلاسك، وفي هذا الصدد يمكنك الاطلاع على المقال كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask من لغة بايثون لفهم مبادئ فلاسك.
	
	
		فهم أساسيات لغة HTML.
	


	الخطوة الأولى - استخدام منقح الأخطاء في فلاسك



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



	لذلك، وبعد التأكّد من تفعيل البيئة البرمجية وتثبيت فلاسك، سننشئ ملفًا ضمن المجلد "flask_app" باسم "app.py" لتحريره:


(env)user@localhost:$ nano app.py


	ونكتب ضمنه الشيفرة التالية:


from flask import Flask

app = Flask(__name__)


@app.route('/')
def index():
    return render_template('index.html')


	استوردنا في الجزء السابق من الشيفرة كائن فلاسك من حزمة falsk، ثم استخدمناه لإنشاء نسخةٍ فعليةٍ موجودةٍ في الذاكرة لتطبيق فلاسك Flask application instance باسم app، ثمّ أنشأنا دالة العرض ()index باستخدام المُزخرف ()app.route@، الذي يحوّل دوال بايثون الاعتيادية إلى دوال عرض، وفيها تكون القيمة المُعادة استدعاءً للدالة ()render_template، والتي تعرض بدورها قالب HTML المُسمى "index.html" في النتيحة. في هذه الشيفرة خطآن: الأوّل هو أنّنا لم نستورد دالة تصيّير القوالب ()render_template من حزمة فلاسك قبل استدعائها، والثاني أنّ قالب HTML المسمّى "index.html" غير موجود بعد.



	نحفظ الملف ونغلقه.



	والآن، لا بُدّ من إرشاد فلاسك إلى موقع التطبيق (في حالتنا الملف ذو الاسم app.py) وذلك باستخدام متغير بيئة فلاسك FLASK_APP على النحو التالي (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export):


(env)user@localhost:$ export FLASK_APP=app


	بعدها سنشغل خادم التطبيق باستخدام الأمر flask run:


(env)user@localhost:$ flask run


	فتظهر في نافذة الطرفية المعلومات التالية:


* Serving Flask app 'app' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)


	يحتوي الخرج السابق على عدة معلومات، مثل:




		اسم التطبيق المُشغَّل، وهو "app.py" في حالتنا.
	
	
		بيئة التشغيل الحالية التي يعمل عليها التطبيق، وهي في حالتنا بيئة الاستخدام الفعلي للتطبيق (نشر المنتج) "production"، وتُشدّد الرسالة التحذيرية هذه على كون الخادم غير مُخصّص لمرحلة نشر المنتج، وبما أنّنا نستخدمه بالواقع بغية تطوير التطبيق، فمن الممكن تجاهل الرسالة التحذيرية هذه.
	
	
		عبارة "Debug mode:off"، التي تشير إلى أن منقّح أخطاء فلاسك ليس قيد التشغيل، وبالتالي لن تتلقّى أي رسائل مفيدة حول الأخطاء الحاصلة في التطبيق، وهو أمرٌ طبيعي كوننا نعمل الآن في بيئة نشر المُنتج، فعرض رسائل تفصيلية بالأخطاء الحاصلة في هذه البيئة (نشر المنتج) يعرّض التطبيق لمخاطر أمنية ويعدّ ثغرة أمنية بحد ذاته.
	
	
		التطبيق يعمل على الرابط "/http://127.0.0.1:5000"، إذ أن "127.0.0.1" هو عنوان IP الذي يمثِّل الخادم المحلي localhost، و "5000:" هو رقم المنفذ، ولإيقاف تشغيل الخادم يمكنك الضغط على مفتاحي "CTRL+C"، ولكن لا توقفه الآن.
	


	الآن، وبالانتقال إلى الصفحة الرئيسية للتطبيق في المتصفّح عبر الرابط:


http://127.0.0.1:5000/


	ستظهر رسالة شبيهة بما يلي في الخرج:


Internal Server Error

The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.


	وهو خطأ الخادم الداخلي 500 Internal Server Error، الذي يمثّل استجابةً خاطئةً للخادم تشير لكونه يواجه خطأً داخليًا في شيفرة التطبيق.



	وسيظهر الخرج التالي في نافذة الطرفية:


[2021-09-12 15:16:56,441] ERROR in app: Exception on / [GET]
Traceback (most recent call last):
  File "/home/abd/.local/lib/python3.9/site-packages/flask/app.py", line 2070, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/abd/.local/lib/python3.9/site-packages/flask/app.py", line 1515, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/abd/.local/lib/python3.9/site-packages/flask/app.py", line 1513, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/abd/.local/lib/python3.9/site-packages/flask/app.py", line 1499, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**req.view_args)
  File "/home/abd/python/flask/series03/flask_app/app.py", line 8, in index
    return render_template('index.html')
NameError: name 'render_template' is not defined
127.0.0.1 - - [12/Sep/2021 15:16:56] "GET / HTTP/1.1" 500 -


	تمرُ عملية التعقّب العكسي أعلاه على الشيفرة المُسبّبة لخطأ الخادم الداخلي، إذ يشير السطر "NameError: name 'render_template' is not defined" إلى أصل المشكلة (خطأ في الاسم)، وهو في حالتنا أنّ الدالة ()render_template غير مستوردة ما جعلها غير مُعرّفة.



	وهنا نلاحظ أنّه لا بدّ من الذهاب إلى نافذة الطرفية لاكتشاف الأخطاء (وليس ضمن خرج التطبيق نفسه)، والذي يُعد أمرًا غير ملائم في الاستخدام الفعلي.



	فمن الممكن الحصول على تجربة استكشاف أخطاء وإصلاحها بطريقة أفضل وأسهل عبر تمكين وضع تنقيح الأخطاء في خادم التطوير، ولإجراء ذلك سنوقف عمل الخادم عبر الضغط على مفتاحي "CTRL+C"، ثمّ سنضبط متغير بيئة فلاسك FLASK_ENV على الوضع development، ما يمكنّنا من تشغيل البرنامج في وضع التطوير ( الذي يُمكِّن منقّح الأخطاء) كما يلي (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export):


(env)user@localhost:$ export FLASK_ENV=development


	نشغّل الآن خادم التطوير:


(env)user@localhost:$ flask run


	فيظهر في نافذة الطرفية خرجٌ مُشابه لما يلي:


* Serving Flask app 'app' (lazy loading)
 * Environment: development
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 120-484-907


	ومنه نلاحظ أنّ وضع التشغيل حاليًا هو وضع التطوير، وأنّ وضع تنقيح الأخطاء قيد التشغيل وبالتالي فإنّ مُنقّح الأخطاء مُفعّل، أمّا "Debugger PIN" فيمثّل الرمز السرّي اللازم لإلغاء قفل سجل المتصفّح (لوحة المراقبة) Browser console (وهي صَدفة shell بايثون تفاعلية يمكنك الوصول إليها بالضغط على رمز الطرفية الصغير المحاط بدائرة حمراء في الصورة أدناه).



	وبتحديث الصفحة الرئيسية للتطبيق ضمن المتصفح، ستظهر الصفحة بالشّكل التالي:



	



	وفي هذه الحالة نرى رسالة الخطأ بصياغة وطريقة عرض أسهل للفهم، إذ يشير العنوان الأوّل فيها إلى اسم استثناء بايثون المُتسبّب بالمشكلة (وهو خطأ في الاسم "NameError" في حالتنا).



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



	ملاحظة: يمكنّك رمز الطرفية الصغير المحاط بدائرة حمراء في الصورة السابقة من تشغيل الشيفرة المكتوبة أصلًا بلغة بايثون ضمن المُتصفّح في أُطر عمل مُختلفة (وهنا ضمن ما يشبه صَدفة بايثون التفاعلية ولكن ضمن المتصفح نفسه)، وهذا أمرٌ مفيدٌ للتحقّق مثلًا من قيمة متغير ما بنفس الطريقة التي تؤديها صَدفة بايثون التفاعلية. عند الضغط على هذه الأيقونة يجب إدخال الرمز السري الخاص بالمنقّح Debugger PIN الذي حصلت عليه عند تشغيل الخادم في الخطوة السابقة، ولكن ضمن محاور هذا المقال لن نحتاج إلى استخدامها.



	الآن، لإصلاح الخطأ في الاسم "NameError" الحاصل، نترك الخادم بحالة تشغيل ونفتح نافذة طرفية جديدة، وفيها نفعّل البيئة البرمجية ومن ثمّ نفتح الملف app.py لتحريره:


(env)user@localhost:$ nano app.py


	ونعدله ليصبح كما يلي:


from flask import Flask, render_template

app = Flask(__name__)


@app.route('/')
def index():
    return render_template('index.html')


	نحفظ الملف ونغلقه.



	استوردنا في الشيفرة السابقة دالة تصيّير القوالب ()render_template من حزمة فلاسك flask، الأمر الذي كان ناقصًا فيما سبق مُتسبّبًا بالخطأ الحاصل.



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


jinja2.exceptions.TemplateNotFound
jinja2.exceptions.TemplateNotFound: index.html


	وتشير رسالة الخطأ هذه لكون القالب "index.html" غير موجود.



	ولإصلاح هذا الخطأ، سننشئ ملف قالب باسم "base.html" لتتمكّن القوالب الأُخرى من وراثة شيفراته بغية تجنُّب تكرار الشيفرات، كما سننشئ القالب "index.html"، الذي سيرث من القالب الرئيسي.



	لذا سننشئ مجلد للقوالب باسم "templates" ضمن المجلد "flask_app"، إذ سيبحث فلاسك ضمنه عن القوالب، وبعدها سنفتح ملف القالب الأساسي المُسمى "base.html" باستخدام أي محرّر نصوص (هنا سنستخدم محرّر النصوص نانو nano:


(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html


	ثمّ نكتب الشيفرة التالية ضمن الملف base.html:



 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('index') }}">FlaskApp
         href="#">About
    
    
     class="content">
        {% block content %} {% endblock %}
    




	نحفظ الملف ونغلقه.



	يتضمّن القالب الأساسي كافّة الشيفرات المتداولة التي ستحتاجها في القوالب الأُخرى، وستُستبدل لاحقًا كتلة العنوان title بعنوان كل صفحة وكتلة المحتوى content بمحتواها، أمّا عن شريط التصفح فسيتضمّن رابطين، الأوّل ينقل المُستخدم إلى الصفحة الرئيسية للتطبيق باستخدام الدالة المساعدة ()url_for لتحقيق الربط مع دالة العرض ()index، والآخر لصفحة المعلومات حول التطبيق في حال قررت تضمينها في تطبيقك.



	لذا سنفتح ملف قالب index.html، الذي سيرث شيفراته من القالب الرئيسي:


(env)user@localhost:$ nano templates/index.html


	ونكنب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Index {% endblock %}h1>
    <h2>Welcome to FlaskApp!h2>
{% endblock %}


	ثمّ نحفظ الملف ونغلقه.



	وسّعنا في الشيفرة السابقة ملف القالب "base.html"، متجاوزين كتلة المحتوى content، ثمّ استخدمنا كتلة العنوان title لتعيين عنوان للصفحة وعرضه ضمن تنسيق عنوان من المستوى الأوّل H1، كما كتبنا الشيفرة اللازمة لعرض رسالة ترحيب ضمن تنسيق عنوان من المستوى الثاني H2.



	الآن وبعد التأكّد من كون خادم التطوير ما يزال قيد التشغيل، نحدّث الصفحة الرئيسية للتطبيق ضمن المتصفح، فنجد أنّ التطبيق لا يعرض أي أخطاء وأنّ الصفحة الرئيسية للتطبيق تبدو بالشكل المطلوب.



	ومع نهاية هذه الخطوة نكون قد استخدمنا وضع تنقيح الأخطاء وتعرفنا على كيفية التعامل مع رسائل الخطأ، وسنعمل في الخطوة التالية على إيقاف طلب ما ليستجيب برسالة خطأ من اختيارنا، وسنتعلّم كيفية إنشاء صفحات أخطاء مُخصّصة لتظهر بمثابة استجابة لطلبات معينة.



	الخطوة الثانية - تخصيص صفحات أخطاء



	سنتعرّف في هذه الخطوة على كيفية إلغاء طلب المستخدم في حال أراد الوصول إلى بيانات غير موجودة على الخادم والاستجابة برسالة خطأ HTTP من النوع 404، كما سنتعلّم كيفية إنشاء صفحات أخطاء مُخصّصة لتظهر بمثابة استجابة لأخطاء HTTP الشائعة، مثل خطأ الخادم الداخلي "‎500 Internal Server Error" وخطأ عدم توفّر البيانات المطلوبة "‎404 Not Found".



	ولنبيّن كيفية إلغاء طلب والاستجابة بصفحة خطأ مُخصّصة بخطأ HTTP من نوع 404، سننشئ صفحةً مهمتها عرض عدد من الرسائل، وفي حال طلب رسالة غير موجودة، ستستجيب بخطأ من النوع 404.



	لذا سنفتح الملف app.py لإضافة وجهةٍ route جديدة لصفحة الرسائل:


(env)user@localhost:$ nano app.py


	وسنضيف الوجهة التالية إلى نهاية الملف:


# ...

@app.route('/messages/')
def message(idx):
    messages = ['Message Zero', 'Message One', 'Message Two']
    return render_template('message.html', message=messages[idx])


	نحفظ الملف ونغلقه.



	استخدمنا في الشيفرة السابقة متغيرًا يدل على رقم مؤشّر الروابط باسم idx، والمُتضمّن رقم المؤشر الذي من شأنه تحديد الرسالة المطلوب عرضها، بمعنى أنّه إذا كان الرابط هو "‎/messages/0"، فهذا يعني أنّ الرسالة الأولى ذات المؤشّر بالقيمة صفر هي المطلوب عرضها؛ كما استخدمنا محوّل القيم int المسؤول عن قبول قيم من النوع "عدد صحيح موجب" فقط، ذلك لأنّ متحولات العناوين تكون افتراضيًا بنمط بيانات من النوع "سلاسل نصية".



	تتضمّن دالة العرض message()‎ قائمة بايثون اعتيادية باسم "messages" تحتوي على ثلاث رسائل (ولكن في الواقع العملي سيكون مصدر هذه الرسائل هو قاعدة البيانات، أو واجهة API، أو أي مصدر خارجي للبيانات، وليست مخزّنة يدويًا كما هو الحال في مثالنا التوضيحي هذا)، وفيها تكون القيمة المُعادة استدعاءً للدالة ()render_template مع وسيطين، هما: الملف "message.html" وسيطًا لملف القالب، والمتغير message الذي سيُمرّر بدوره إلى القالب، إذ تكون قيمة هذا المتغير هي أحد عناصر القائمة "messages" (أي إحدى الرسائل) وذلك تبعًا لقيمة المتغيّر idx الدال على رقم مؤشّر الرسالة المطلوبة والموجود ضمن الرابط.



	ومن ثمّ سننشئ ملف القالب "message.html":


(env)user@localhost:$ nano templates/message.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Messages {% endblock %}h1>
    <h2>{{ message }}h2>
{% endblock %}


	نحفظ الملف ونغلقه.



	وسّعنا في الشيفرة السابقة ملف القالب "base.html"، متجاوزين كتلة المحتوى content، ثمّ أضفنا عنوانًا وهو "Messages" ضمن تنسيق عنوان من المستوى الأوّل H1، كما عرضنا قيمة المتغير message المُتضمّن الرسالة المطلوبة حسب الرابط ضمن تنسيق عنوان من المستوى الثاني H2.



	الآن، ويعد التأكّد من كون خادم التطوير ما يزال قيد التشغيل، سنزور الروابط التالية تباعًا في المتصفح:


http://127.0.0.1:5000/messages/0
http://127.0.0.1:5000/messages/1
http://127.0.0.1:5000/messages/2
http://127.0.0.1:5000/messages/3


	ولدى زيارة الروابط الثلاث الأولى، ستظهر النصوص "Message Zero" و "Message One" و "Message Two" على الترتيب، ضمن تنسيق عنوان من المستوى الثاني H2، في حين سيستجيب الخادم برسالة الخطأ التفصيليّة "IndexError: list index out of range" لدى زيارة الرابط الرابع (والتي تعني أنّ رقم مؤشّر الرسالة المطلوبة خارج نطاق الرسائل المتوفرّة)، لأنّنا في وضع التطوير؛ ولو كنا نعمل في بيئة نشر المنتج (التشغيل الفعلي للتطبيق) لظهر خطأ الخادم الداخلي "‎500 Internal Server Error"، إلّا أنّ الاستجابة الأنسب لمثل هذه الحالة بغية الإيضاح للمُستخدم ماهية الخطأ الحاصل هي الاستجابة بخطأ "‎404 Not Found" دلالةً على أنّ الخادم غير قادر على إيجاد رسالة برقم مؤشّر مساوٍ للرقم "3".



	من الممكن استخدام دالة فلاسك المساعدة ()abort للاستجابة برسالة خطأ من النوع "404"، ولتطبيق هذا الأمر، سنفتح الملف app.py:


(env)user@localhost:$ nano app.py


	وفيه سنعدّل السطر الأوّل لنستورد دالة ()abort، ثمّ سنعدّل دالة العرض ()message بإضافة البنية "try … except" كما هو موضّح في الشيفرة التالية:


from flask import Flask, render_template, abort

# ...
# ...


@app.route('/messages/')
def message(idx):
    messages = ['Message Zero', 'Message One', 'Message Two']
    try:
        return render_template('message.html', message=messages[idx])
    except IndexError:
        abort(404)


	نحفظ الملف ونغلقه.



	استوردنا في الشيفرة السابقة دالة ()abort المُستخدمة في إلغاء طلب ما والاستجابة برسالة خطأ مُحدّدة، كما استخدمنا البنية "try … except" في الدالة ()message بغية تغليفها، إذ نحاول بدايةً الاستجابة لطلب المستخدم بالقالب messages المتضمّن الرسالة المطلوبة وفقًا لرقم المؤشّر المطلوب في الرابط، وفي حال عدم توفّر رسالة برقم مؤشّر موافق لذلك المطلوب، سيتحقّق الاستثناء except ونستخدمه لاكتشاف الخطأ مستخدمين استدعاء الدالة (abort(404 لإلغاء هذا الطلب الخاطئ والاستجابة له بخطأ HTTP من النوع 404 "‎404 Not Found".



	الآن ويعد التأكّد من كون خادم التطوير ما يزال قيد التشغيل، وباستخدام المتصفح سنزور الرابط الذي تسبّب بظهور رسالة الخطأ IndexError في المرة الماضية (أو أي رايط برقم مؤشّر أكبر من الرقم "2"):


http://127.0.0.1:5000/messages/3


	فتظهر لنا الاستجابة التالية في النتيجة:


Not Found

The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.


	وبذلك أصبح لدينا رسالة خطأ أفضل وأوضح تشير إلى عدم تمكُّن الخادم من إيجاد الرسالة المطلوبة.



	أمّا فيما يلي، فسنعمل على إنشاء قالب خاص بعرض صفحة بالخطأ من النوع 404 وآخر لعرض صفحة بالخطأ من النوع 500.



	بدايةً سنعرّف دالة باستخدام المُزخرف الخاص ()app.errorhandler مهمتها التعامل مع الخطأ من النوع 404، لذا سنفتح الملف "app.py" لتحريره:


nano app.py


	ونعدّل الملف ليصبح كما يلي:


from flask import Flask, render_template, abort

app = Flask(__name__)


@app.errorhandler(404)
def page_not_found(error):
    return render_template('404.html'), 404


@app.route('/')
def index():
    return render_template('index.html')


@app.route('/messages/')
def message(idx):
    messages = ['Message Zero', 'Message One', 'Message Two']
    try:
        return render_template('message.html', message=messages[idx])
    except IndexError:
        abort(404)


	نحفظ الملف ونغلقه.



	استخدمنا في الشيفرة السابقة المُزخرف ()app.errorhandler@ لتعريف الدالة ()page_not_found وتخصيصها للتعامل مع نوع خطأ بحد ذاته، إذ نمرّر لها نوع الخطأ مثل وسيط، وتكون القيمة المُعادة استدعاءً للدالة ()render_template مع القالب المُسمّى "404.html" الذي سننشئه لاحقًا وسيطًا لها؛ كما من الممكن تغيير اسم القالب بالاسم الذي نريد، لتكون بدورها القيمة المعادة من الدالة ()render_template هي الرقم الصحيح 404، وهذا يدل فلاسك على أنّ رمز الخطأ في الاستجابة يجب أن يكون "404"، وفي حال عدم تحديد أي رقم لدى استدعاء الدالة، فيستجيب فلاسك افتراضيًا بالرقم "200" الدال على نجاح الطلب.



	الآن، سنفتح ملف القالب المُسمّى "404.html":


(env)user@localhost:$ nano templates/404.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
        <h1>{% block title %} 404 Not Found. {% endblock %}h1>
        <p>OOPS! Sammy couldn't find your page; looks like it doesn't exist.p>
        <p>If you entered the URL manually, please check your spelling and try again.p>
{% endblock %}


	نحفظ الملف ونغلقه.



	في الشيفرة السابقة وكما هو الحال في جميع القوالب، وسّعنا ملف القالب "base.html" واستبدلنا محتويات كتلتي المحتوى content والعنوان title، وأضفنا أي شيفرات HTML نريدها، إذ أضفنا عنوانًا مُنسقًا وفق المستوى الأوّل من العناوين باستخدام الوسم 
، كما استخدمنا وسم فقرة  لإضافة رسالة خطأ مُخصّصة تُعلم المستخدم بكون الصفحة المطلوبة غير متوفرّة، إضافةً لرسالة تفيد أولئك المستخدمين الذين قد أدخلوا الرابط المطلوب يدويًا.



	كما من الممكن إضافة أي شيفرات HTML و CSS وجافا سكربت JavaScript نريدها لبناء وتنسيق صفحات الأخطاء، كما هو الحال في أي قالب آخر.



	الآن ويعد التأكّد من كون خادم التطوير ما يزال قيد التشغيل، سننتقل مُجدّدًا إلى الرابط:


http://127.0.0.1:5000/messages/3


	فتظهر الصفحة بشريط تصفُّح (الموروث من القالب الرئيسي) وبرسالة الخطأ المُخصّصة التي حددناها، وسنضيف بنفس الآلية صفحة خطأ مُخصّصة لأخطاء الخادم الداخلية "‎500 Internal Server Error"، لذا سنفتح الملف app.py لتحريره:


(env)user@localhost:$ nano app.py


	سنضيف الشيفرة المسؤولة عن التعامل مع الخطأ من النوع "500" أسفل تلك المسؤولة عن التعامل مع الخطأ من النوع "404"، كما يلي:


# ...

@app.errorhandler(404)
def page_not_found(error):
    return render_template('404.html'), 404


@app.errorhandler(500)
def internal_error(error):
    return render_template('500.html'), 500

# ...


	اعتمدنا في الشيفرة السابقة نفس الآلية المُتبعة للتعامل مع الخطأ 404، إذ استخدمنا المُزخرف ()app.errorhandler مع الرقم "500" مثل وسيط لإنشاء دالّة باسم ()internal_error للتعامل مع هذا النوع من الأخطاء. صيّر قالبًا باسم "500.html" ليستجيب برمز الخطأ ذو الرقم "500".



	والآن ولبيان كيفيّة عرض رسالة الخطأ المُخصّصة، سنضيف إلى نهاية الملف app.py وجهةً تستجيبُ بخطأ HTTP من النوع "500"، والذي سيعيد خطأ "‎500 Internal Server Error" سواءٌ كان منقّح الأخطاء قيد التشغيل أم لا:


# ...
@app.route('/500')
def error500():
    abort(500)


	أنشأنا في جزء الشيفرة السابق الوجهة ‎/500 واستخدمنا الدالة abort()‎ لإنشاء استجابة بخطأ HTTP من النوع "500".



	نحفظ الملف ونغلقه.



	ومن ثمّ سننشئ ملف القالب المُسمّى 500.html ضمن مجلد القوالب، كما يلي:


(env)user@localhost:$ nano templates/500.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
        <h1>{% block title %} 500 Internal Server Error {% endblock %}h1>
        <p>OOOOPS! Something went wrong on the server.p>
        <p>Sammy is currently working on this issue. Please try again later.p>
{% endblock %}


	ثمّ نحفظ الملف ونغلقه.



	اتبعنا في الشيفرة السابقة نفس الآلية المُتبعة في القالب 404.html، إذ وسّعنا ملف القالب base.html، واستبدلنا محتويات كتلة المحتوى content بعنوان ورسالتين مُخصّصتين لإعلام المستخدم حول خطأ الخادم الداخلي الحاصل.



	الآن، وبعد التأكّد من كون خادم التطوير ما يزال قيد التشغيل، سننتقل إلى الوجهة الجديدة التي تستجيب بالخطأ من النوع "500" عبر الرابط:


http://127.0.0.1:5000/500


	فستظهر صفحتنا المُخصّصة عوضًا عن صفحة الخطأ العامّة التي تظهر افتراضيًا.



	ومع نهاية هذه الخطوة نكون قد تعرفنا على كيفية استخدام صفحات أخطاء مُخصّصة لأخطاء HTTP في تطبيقات فلاسك. أمّا في الخطوة التالية فسنتعرّف على كيفية استخدام السجل لتتبّع الأحداث في التطبيق، والذي من شأنه تعزيز فهمنا لآلية عمل شيفرة التطبيق ما يساعد بدوره على تطوير التطبيق واكتشاف الأخطاء وإصلاحها.



	الخطوة الثالثة - استخدام السجل لتتبع أحداث التطبيق



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



	لقد سبق واطلعنا على سجل الأحداث عند كل تشغيل لخادم التطوير، والذي يبدو عادةً كما يلي:


127.0.0.1 - - [21/Sep/2021 14:36:45] "GET /messages/1 HTTP/1.1" 200 -
127.0.0.1 - - [21/Sep/2021 14:36:52] "GET /messages/2 HTTP/1.1" 200 -
127.0.0.1 - - [21/Sep/2021 14:36:54] "GET /messages/3 HTTP/1.1" 404 -


	إذ يتضمّن سجل الأحداث السابق المعلومات التالية:




		"127.0.0.1": عنوان المضيف الذي يعمل ضمنه الخادم.
	
	
		"[21/Sep/2021 14:36:45]": وقت وتاريخ الطلب.
	
	
		"GET": نوع طلب HTTP وهو في هذه الحالة من النوع "GET" المُستخدم لجلب البيانات.
	
	
		"messages/2/": المسار الذي طلبه المُستخدم.
	
	
		"HTTP/1.1": إصدار بروتوكول HTTP المُستخدَم.
	
	
		200 أو 404: رمز حالة الطلب.
	


	تساعد سجلات الأحداث هذه في تشخيص الأخطاء الحاصلة في التطبيق، كما من الممكن تسجيل مزيدٍ من المعلومات في سجلات الأحداث باستخدام مُسجّل الأحداث "app.logger" الذي يوفرّه فلاسك، وذلك بغية الحصول على معلومات تفصيلية حول طلباتٍ بحد ذاتها.



	يمكننا مع مُسجّل الأحداث هذا استخدام عدة دوال تعيد معلومات حول الأحداث باختلاف مستوياتها، إذ يدل كل مستوًى على حدثٍ ذي درجة معيّنة من الخطورة، ومن هذه الدوال:




		app.logger.debug()‎: للحصول على معلومات تفصيلية حول الحدث.
	
	
		app.logger.info()‎: للتأكّد من كون الأمور تسير على النحو السليم.
	
	
		app.logger.warning()‎: تشير لوقوع حدث غير متوقّع، مثل انخفاض مساحة القرص الصلب التخزينية، مع بقاء التطبيق يعمل على النحو السليم.
	
	
		app.logger.error()‎: تشير لوقوع خطأ في أحد أجزاء التطبيق.
	
	
		app.logger.critical()‎: يشير لوقوع خطأ حرج يعرّض كامل التطبيق للتوقف عن العمل.
	


	ولبيان كيفيّة استخدام سجّل الأحداث في فلاسك، سنفتح الملف app.py لتحريره بغية تسجيل بعض الأحداث:


(env)user@localhost:$ nano app.py


	سنعدّل الدالة ()message لتصبح كما يلي:


# ...

@app.route('/messages/')
def message(idx):
    app.logger.info('Building the messages list...')
    messages = ['Message Zero', 'Message One', 'Message Two']
    try:
        app.logger.debug('Get message with index: {}'.format(idx))
        return render_template('message.html', message=messages[idx])
    except IndexError:
        app.logger.error('Index {} is causing an IndexError'.format(idx))
        abort(404)

# ...


	نحفظ الملف ونغلقه.



	سجّلنا في الشيفرة السابقة عددًا من الأحداث من مستوياتٍ مختلفة، إذ استخدمنا الدالة ()app.logger.info لتسجيل حدث يعمل بصورةٍ سليمة (أي من مستوى المعلومات INFO)؛ كما استخدمنا الدالة ()app.logger.debug لتسجيل حدث بمعلوماتٍ تفصيلية (أي من مستوى التنقيح DEBUG) مشيرين لحصول التطبيق في هذا الحدث ضمن الطلب على رقم مؤشّر رسالة؛ ثمّ استخدمنا الدالة ()app.logger.error لتسجيل حقيقة كون الاستثناء IndexError قد تحقّق بسبب ورود رقم مؤشّر خاطئ مُسبّبًا حدوث الخلل (أي حدث من مستوى الخطأ ERROR، ذلك لأنّ خطأً ما قد حدث فعلًا).



	الآن وبزيارة الرابط:


http://127.0.0.1:5000/messages/1


	نحصل في الخرج على المعلومات التالية ضمن نافذة الطرفية التي يعمل ضمنها الخادم:


[2021-09-21 15:17:02,625] INFO in app: Building the messages list...
[2021-09-21 15:17:02,626] DEBUG in app: Get message with index: 1
127.0.0.1 - - [21/Sep/2021 15:17:02] "GET /messages/1 HTTP/1.1" 200 -


	وفيه نرى رسالة المعلومات INFO المُسجلّة من قبل الدالة ()app.logger.info، ورسالة التنقيح DEBUG المُسجّلة من قبل الدالة ()app.logger.debug والتي تبيّن رقم المؤشّر المطلوب.



	الآن وبزيارة رابط برقم مؤشّر خارج المجال المتوفّر، مثل:


http://127.0.0.1:5000/messages/3


	نحصل على الخرج التالي ضمن نافذة الطرفية:


[2021-09-21 15:33:43,899] INFO in app: Building the messages list...
[2021-09-21 15:33:43,899] DEBUG in app: Get message with index: 3
[2021-09-21 15:33:43,900] ERROR in app: Index 3 is causing an IndexError
127.0.0.1 - - [21/Sep/2021 15:33:43] "GET /messages/3 HTTP/1.1" 404 -


	وهنا نلاحظ أنّنا قد حصلنا على كل من سجلات INFO و DEBUG التي حصلنا عليها المرة الماضية ولكن مع سجل جديد لحدث خطأ ERROR بسبب طلب رسالة برقم مؤشّر غير موجود وهو الرقم "3" في مثالنا.



	لهذه الأحداث المُسجّلة والمعلومات التفصيلية والأخطاء المُسجلة الدور المهم في المساعدة على تحديد مكان حدوث الخطأ ما يجعل اكتشافه وإصلاحه أسهل.



	وبذلك ومع نهاية هذه الخطوة نكون قد تعلمنا كيفية التعامل مع مُسجّل الأحداث في فلاسك.



	الخاتمة



	تعرفنا في هذا المقال على كيفية استخدام وضع التنقيح في فلاسك، واكتشاف وإصلاح بعض الأخطاء الشائعة التي قد تواجهنا خلال تطوير تطبيق ويب باستخدام فلاسك، كما تعلمنا كيفية إنشاء صفحات أخطاء مُخصّصة لأخطاء HTTP الشائعة، ونهايةً استعرضنا كيفية استخدام مسجّل الأحداث الذي يوفرّه فلاسك لتتبع الأحداث في التطبيق ما يساعد على فحص سلوك التطبيق وفهمه.



	ترجمة -وبتصرف- للمقال How To Handle Errors in a Flask Application لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا




		المقال السابق: كيفية استخدام القوالب في تطبيقات فلاسك Flask
	
	
		استخدام أطر العمل في برمجة تطبيقات الويب: فلاسك نموذجا
	




كيفية استخدام القوالب في تطبيقات فلاسك Flask
Wed, 05 Oct 2022 07:50:02 +0000




	يُعد فلاسك إطار عمل للويب مبني بلغة بايثون، ويتميز بكونه صغير الحجم وسهل المعالجة، ويوفّر أيضًا عدة أدوات وميزات من شأنها جعل إنشاء تطبيقات الويب في لغة بايثون أسهل.



	عند تطوير تطبيق ويب ما، من الضروري الفصل بين ما يدعى "منطق العمل business logic" و"منطق العرض presentation logic"؛ إذ يكون منطق العمل مسؤولاً عن التعامل مع طلبات المستخدمين، مُخاطبًا قاعدة البيانات لإنشاء الاستجابة المناسبة؛ في حين يُحدّد منطق العرض كيفيّة عرض البيانات للمستخدم، وذلك غالبًا باستخدام ملفات HTML لإنشاء الهيكل الأساسي لصفحة الويب التي تستجيب لطلبات المستخدمين، مع استخدام تنسيقات CSS لتنسيق مظهر تلك المكونات المبنية باستخدام HTML.



	فمثلًا في حال كان لدينا تطبيق للتواصل الاجتماعي، فيوجد عادةً حقلٌ لإدراج اسم المستخدم وحقل لإدراج كلمة المرور بحيث لا يظهران إلّا في حال كون المستخدم لم يسجل دخوله إلى التطبيق بعد، ولدى كتابة المستخدم اسم المستخدم وكلمة المرور يعمل فلاسك على تطبيق منطق العمل، إذ تُستخرج البيانات (اسم المستخدم وكلمة المرور) من الطلب ليُسجَّل دخول المستخدم إذا كانت هذه البيانات صحيحة، وإلّا ستظهر رسالة خطأ، ويجري التعامل مع كيفية ظهور رسالة الخطأ بالاعتماد على منطق العرض.



	يستخدم فلاسك محرّك القوالب جينجا jinja لبناء صفحات HTML ديناميكيًا باستخدام مفاهيم بايثون المألوفة، من متغيراتٍ وحلقاتٍ تكرارية وقوائم وغيرها، وبالتالي ستُستخدم هذه القوالب على أنها جزءٌ من هذا المشروع، إذ يُعرّف القالب بأنه ملف يحتوي على مكونات ثابتة وأُخرى ديناميكية، وعندما يطلب المستخدم عنصرًا من التطبيق، مثل الصفحة الرئيسية، أو صفحة تسجيل الدخول، يُمكنّنا جينجا من الاستجابة باستخدام قالب HTML، وبذلك يصبح من الممكن استخدام عددٍ كبيرٍ من الميزات غير المتوفرة أصلًا في لغة HTML المعيارية، مثل المتغيرات والعبارة الشرطية "if" والحلقات التكرارية مثل حلقة "for"، والمُرشّحات filters ومفهوم وراثة القوالب، إذ تسمح لنا هذه الخواص بكتابة صفحات HTML سهلة الإصلاح، كما تعزل جينجا شيفرات HTML تلقائيًا بهدف منع هجمات البرمجة العابرة للمواقع Cross-Site Scripting -أو اختصارًا XSS-.



	سنبني في هذا المقال تطبيق ويب صغير يعمل على تصييّر عدّة ملفات HTML ضمن المتصفح معًا، إذ سنستخدم المتغيرات لتمرير البيانات من الخادم إلى القوالب، كما سنطبّق مفهوم وراثة القوالب لتجنُّب التكرار في الشيفرات البرمجية.



	وسنستخدم كذلك التعابير المنطقية في بناء شيفرات القوالب من عبارات شرطية وحلقات، وسنطبّق المُرشّحات اللازمة لتعديل النصوص، وسنعمل من خلال إطار العمل بوتستراب bootstrap على إضافة التنسيقات على التطبيق ليبدو أكثر جاذبية بصريًا.



	مستلزمات العمل



	قبل المتابعة في هذا المقال لا بُدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو "flask_app".
	
	
		توفّر إطار العمل فلاسك مُثبّت ضمن البيئة البرمجبة كما هو مُبيّن في الخطوة الأولى من المقال كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask والإصدار الثالث من لغة بايثون.
	
	
		الفهم الجيد لأساسيات فلاسك، مثل مفهوم الوجهات routes ودوال العرض view في فلاسك، ويمكنك في هذا الصدد الاطلاع على المقال كيفية بناء موقعك الإلكتروني الأول باستخدام إطار عمل فلاسك Flask والإصدار الثالث من لغة بايثون المشار إليه أعلاه لفهم مبادئ فلاسك.
	
	
		فهم أساسيات لغة HTML.
	


	الخطوة الأولى - تصيير القوالب واستخدام المتغيرات



	بعد التأكّد من تفعيل بيئة البرمجة وتثبيت فلاسك، سنبدأ ببناء التطبيق، إذ تتمثّل الخطوة الأولى بعرض رسالة ترحيب بالزوار في الصفحة الرئيسية، وسنستخدم لهذا الغرض دالة فلاسك المساعدة ()render_template لتوفير قوالب HTML مثل استجابة ضمن الصفحة، وسنتعلّم في هذا الصدد كيفيّة تمرير المتغيرات من التطبيق إلى القوالب.



	بدايةً نفتح الملف "app.py" الموجود في المجلد "flask_app" لتعديله وذلك باستخدام محرّر النصوص نانو "nano" أو أي محرر آخر تفضّله:


(env) user@localhost:$ nano app.py


	ونضيف الشيفرة التالية ضمنه:


from flask import Flask, render_template

app = Flask(__name__)


@app.route('/')
def hello():
    return render_template('index.html')


	نحفظ الملف ونغلقه.



	استوردنا في الشيفرة السابقة الصنف Flask الذي سنستخدمه لإنشاء نسخة من تطبيق باسم "app"، كما استوردنا الدالة ()render_template من حزمة flask، ثمّ عرفنا دالة العرض ()hello (وهي في الواقع دالة بايثون اعتيادية تعيد استجابةً من النمط HTTP) باستخدام المُزخرف ()app.route، الذي يحوّل دوال بايثون الاعتيادية إلى دوال عرض في فلاسك، تستخدم دالة العرض هذه الدالة ()render_template لتصييّر ملف قالب HTML المُسمّى "index.html".



	الآن، سننشئ القالب "index.html" ضمن المجلد الفرعي "templates" من المجلد الرئيسي "flask_app"، إذ سيبحث فلاسك عن القوالب في المجلد المسمّى "templates" تحديدًا، لذا يُعدُّ الاسم مهمًا. لإنشاء هذا المجلد، نتأكد من وجودنا ضمن المجلد "flask_app" وننفذ الأمر التالي:


(env) user@localhost:$ mkdir templates


	بعد ذلك، ننشئ ملفًا باسم "index.html" ضمن مجلد القوالب "templates" لنكتب ضمنه لاحقًا الشيفرات اللازمة، ومن الجدير بالملاحظة أنّه من غير الضروري التقيُّد باسم "index.html" على عكس اسم المجلد الرئيسي، فمن الممكن تغييّر اسم الملف ليصبح مثلًا "home.html"، أو "homepage.html"، أو أي اسم آخر تفضّله:


(env) user@localhost:$ nano templates/index.html


	ثمّ نضيف شيفرة HTML التالية داخل الملف "index.html":



 lang="en">

     charset="UTF-8">
    </span><span class="pln">FlaskApp</span><span class="tag">


    Hello World!
    Welcome to FlaskApp!




	اخترنا في الشيفرة السابقة عنوانًا للصفحة، كما أضفنا الرسالة "!Hello World" لتظهر ضمن تنسيق عنوان من المستوى الأوّل H1، والرسالة "!Welcome to FlasApp" لتظهر ضمن تنسيق عنوان من المستوى الثاني H2.



	نحفظ الملف ونغلقه.



	ولتشغيل تطبيق الويب الذي أنشأناه، وبعد التأكّد من وجودنا ضمن المجلد "flask_app" مع تفعيل البيئة الافتراضية، لا بُدّ من إرشاد فلاسك إلى موقع التطبيق (في حالتنا الملف ذو الاسم app.py) باستخدام متغير بيئة فلاسك FLASK_APP، ولتشغيله بوضع التطوير، نضبط متغير بيئة فلاسك Flask_ENV على الوضع development على النحو التالي (مع ملاحظة أنّنا نستخدم الأمر set في بيئة ويندوز عوضًا عن الأمر export):


(env) user@localhost:$ export FLASK_APP=app
(env) user@localhost:$ export FLASK_ENV=development


	بعدها سنشغل التطبيق باستخدام الأمر flask run:


(env) user@localhost:$ flask run


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


http://127.0.0.1:5000/


	فتظهر العبارة "FlasApp" عنوانًا للصفحة، ويجري تصييّر الرسالتين المكتوبتين في HTML لتظهرا بالتنسيق المطلوب.



	تُمرّر البيانات عادةً في تطبيقات الويب من ملفات بايثون الخاصة بالتطبيق إلى قوالب HTML، ولنوضّح كيفية فعل ذلك في تطبيقنا هذا، سنمرّر متغيرًا يحتوي على التاريخ والوقت وفق التوقيت العالمي UTC إلى القالب الرئيسي، وبعدها سنعرض قيمة هذا المتغير في القالب.



	سنترك خادم التطوير قيد التشغيل وسنفتح الملف app.py في نافذة أسطر أوامر جديدة للتعديل عليه:


(env) user@localhost:$ nano app.py


	سنستورد الوحدة الخاصّة بالتعامل مع الوقت والتاريخ datetime من مكتبة بايثون المعيارية وسنعدّل الدالة ()index ليبدو الملف كما يلي:


import datetime
from flask import Flask, render_template

app = Flask(__name__)


@app.route('/')
def hello():
    return render_template('index.html', utc_dt=datetime.datetime.utcnow())


	نحفظ الملف ونغلقه.



	استوردنا في الشيفرة السابقة الوحدة datetime ومرّرنا المتغير المُسمّى utc_dt مع قيمة ()datetime.datetime.utcnow التي تمثّل الوقت والتاريخ الحالي وفق التوقيت العالمي إلى القالب "index.html".



	ولعرض قيمة هذا المتغير في الصفحة الرئيسية، سنفتح الملف index.html من أجل التعديل عليه:


(env) user@localhost:$ nano templates/index.html


	وسنعدّل الملف كما يلي:



 lang="en">

     charset="UTF-8">
    </span><span class="pln">FlaskApp</span><span class="tag">


    Hello World!
    Welcome to FlaskApp!
    {{ utc_dt }}




	نحفظ الملف ونغلقه.



	أضفنا موضعًا لنص منسّق مثل عنوان من المستوى الثالث H3 مع استخدام المُحدّد الخاص "{{ … }}" لطباعة قيمة المتغيّر utc_dt ضمنه.



	الآن، بالذهاب إلى صفحة التطبيق الرئيسية ضمن المتصفح:


http://127.0.0.1:5000/


	ستظهر صفحة مشابهة للصورة التالية:



	



	ومع نهاية هذه الخطوة نكون قد أنشأنا صفحةً رئيسيةً ذات قالب HTML داخل تطبيق فلاسك، وصيّرنا محتويات قالب آخر، ومرّرنا وأظهرنا قيمة مُتغير، وفيما يلي سنتجنّب تكرار الشيفرات البرمجية باستخدام مفهوم وراثة القوالب.



	الخطوة الثانية – استخدام مفهوم وراثة القوالب



	سننشئ في هذه الخطوة قالبًا أساسيًا ذا محتوًى قابل للمشاركة مع القوالب الأُخرى، وسنعدّل قالب الصفحة الرئيسية index template للتطبيق ليرث من القالب الأساسي هذا، ثمّ سننشئ صفحةً جديدةً مسؤولةً عن عرض معلومات التطبيق للمستخدمين.



	يحتوي القالب الأساسي على أهم مكونات HTML المُستخدمة عادةً في أي قالب، مثل عنوان التطبيق وأشرطة التنقّل والتذييلات.



	بدايةً، سننشئ ملفًا جديدًا باسم "base.html" ضمن مجلد القوالب templates:


(env) user@localhost:$ nano templates/base.html


	وسنكتب ضمنه الشيفرات التالية:


DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{% block title %} {% endblock %} - FlaskApptitle>
    <style>
        nav a {
            color: #d64161;
            font-size: 3em;
            margin-left: 50px;
            text-decoration: none;
        }
    style>
head>
<body>
    <nav>
        <a href="#">FlaskAppa>
        <a href="#">Abouta>
    nav>
    <hr>
    <div class="content">
        {% block content %} {% endblock %}
    div>
body>
html>


	نحفظ الملف ونغلقه.



	الجزء الأكبر من الشيفرة السابقة هو تعليمات HTML معيارية تشمل عنوانًا وبعض التنسيقات لروابط التنقل، إضافةً إلى شريط تنقّل مع رابطين، أحدهما للوصول إلى الصفحة الرئيسية للتطبيق والآخر للوصول إلى صفحة المعلومات التي لم ننشئها بعد، إضافةً إلى عنصر الحافظة 
 ليتضمّن محتويات الصفحة. لا تعمل هذه الروابط بعد لكننا سنوضح في الخطوة التالية كيفية إنشاء الربط بين الصفحات.



	أمّا الأجزاء من الشيفرة الموضحّة فيما يلي فهي خاصةٌ بمحرك القوالب جينجا:




		{% block title %} {% endblock %}: كتلة برمجية تحجز مكانًا لعنوان الصفحة، الذي سنستخدمه لاحقًا في تحديد العنوان الخاص بكل صفحة في التطبيق دون الحاجة إلى إعادة كتابة قسم الترويسة  كاملًا في كل مرةٍ من أجل كل صفحة.
	
	
		{% block content %} {% endblock %}: كتلة برمجية أخرى ستُستبدل لاحقًا بالمحتوى الفعلي بالاعتماد على القالب الابن، أي القالب الذي يرث شيفرات القالب الرئيسي "base.html".
	


	والآن، بعد أن أصبح لديك قالبٌ رئيسي، يمكنك الاستفادة من ميزاته باستخدام فكرة الوراثة، لذلك افتح الملف "index.html":


(env) user@localhost:$ nano templates/index.html


	ثمّ استبدل محتوياته بما يلي:


{% extends 'base.html' %}

{% block content %}
    {% block title %} Index {% endblock %}
    Hello World!
    Welcome to FlaskApp!
    {{ utc_dt }}
{% endblock %}


	استخدمنا في هذه النسخة الجديدة من القالب template.html الوسم {% extends %} للوراثة من القالب الرئيسي base.html، وذلك عن طريق استبدال الشيفرة السابقة بكتلة المحتوى content في القالب الرئيسي.



	تحوي كتلة المحتوى هذه على وسم 
 وبداخله كتلة عنوان title تحتوي على العبارة "Index"، والتي بدورها تستبدل كتلة العنوان title الموجودة أصلًا في القالب الرئيسي base.html لتحتوي على العبارة "Index" وبذلك يصبح العنوان كاملًا "Index - FlaskApp"، وبهذه الطريقة نتفادى تكرار نفس النص مرتين، ذلك لأنّ هذا النص سيظهر في عنوان الصفحة وضمن الوسم  أسفل شريط التصفح الموروث من القالب الرئيسي.



	وبذلك يصبح لدينا عدة عناوين، الأوّل بتنسيق من المستوى الأوّل 
 يتضمّن النص "!Hello World"، والثاني بتنسيق من المستوى الثاني ، والثالث بتنسيق من المستوى الثالث  والذي يحتوي على قيمة متغير الوقت والتاريخ utc_dt.



	تمكنّنا وراثة القوالب من إعادة استخدام شيفرة HTML الموجودة في القوالب الأخرى (القالب الرئيسي base.html في حالتنا) دون الحاجة لتكراره في كل مرة.



	اِحفظ الملف وأغلقه، ثم حدِّث الصفحة الرئيسية index في المتصفح، فستظهر الصفحة بشريط تصفح وعنوانٍ منسقٍ كما يلي:



	



	أمّا الآن فسننشئ صفحة معلومات التطبيق، لذا سنفتح الملف "app.py" ولنضيف ضمنه وجهةً جديدةً:


(env) user@localhost:$ nano app.py


	ونضيف الوجهة التالية إلى نهايته:


# ...
@app.route('/about/')
def about():
    return render_template('about.html')


	استخدمنا المزخرف ()app.route لإنشاء دالة فلاسك باسم "()about"، إذ ترجع ضمنها نتيجة استدعاء الدالة ()render_template لدى تمرير اسم ملف القالب "about.html" وسيطًا لها.



	نحفظ الملف ونغلقه.



	الآن سننشئ ملف قالب باسم "about.html" كما يلي:


(env) user@localhost:$ nano templates/about.html


	ونضيف ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} About {% endblock %}h1>
    <h3>FlaskApp is a Flask web application written in Python.h3>
{% endblock %}


	استخدمنا في الشيفرة السابقة الوسم extend لوراثة الشيفرات من القالب الرئيسي، كما استبدلنا كتلة المحتوى content في القالب الرئيسي بوسم من النوع 
 الذي يعمل أيضًا بمثابة عنوان للصفحة، وأضفنا بعض المعلومات حول التطبيق ضمن وسم من النوع .



	نحفظ الملف ونغلقه.



	بعد التأكد من أنّ خادم التطوير ما يزال قيد التشغيل، ننتقل إلى الرابط التالي باستخدام المتصفح:


http://127.0.0.1:5000/about


	فتظهر صفحةٌ مشابهة للصورة التالية:



	



	نلاحظ وراثة شريط التنقل وجزءٍ من العنوان من القالب الأساسي.



	ومع نهاية هذه الخطوة نكون قد أنشأنا قالبًا أساسيًا واستخدمناه في بناء صفحة التطبيق الرئيسية وصفحة معلومات التطبيق لتجنُّب تكرار الشيفرات، إلّا أنّ الروابط في شريط التنقل ما تزال غير مُفعّلة ولا تؤدي أية مهمة حتى الآن، لذا سنربط في الخطوة سنربط بين الوجهات في القوالب من خلال تعديل الروابط في شريط التنقل.



	الخطوة الثالثة – الربط بين الصفحات



	سنتعلّم في هذه الخطوة كيفيّة الربط بين الصفحات باستخدام الدالة المساعدة ()url_for، إذ سنضيف رابطين إلى شريط التنقل في القالب الأساسي، أحدهما للوصول إلى الصفحة الرئيسية والآخر للوصول إلى صفحة معلومات التطبيق.



	بدايةً سنفتح القالب الأساسي لتعديله:


(env) user@localhost:$ nano templates/base.html


	ونعدّل الملف كما يلي:



 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('hello') }}">FlaskApp
         href="{{ url_for('about') }}">About
    
    
     class="content">
        {% block content %} {% endblock %}
    





	استخدمنا في الشيفرة السابقة دالة ()url_for خاصّة، والتي ستُعيد الرابط الموافق لدالة فلاسك المُمرّرة لها، إذ أنّ الرابط الأول مرتبط بالوجهة الخاصة بدالة فلاسك ()hello (وهي الصفحة الرئيسية للتطبيق)، في حين يرتبط الرابط الثاني بالوجهة الخاصة بدالة فلاسك ()about، مع ملاحظة أنّنا مرّرنا اسم دالة فلاسك وسيطًا وليس اسم الوجهة (/ أو about/).



	يساعد استخدام الدالة ()url_for لبناء الروابط على إدارتها على نحوٍ أفضل، فلو كتبنا الروابط بصورةٍمحددة وبتعليمات برمجية ثابتة فإنها ستفشل مع أول تعديل على الوجهات، في حين أنّه ومع استخدام الدالة ()url_for فمن الممكن التعديل على الوجهات مع ضمان محافظة الروابط على عملها الطبيعي المتوقع، ناهيك عن كون دالة ()url_for مسؤولة أيضًا عن أمور أُخرى مثل عزل المحارف الخاصة.



	نحفظ الملف ونغلقه.



	سنعود الآن إلى الصفحة الرئيسية ونجرّب الروابط الموجودة في شريط التنقل، فنجد أنها تعمل كما هو مطلوب.



	ومع نهاية هذه الخطوة نكون قد تعلمنا كيفية استخدام الدالة ()url_for للربط بين الوجهات في القوالب، وفيما يلي سنضيف بعض العبارات الشرطية للتحكم بما يُعرض في القوالب بناءً على الشروط التي نضعها، كما سنستخدم حلقات "for" التكرارية في قوالبنا لعرض عناصر القائمة.



	الخطوة الرابعة - استخدام العبارات الشرطية والحلقات التكرارية



	سنستخدم في هذه الخطوة العبارة الشرطية "if" في القوالب للتحكم بما سيُعرض بناءً على شروط محدّدة، كما سنستخدم حلقات "for" التكرارية للتنقّل بين عناصر قوائم بايثون وعرضها، ثمّ سنضيف صفحةً جديدةً إلى التطبيق مهمتها عرض التعليقات ضمن قائمة، بحيث تكون التعليقات ذات رقم الدليل الزوجي بخلفية زرقاء والتعليقات ذات رقم الدليل الفردي بخلفية رمادية.



	سننشئ بدايةً وجهةً جديدةً لصفحة التعليقات، لذا سنفتح الملف app.py للتعديل عليه:


(env) user@localhost:$ nano app.py


	ونضيف الوجهة التالية إلى نهاية الملف:


# ...

@app.route('/comments/')
def comments():
    comments = ['This is the first comment.',
                'This is the second comment.',
                'This is the third comment.',
                'This is the fourth comment.'
                ]

    return render_template('comments.html', comments=comments)


	لدينا في الوجهة السابقة قائمة مبنية في بايثون باسم comments تحتوي على أربعة عناصر (في التطبيق العملي يمكن الحصول على هذه التعليقات من قاعدة البيانات بدلاً من كتابتها يدويًا وتثبيتها ضمن الشيفرة)، لتكون القيمة المعادة هي تصيّير لملف قالب باسم "comments.html" وذلك في السطر الأخير من الشيفرة، ممررين المتغير comments الذي يحتوي القائمة مثل وسيط إلى ملف القالب.



	نحفظ الملف ونغلقه.



	بعدها ننشئ ملف جديد باسم comments.html ضمن مجلد القوالب templates للتعديل عليه:


(env) user@localhost:$ nano templates/comments.html


	ونضيف ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
        <div style="padding: 10px; background-color: #EEE; margin: 20px">
            <p style="font-size: 24px">{{ comment }}p>
        div>
        {% endfor %}
    div>
{% endblock %}


	وفيه توسعنا بالقالب الأساسي base.html واستبدلنا محتويات كتلة المحتوى content. واستخدمنا تنسيق عنوان من النمط 
 الذي سيعمل أيضًا بمثابة عنوانٍ للصفحة.



	كما استخدما حلقة for التكرارية وهي من ضمن تعليمات محرّك القوالب جينجا وذلك في السطر البرمجي {% for comment in comments %} بهدف التنقل بين التعليقات في القائمة comments المُخزنة ضمن المتغير المسمّى comment، إذ سنعرض التعليقات باستخدام الوسم 
{{ comment }}
، أي بنفس الآلية التي يُعرض فيها أي متغير في جينجا، مع ملاحظة أنّ نهاية حلقة for هنا تكون باستخدام الكلمة المفتاحية {% endfor %} الأمر المختلف عن طريقة بناء حلقات for في بايثون.



	نحفظ الملف ونغلقه.



	الآن وبعد التأكد من كون خادم التطوير ما يزال قيد التشغيل، نفتح المتصفح وننتقل إلى صفحة التعليقات باستخدام الرابط:


http://127.0.0.1:5000/comments


	فتظهر الصفحة بما يشبه التالي:



	



	الآن سنستخدم عبارة if الشرطية في القوالب لعرض التعليقات ذات رقم الدليل الفردي بخلفية رمادية والتعليقات ذات رقم الدليل الزوجي بخلفية زرقاء.



	لذا سنفتح ملف القالب comments.html:


(env) user@localhost:$ nano templates/comments.html


	ثمّ سنعدله ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index % 2 == 0 %}
                {% set bg_color = '#e6f9ff' %}
            {% else %}
                {% set bg_color = '#eee' %}
            {% endif %}

            <div style="padding: 10px; background-color: {{ bg_color }}; margin: 20px">
                <p>#{{ loop.index }}p>
                <p style="font-size: 24px">{{ comment }}p>
            div>
        {% endfor %}
    div>
{% endblock %}


	وفي هذا التعديل أضفنا عبارة if الشرطية في السطر {% if loop.index % 2 == 0 %}، إذ أنّ المتغير loop هو متغير خاص في جينجا يمكنّنا من الوصول إلى معلومات حول الحلقة الحالية، واستخدمنا loop.index للحصول على دليل العنصر الحالي، الذي يبدأ من "1" وليس من "0" كما هو الحال في قوائم بايثون.



	تتحقق عبارة if ما إذا كان الدليل زوجياً باستخدام عملية باقي القسمة %، إذ تُفحص قيمة باقي قسمة الدليل على الرقم "2"، فإذا كان الباقي يساوي "0"، فهذا يعني أن الدليل زوجي، وإلّا فيكون الدليل فرديًا. استخدمنا الوسم {% set %} للتعريف عن متغير باسم bg_color ليتضمّن لون الخلفية المطلوب، فإذا كان الدليل زوجيًا، نضبط قيمة هذا المتغير إلى اللون الأزرق، وإلّا وفي حال كون الدليل فرديًا نضبطها إلى اللون الرمادي، ثم نخصّص المتغير bg_color لضبط لون الخلفية للوسم 
 الحاوي على التعليق. نستخدم loop.index في أعلى النص الخاص بالتعليق لعرض رقم الدليل الحالي ضمن وسمٍ من النوع .



	نحفظ الملف ونغلقه.



	الآن بفتح المتصفح والانتقال إلى صفحة التعليقات كما يلي:


http://127.0.0.1:5000/comments


	ستظهر صفحة التعليقات الجديدة كما في الصورة:



	



	وضّحنا فيما سبق كيفية استخدام العبارة الشرطية if، ولكن من الممكن الحصول على نفس النتيجة باستخدام الدالة الخاصّة المساعدة ()loop.cycle في جينجا، ولتوضيح هذه النقطة سنفتح الملف "comments.html":


(env) user@localhost:$ nano templates/comments.html


	ونعدله ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            <div style="padding: 10px;
                        background-color: {{ loop.cycle('#EEE', '#e6f9ff') }};
                        margin: 20px">
                <p>#{{ loop.index }}p>
                <p style="font-size: 24px">{{ comment }}p>
            div>
        {% endfor %}
    div>
{% endblock %}


	حذفنا في هذه الشيفرة العبارة الشرطية "if/else" واستخدمنا عوضًا عنها الدالة المساعدة ('loop.cycle('#EEE', '#e6f9ff للتنقل بين اللونين، إذ ستكون قيمة المتغيّر background-color مساويةً للقيمة "‎#EEE" للون الرمادي مرّةً، ثمّ تتحول إلى القيمة "‎#e6f9ff" للون الأزرق مرةً أُخرى، وهكذا بالتناوب.



	نحفظ الملف ونغلقه.



	لدى فتح صفحة التعليقات في المتصفح وتحديثها، ستظهر صفحةٌ مشابهةٌ لتلك التي ظهرت مع استخدام عبارة "if" الشرطية.



	يمكن استخدام عبارات "if" الشرطية لأغراض مختلفة، بما في ذلك التحكم بما يُعرض على الصفحة، فعلى سبيل المثال لعرض جميع التعليقات باستثناء التعليق الثاني، يمكننا استخدام عبارة if بالشرط loop.index != 2 لترشيح التعليق الثاني.



	لذا سنفتح قالب التعليقات:


(env) user@localhost:$ nano templates/comments.html


	ونعدله ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index != 2 %}
                <div style="padding: 10px;
                            background-color: #EEE;
                            margin: 20px">
                    <p>#{{ loop.index }}p>
                    <p style="font-size: 24px">{{ comment }}p>
                div>
            {% endif %}
        {% endfor %}
    div>
{% endblock %}


	استخدمنا العبارة الشرطية {‎% if loop.index != 2 %‎} لعرض التعليقات ذات رقم الدليل غير المساوي للرقم "2"، ما يشمل جميع التعليقات باستثناء التعليق الثاني، كما استخدمنا شيفرةً ثابتةً لتغيير لون الخلفية بدلًا من استخدام الدالة المساعدة ()loop.cycle لتسهيل الأمور، أمّا بالنسبة لبقية أجزاء الشيفرة، فلم نجري عليها أي تغييرات، وأيضًا هنا تُنهى عبارة if الشرطية باستخدام الأمر {% endif %}.



	نحفظ الملف ونغلقه.



	سنلاحظ بتحديث صفحة التعليقات عدم ظهور التعليق الثاني.



	سنضيف الآن رابط يسمح للمستخدم بالانتقال إلى صفحة التعليقات مباشرةً من شريط التنقل، لذا سنفتح القالب الأساسي للتعديل عليه:


(env) user@localhost:$ nano templates/base.html


	وسنعدّل محتويات الوسم 
 بإضافة رابط جديد  إليه كما يلي:



 lang="en">

     charset="UTF-8">
    </span><span class="pln">{% block title %} {% endblock %} - FlaskApp</span><span class="tag">
    


    
         href="{{ url_for('hello') }}">FlaskApp
         href="{{ url_for('comments') }}">Comments
         href="{{ url_for('about') }}">About
    
    
     class="content">
        {% block content %} {% endblock %}
    





	استخدمنا الدالة المساعدة ()url_for للوصول إلى دالة فلاسك ()comments



	نحفظ الملف ونغلقه.



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



	وبذلك نكون قد تعلمنا كيفية استخدام العبارة الشرطية "if" في القوالب للتحكّم بما يُعرَض وفقًا لشروط معينة، كما استخدمنا حلقات "for" التكرارية للتنقل بين عناصر قوائم بايثون وعرض كل منها، وتعلمنا كيفية استخدام المتغير "loop" الخاص في جينجا، وسنستخدم في الخطوة التالية مرشّحات جينجا للتحكّم بكيفية عرض بيانات المتغير.



	الخطوة 5 – استخدام المرشحات



	سنتعلّم في هذه الخطوة كيفيّة استخدام مُرشحات جينجا في القوالب، إذ سنستخدم المُرشّح upper لتحويل كامل نصوص التعليقات التي أضفناها في الخطوة السابقة (أو الواردة من قاعدة البيانات في الواقع العملي) إلى حالة أحرف كبيرة، في حين سنستخدم المرشح join لربط عدّة سلاسل نصيّة لتصبح سلسلةً واحدة، كما سنتعرّف على كيفيّة تصيّير شيفرة HTML موثوقة وآمنة دون الحاجة لعزلها باستخدام المرشح safe.



	بدايةً سنعمل على تحويل التعليقات في صفحة التعليقات إلى حالة الأحرف الكبيرة، لذا سنفتح القالب "comments.html" للتعديل عليه:


(env) user@localhost:$ nano templates/comments.html


	ثمّ سنعدله ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index != 2 %}
                <div style="padding: 10px;
                            background-color: #EEE;
                            margin: 20px">
                    <p>#{{ loop.index }}p>
                    <p style="font-size: 24px">{{ comment | upper }}p>
                div>
            {% endif %}
        {% endfor %}
    div>
{% endblock %}


	أضفنا مرشح upper باستخدام رمز | الذي يمثل أنبوبًا pipe، والذي سيعمل على تعديل قيمة متغير comment إلى حالة الأحرف الكبيرة.



	نحفظ الملف ونغلقه.



	وبعد التأكد من كون خادم التطوير ما يزال قيد التشغيل، ننتقل إلى صفحة التعليقات باستخدام المتصفح:


http://127.0.0.1:5000/comments


	ونلاحظ أنّ جميع التعليقات أصبحت في حالة الأحرف الكبيرة بعد تطبيق المرشح، كما من الممكن تمرير وسطاء للمُرشّحات بين أقواسها. لتوضيح هذه النقطة: سنستخدم المُرشّح join لدمج جميع التعليقات الموجودة في القائمة comments ضمن سلسلة واحدة.



	لذا سنفتح قالب التعليقات:


(env) user@localhost:$ nano templates/comments.html


	ونعدله كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index != 2 %}
                <div style="padding: 10px;
                            background-color: #EEE;
                            margin: 20px">
                    <p>#{{ loop.index }}p>
                    <p style="font-size: 24px">{{ comment | upper }}p>
                div>
            {% endif %}
        {% endfor %}
        <hr>
        <div>
            <p>{{ comments | join(" | ") }}p>
        div>
    div>
{% endblock %}


	أضفنا في الشيفرة السابقة الوسم 
 (الذي يُصيّر مثل فاصل أفقي)، والوسم  (الذي يُستخدم لأغراض التنسيق وتجميع العناصر)، إذ دمجنا جميع التعليقات الموجودة في القائمة comments باستخدام المُرشّح ()join.



	نحفظ الملف ونغلقه.



	وبتحديث صفحة التعليقات ستظهر كما يلي:



	



	نلاحظ عرض كافّة محتويات القائمة comments بحيث تكون التعليقات مفصولة عن بعضها برمز الشريط العمودي pipe وهي القيمة المُمررة وسيطًا إلى المُرشّح ()join.



	ومن المُرشّحات المهمّة الأُخرى المُرشّح safe الذي يساعد في تصيّير شيفرة HTML موثوقة في المتصفح، ولتوضيح ذلك سنضيف نصًا يحتوي على وسم HTML ما إلى قالب التعليقات (لنرى هل سيُصيّر في المُتصفّح أم سيُعامل على أنه نص عادي) باستخدام مُحدّد جينجا "{{ }}". نحصل في التطبيق العملي على هذا النص (التعليق) مثل متغير آتٍ من الخادم، ومن ثمّ سنعدّل وسيط المُرشّح ()join ليكون وسم 
 (أي الفصل بين التعليقات بشريط أفقي) بدلًا من الشريط العمودي pipe.



	لذا سنفتح قالب التعليقات:


(env) user@localhost:$ nano templates/comments.html


	ونعدّله ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index != 2 %}
                <div style="padding: 10px;
                            background-color: #EEE;
                            margin: 20px">
                    <p>#{{ loop.index }}p>
                    <p style="font-size: 24px">{{ comment | upper }}p>
                div>
            {% endif %}
        {% endfor %}
        <hr>
        <div>
            {{ "COMMENTS
" }}
            <p>{{ comments | join(" 
 ") }}p>
        div>
    div>
{% endblock %}


	أضفنا القيمة 
COMMENTS
 وغيرنا وسيط مُرشّح الدمج ليصبح وسم .



	نحفظ الملف ونغلقه.



	وبتحديث صفحة التعليقات تظهر صفحةٌ مشابهةٌ لما يلي:



	



	نلاحظ أنّ وسوم HTML التي أضفناها ضمن التعليقات لم تُصيَّر، وهي ميزة أمان مهمّة في جينجا، لأنّ وسوم HTML قد تكون ضارة أو خبيثة، ويمكن أن تؤدي إلى هجمات البرمجة العابرة للمواقع XSS.



	أمّا لتصيير وسوم HTML المُضافة السابقة نفتح ملف قالب التعليقات:


(env) user@localhost:$ nano templates/comments.html


	ونعدله بإضافة المُرشّح safe، للدلالة على أنّ هذه الوسوم آمنة ونريد تصييّرها:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Comments {% endblock %}h1>
    <div style="width: 50%; margin: auto">
        {% for comment in comments %}
            {% if loop.index != 2 %}
                <div style="padding: 10px;
                            background-color: #EEE;
                            margin: 20px">
                    <p>#{{ loop.index }}p>
                    <p style="font-size: 24px">{{ comment | upper }}p>
                div>
            {% endif %}
        {% endfor %}
        <hr>
        <div>
            {{ "COMMENTS
" | safe }}
            <p>{{ comments | join(" 
 ") | safe }}p>
        div>
    div>
{% endblock %}


	نلاحظ أنّه من الممكن ربط المُرشّحات كما هو ظاهر في السطر:


{{ comments | join(" 
 ") | safe }}


	إذ يُطبَّق كل مُرشّح على نتيجة خرج المُرشّح السابق له.



	نحفظ الملف ونغلقه.



	وبتحديث صفحة التعليقات نجد أن وسوم HTML قد جرى تصييّرها كما هو مُتوقّع مع استخدام المُرشّح "safe":



	



	تنبيه: قد يجعل تطبيق المُرشّح "safe" لشيفرة HTML غير موثوقة المصدر تطبيقنا عرضةً لهجمات البرمجة عابرة المواقع، لذا لا يُفضّل استخدامه إلّا إذا كانت شيفرات HTML المُراد تصييّرها موثوقة المصدر.



	تعرّفنا في هذه الخطوة على كيفيّة استخدام المُرشّحات في قوالب جينجا لتعديل قيم المتغيرات، وفيما يلي سنستخدم حزمة بوتستراب Bootstrap لتنسيق مظهر التطبيق وجعله أكثر جاذبية بصريًا.



	الخطوة السادسة – استخدام بوتستراب



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



	يساعد إطار العمل بوتستراب bootstrap على إضافة التنسيقات على التطبيق ليبدو أكثر جاذبية بصريًا، كما سيساعدنا على تمكين ميزة الصفحات المتوافقة مع المتصفحات في تطبيق الويب، ما يضمن عمله بصورةٍ جيدة في المتصفحات الخاصة بالجوال، دون كتابة شيفرات HTML و CSS وجافا سكربت JavaScript لتحقيق هذه الغاية.



	وحتّى نستخدم بوتستراب سنضيفه إلى القالب الأساسي بحيث يسهل استخدامه في جميع القوالب الأُخرى.



	لذا سنفتح القالب الأساسي "base.html" للتعديل عليه:


(env) user@localhost:$ nano templates/base.html


	ونعدله كما يلي:


doctype html>
<html lang="en">
  <head>
    
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-KyZXEAg3QhqLMpG8r+8fhAXLRk2vvoC2f3B09zVXn8CA5QIVfZOJ3BCsw2P0p/We" crossorigin="anonymous">

    <title>{% block title %} {% endblock %} - FlaskApptitle>
  head>
  <body>
    <nav class="navbar navbar-expand-lg navbar-light bg-light">
    <div class="container-fluid">
        <a class="navbar-brand" href="{{ url_for('hello') }}">FlaskAppa>
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
        <span class="navbar-toggler-icon">span>
        button>
        <div class="collapse navbar-collapse" id="navbarNav">
        <ul class="navbar-nav">
            <li class="nav-item">
              <a class="nav-link" href="{{ url_for('comments') }}">Commentsa>
            li>
            <li class="nav-item">
              <a class="nav-link" href="{{ url_for('about') }}">Abouta>
            li>
        ul>
        div>
    div>
    nav>
    <div class="container">
        {% block content %} {% endblock %}
    div>

    

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-U1DAWAznBHeqEIlVSCgzq+c9gqGAJn5c/t99JyeKa9xxaYpSvHU5awsuZVVFIhvj" crossorigin="anonymous">script>

  body>
html>


	الجزء الأكبر من الشيفرة السابقة هو تعليمات لازمة لعمل بوتستراب، إذ تزوّد الوسوم  متصفح الويب بالمعلومات، في حين ينشئ الوسم  ضمن القسم  ارتباطًا إلى ملفات CSS الخاصة ببوتستراب، وفي الجزء الأخير منه يُضمِّن الوسم 
     src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
     src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
  



	الجزء الأكبر من الشيفرة السابقة هو تعليمات HTML معيارية وشيفرات لازمة لعمل بوتستراب، إذ تزوّد الوسوم  متصفح الويب بالمعلومات، في حين ينشئ الوسم  ارتباطًا إلى ملفات CSS الخاصة ببوتستراب، ويضمِّن الوسم 
     src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
     src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
  



	أضفنا في الشيفرة السابقة عنصر قائمة 
 إلى شريط التصفح واستخدمنا فيه الدالة ()url_for لتأمين الربط مع دالة فلاسك ()create، وهذا ما يضمن الوصول إلى صفحة إنشاء ملاحظة جديدة من شريط التصفح.



	الآن شغّل خادم التطوير إن لم يكن مُشغّلًا أصلًا باستخدام الأمر التالي:


(env)user@localhost:$ flask run


	الآن، استخدم الرابط "http://127.0.0.1:5000/create" في المتصفّح وأضف الملاحظة التالية المُنسقّة باستخدام مارك داون:


### Flask
Flask is a **web** framework for _Python_.

Here is the Flask logo:

![Flask Logo](https://flask.palletsprojects.com/en/1.1.x/_images/flask-logo.png)


	يتضمّن تنسيق مارك داون للملاحظة السابقة عنوانًا من المستوى الثالث h3 ويجعل كلمة web بخط غامق وكلمة python بخط مائل، كما يتضمّن صورة.



	وبتأكيد الملاحظة وإرسالها سيحوّل التطبيق التنسيقات إلى مقابلاتها في HTML لتظهر بالشكل التالي:



	



	الخاتمة



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



	وربطنا التطبيق مع قاعدة بيانات SQLite لحفظ البيانات وجلبها، إذ سيفسّر التطبيق النصوص المُنسقّة باستخدام ماركداون إلى مقابلاتها من شيفرات HTML ليتمكّن المتصفح من تصييّرها بشكلها المطلوب.



	ترجمة -وبتصرف- للمقال How To Use Python-Markdown with Flask and SQLite لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا



	
		المقال التالي: تخديم تطبيقات فلاسك باستخدام خادمي الويب uWSGI و Nginx
	
	
		أهم 8 مكتبات بلغة البايثون تستخدم في المشاريع الصغيرة
	
	
		إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask من لغة بايثون
	
	
		كيف ومتى نستخدم SQLite
	
	
		التعامل مع قواعد البيانات SQLite في تطبيقات Flask
	




بناء مختصر روابط باستخدام إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite
Mon, 25 Jul 2022 16:00:01 +0000




	يُعد فلاسك إطار عمل لبناء تطبيقات الويب مبني باستخدام لغة بايثون، أما SQLite، فهو محرك قواعد بيانات يُستخدم مع بايثون لتخزين بيانات التطبيقات. سنبني في هذا المقال مختصِرًا للروابط URL shortener ليحوّل أي رابط إلى آخر مُختصَر وأكثر موثوقية بما يشبه مبدأ عمل موقع bit.ly.



	سنستخدم في بناء تطبيقنا مكتبة التعمية Hashids لتوليد سلاسل فريدة لمُعرّفات الروابط؛ إذ أن هذه المكتبة مُختصّةٌ بتوليد مُعرّفات مميزة قصيرة unique ID انطلاقًا من أرقام صحيحة، إذ تحوّل مثلاً الرقم "12" إلى سلسلة فريدة مثل "1Xcld".



	يمكن استخدام السلاسل الفريدة هذه لتوليد معرّفات لا يمكن التنبؤ بها سواءٌ للفيديوهات على مواقع مشاركة الفيديوهات، أو الصور في خدمة رفع الصور وغيرها. ففي حال وصول المستخدم مثلًا إلى صورةٍ ذات رابط "your_domain/image/J32Fr"، فلا يمكنه التنبؤ بمواقع الصور الأخرى، على عكس حالة استخدام معرفّات مؤلفّة من أرقام صحيحة في مختصر الروابط، فمثلاً لو كان رابط الصورة "your_domain/image/33"، فسيتمكن المستخدم من التنبؤ بمواقع الصور الأخرى بسهولة، وبالتالي يقدِّم استخدام روابط بمعرّفات غير قابلة للتنبؤ نوعًا من الخصوصية للخادم، كونها تمنع المستخدمين من اكتشاف الروابط المختصرة المُستخدمة من قِبل المستخدمين الآخرين.



	سنبني إذًا مختصِرًا للروابط باستخدام فلاسك وSQLite ومكتبة Hashids، بحيث يتمكّن المستخدمون من إدخال روابط وتوليد نسخٍ مختصرةٍ منها، إضافةً إلى توفير صفحة إحصاءات يمكن للمستخدمين من خلالها متابعة عدد مرات زيارة الرابط، كما سنستخدم بوتستراب bootstrap لإضافة التنسيقات للتطبيق.



	مستلزمات العمل



	قبل المتابعة في هذا المقال لا بدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، مثبّتة على حاسوبك، وسنفترض في مقالنا أن اسم مجلد المشروع هو flask_shortener.
	
	
		فهم مبادئ فلاسك، مثل بناء الوجهات وإخراج نماذج HTML والاتصال بقواعد بيانات SQLite، ويمكنك الاطلاع على [هذا المقال](رابط المقال الأوّل بعد نشره) لمزيدٍ من المعلومات حول هذه النقاط.
	


	الخطوة الأولى- إعداد المتطلبات



	سنفعّل في هذه الخطوة بيئة بايثون ونثبّت فلاسك باستخدام مثبِّت الحزم pip، ثم سننشئ قاعدة بيانات سنستخدمها لتخزين الروابط، وفي حال كون بيئة البرمجة غير مفعّلة بعد، سنستخدم الأمر التالي لتفعيلها:


$ source env/bin/activate


	وبعد تفعيل بيئة البرمجة، سنثبّت فلاسك ومكتبة Hashids باستخدام الأمر التالي:


(env)user@localhost:$ pip install flask hashids



	ثمّ سننشئ ملف تخطيط قاعدة البيانات باسم schema.sql، ليحتوي أوامر SQL اللازمة لإنشاء جدول للعناوين باسم urls.



	لذا، سننشئ الملف schema.sql داخل المجلد flask_shortener كما يلي:


(env)user@localhost:$ nano schema.sql


	ونكتب أوامر SQL التالية فيه:


DROP TABLE IF EXISTS urls;

CREATE TABLE urls (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    original_url TEXT NOT NULL,
    clicks INTEGER NOT NULL DEFAULT 0
);


	أول سطرٍ من شيفرة SQL السابقة مسؤولٌ عن حذف أي جداول موجودةٍ سابقًا ضمن قاعدة البيانات urls، وبذلك لن يكون هناك أي سلوك متضارب أو عشوائي ناجمٍ عن تشابه الأسماء ضمن قاعدة البيانات، والجدير بالملاحظة أنّ تطبيق هذين الأمر سيؤدي إلى حذف كامل محتوى قاعدة البيانات الحالي، لذا لا تُدخل أي بياناتٍ مهمّة في التطبيق حتى تنتهي من كافّة الخطوات التعليميّة في المقال وتجربة نتائجه النهائية.



	بعد ذلك، سننشئ جدولًا يحتوي الأعمدة التالية:




		"id": ويحتوي بياناتٍ من نوع رقم صحيح ويمثِّل المعرّف الفريد لكل رابطٍ مُدخل، وسنستخدم هذا المعرّف لاحقًا في استنتاج الرابط الأصلي من سلسلة محارف عشوائية معمّاة Hash string.
	
	
		"created": يحتوي على تاريخ ووقت اختصار الرابط.
	
	
		"original_url": يحتوي على الرابط الكامل الأصلي قبل الاختصار والذي سيُعاد توجيه المستخدمين إليه.
	
	
		"clicks": يحتوي على عدد مرات النقر على الرابط. ستكون قيمته الابتدائية 0، وتزداد مع كل إعادة توجيه.
	


	اِحفظ الملف وأغلقه.



	الآن لتنفيذ ملف schema.sql المسؤول عن بناء جدول الروابط urls، سننشئ ملفًا باسم int_db.py داخل مجلد flasks_hortener:


(env)user@localhost:$ nano init_db.py


	ونضيف الشيفرة التالية إليه:


import sqlite3

connection = sqlite3.connect('database.db')

with open('schema.sql') as f:
    connection.executescript(f.read())

connection.commit()
connection.close()


	إذ يحدث في البداية اتصالٌ مع الملف database.db المُنشأ تلقائيًا عند تنفيذ البرنامج السابق، ويمثّل هذا الملف قاعدة البيانات التي ستخزّن كامل بيانات التطبيق، ثم يُفتح بعد ذلك ملف تخطيط قاعدة البيانات schema.sql ويُشغَّل باستخدام التابع ()executscript القادر على تنفيذ عدّة تعليمات SQL معًا، وهذا ما سينشئ بالنتيجة جدول الروابط urls، وفي النهاية نؤكِّد على التغييرات ويُغلق الاتصال مع قاعدة البيانات.



	اِحفظ الملف وأغلقه.



	الآن، نشغّل البرنامج:


(env)user@localhost:$ python init_db.py


	وبعد انتهاء تنفيذه، سيظهر ملفٌ جديدٌ باسم database.db ضمن المجلد flask_shortener.



	وبنهاية الخطوة الأولى، نكون قد ثبّتنا فلاسك ومكتبة Hashids، وأنشأنا مخطّط قاعدة البيانات إضافةً لقاعدة بيانات SQLite تحتوي جدولًا باسم "urls" مخصّصًا لتخزين العناوين الأصلية لتلك المُختصرة.



	سنستخدم فيما يلي فلاسك لإنشاء الصفحة الرئيسية index والتي سيتمكّن المستخدمون من خلالها من إدخال الروابط المطلوب اختصارها.



	الخطوة الثانية - إنشاء الصفحة الرئيسية لتطبيق اختصار الروابط



	سننشئ في هذه الخطوة الوجهة اللازم لعمل الصفحة الرئيسية index، والذي يمكّن المستخدمين من إدخال الروابط الأصلية المراد اختصارها؛ إذ ستُخزَّن هذه الروابط في قاعدة البيانات بدايةً، ويستخدم المعرّف الفريد للرابط لتوليد سلسلة محارف قصيرة معمّاة باستخدام مكتبة Hashids، ويبني الرابط المُختصر ويخرجه نتيجةً.



	سننشئ الآن الملف الأساسي لتطبيق فلاسك باسم app.py ضمن المجلد flask_shortener:


(env)user@localhost:$ nano app.py


	ونضيف الشيفرة التالية ضمنه:


import sqlite3
from hashids import Hashids
from flask import Flask, render_template, request, flash, redirect, url_for


def get_db_connection():
    conn = sqlite3.connect('database.db')
    conn.row_factory = sqlite3.Row
    return conn


	نبدأ بالشيفرة السابقة باستيراد الوحدة sqlite3، والصنف Hashids من المكتبة hashids، إضافةً للمساعد الخاص بإطار فلاسك، ثم تفتح الدالة ()get_db_connection اتصالًا مع ملف قاعدة البيانات database.db، وتعيّن قيمة السمة row_factory لتكون sqlite3.Row لنتمكّن من الوصول لأعمدة جدول قاعدة البيانات باستخدام أسمائها؛ وهذا يعني أنّ اتصال قاعدة البيانات سيعيد سجلات يمكننا التعامل معها كما هو الحال مع قواميس بايثون Dictionaries الاعتيادية (وحدات تخزين القيم المنظمّة في بايثون)، وفي النهاية تعيد الدالة كائن الاتصال conn، الذي سيُستخدم للوصول إلى قاعدة البيانات.



	سنضيف الآن الشيفرة التالية:


. . .
app = Flask(__name__)
app.config['SECRET_KEY'] = 'this should be a secret random string'

hashids = Hashids(min_length=4, salt=app.config['SECRET_KEY'])


	التي تنشئ كائن تطبيق فلاسك وتحدِّد مفتاح الأمان لجعل الجلسات آمنة، وبما أنّ مفتاح الأمان هو أيضًا سلسلة محارف عشوائية وسريّة، فسنستخدمها مصدرًا لمحارف الإغفال salt لمكتبة التعمية Hashids بما يضمن كون السلاسل المعمّاة الناتجة غير قابلة للتنبؤ كونها ستتغير بتغيّر محارف الإغفال المتغيرة أصلًا باستمرار مع تغيُّر مفتاح الأمان.



	
		اقتباس
	

	
		
			ملاحظة: محارف الإغفال salt هي سلاسل عشوائية تُزوَّد بها دالة التعمية ()hashids.encode، بحيث تكون السلسلة المعمّاة الناتجة مبنيةً باستخدام محارف الإغفال هذه، بما يضمن كون السلاسل الناتجة فريدةً وغير قابلةٍ للتخمين، مثل مبدأ كلمات المرور السرية والتي لا يستخدمها سوى مالكها لتشفير وفك تشفير السلاسل المعمّاة.
		
	



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



	وبذلك نكون أنشأنا كائن تعمية hashids يضمن كون كل سلسلة معمّاة مؤلفّة من 4 محارف على الأقل عبر تمرير هذه القيمة إلى المعامل min_length من هذا الكائن، واستخدمنا مفتاح أمان التطبيق مثل محرف إغفال.



	سنضيف الآن الشيفرة التالية إلى نهاية الملف:


. . .
@app.route('/', methods=('GET', 'POST'))
def index():
    conn = get_db_connection()

    if request.method == 'POST':
        url = request.form['url']

        if not url:
            flash('The URL is required!')
            return redirect(url_for('index'))

        url_data = conn.execute('INSERT INTO urls (original_url) VALUES (?)',
                                (url,))
        conn.commit()
        conn.close()

        url_id = url_data.lastrowid
        hashid = hashids.encode(url_id)
        short_url = request.host_url + hashid

        return render_template('index.html', short_url=short_url)

    return render_template('index.html')


	يعدِّل المزخرف app.route@ دوال بايثون المألوفة لتصبح دوالًا عاملةً في فلاسك مثل الدالة ()index، التي تُحوَّل القيمة المعادة منها إلى استجابةٍ من نوع HTTP تُعرض لدى عميل HTTP الذي قد يكون متصفحًا مثلًا.



	وضمن بناء دالة فلاسك ()index، سنمرّر السطر التالي:


methods=('GET', 'POST')



	الحاوي على طرائق الطلبات المقبولة إلى وسيط الطرائق methods في المزخرف ()app.route، ما يضمن قبول الطلبات سواءً بطريقة GET أو POST.



	الآن سيُفتح اتصالٌ مع قاعدة البيانات، فإذا كان الطلب بطريقة GET، نتجاوز الشرط:


if request.method == 'POST'



	وصولًا إلى آخر سطر في الشيفرة والمسؤول عن إخراج قالب HTML باسم index.html، الذي سيحتوي على نموذج إدخال الروابط المُراد اختصارها؛ أما في حال تحقّق الشرط السابق، فهذا يعني أنّه قد أُدخل رابطٌ من قِبل المستخدم لاختصاره، فيُخزَّن هذا الرابط ضمن المتغير url؛ أمّا في حال إرسال المستخدم النموذج دون إدخال رابط، فستظهر له رسالةً تخبره بأنّ حقل الرابط مطلوب "!The URL is required" ويُعاد توجيهه إلى الصفحة الرئيسية index مجدّدًا.



	وعندما يرسل المستخدم نموذجًا حاويًا على رابط، يُخزّن هذا الرابط في جدول urls من قاعدة البيانات باستخدام تعليمة INSERT INTO في SQL، كما يُضمَّن الموضع المؤقت ? (الذي سيُستبدل لاحقًا برقمٍ ما) في الدالة ()execute، ومن ثمّ يُمرّر السجل الحاوي على الرابط المطلوب اختصاره ليُحفظ في قاعدة البيانات بأمان، وفي النهاية تؤكَّد العملية ويُقطع الاتصال مع قاعدة البيانات.



	بعد ذلك، يُخزَّن المعرّف الخاص بالرابط المُدخل آنفًا في قاعدة البيانات ضمن متغيّر باسم url_id، و يمكننا الوصول إلى معرّف الرابط باستخدام السمة lastrowid التي تعيد معرّف آخر سجل مُدخلٍ في قاعدة البيانات.



	وتُبنى السلسلة المعمّاة بتمرير معرّف الرابط إلى التابع ()hashids.encode، لتخزَّن في المتغير hashid، فمثلًا ستكون القيمة المعادة لدى استدعاء التابع (hashids.encode(1 هي السلسلة المُعمّاة KJ34 وذلك اعتمادًا على محارف الإغفال المُستخدمة.



	ننتقل الآن إلى مرحلة بناء الرابط المُختصر باستخدام السمة request.host_url، التي يوفرّها عادةً كائن فلاسك request للوصول إلى رابط مضيف التطبيق، والذي سيكون /http://127.0.0.1:5000 في بيئة التطوير، ويصبح "your_domain" لدى نشر التطبيق؛ فمثلًا ستكون قيمة المتغير short_url مساويةً http://127.0.0.1:5000/KJ34، والتي تمثّل الرابط المختصر الذي سيعيد توجيه المُستخدم إلى الرابط الأصلي ذي المعرّف الموافق للسلسلة المعمّاة KJ34 والمحفوظ في قاعدة البيانات .



	نهايةً، يُخرج قالب HTML المسمّى index.html بتمرير المتغير short_url إليه. وستبدو الشيفرة كما يلي بعد الإضافات السابقة:


import sqlite3
from hashids import Hashids
from flask import Flask, render_template, request, flash, redirect, url_for


def get_db_connection():
    conn = sqlite3.connect('database.db')
    conn.row_factory = sqlite3.Row
    return conn


app = Flask(__name__)
app.config['SECRET_KEY'] = 'this should be a secret random string'

hashids = Hashids(min_length=4, salt=app.config['SECRET_KEY'])


@app.route('/', methods=('GET', 'POST'))
def index():
    conn = get_db_connection()

    if request.method == 'POST':
        url = request.form['url']

        if not url:
            flash('The URL is required!')
            return redirect(url_for('index'))

        url_data = conn.execute('INSERT INTO urls (original_url) VALUES (?)',
                                (url,))
        conn.commit()
        conn.close()

        url_id = url_data.lastrowid
        hashid = hashids.encode(url_id)
        short_url = request.host_url + hashid

        return render_template('index.html', short_url=short_url)

    return render_template('index.html')


	اِحفظ الملف وأغلقه.



	الآن سننشئ ملف القالب الأساسي وملف قالب HTML المسمّى index.html، لذا سنضيف مجلدًا جديدًا للقوالب باسم templates ضمن المجلد flask_shortener، وسنفتح ملفًا باسم base.html ضمنه:


(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html


	والآن سنكتب شيفرة بوتستراب bootstrap التالية ضمن الملف base.html، وإن لم تكن قوالب HTML في فلاسك مألوفةً بالنسبة لك، يمكنك قراءة الخطوة الثالثة من المقال كيفية إنشاء تطبيق ويب باستخدام إطار فلاسك في لغة بايثون 3:



 lang="en">
  
    
     charset="utf-8">
     name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    
     rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">

    </span><span class="pln">{% block title %} {% endblock %}</span><span class="tag">
  
  
     class="navbar navbar-expand-md navbar-light bg-light">
         class="navbar-brand" href="{{ url_for('index')}}">FlaskShortener
         class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
             class="navbar-toggler-icon">
        
         class="collapse navbar-collapse" id="navbarNav">
             class="navbar-nav">
             class="nav-item active">
                 class="nav-link" href="#">About
            
            
        
    
     class="container">
        {% for message in get_flashed_messages() %}
             class="alert alert-danger">{{ message }}
        {% endfor %}
        {% block content %} {% endblock %}
    

    
    
     src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous">
     src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
     src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
  



	الجزء الأكبر من الشيفرة السابقة هو تعليمات HTML معيارية وشيفرات لازمة لعمل بوتستراب، إذ تزوّد الوسوم  متصفح الويب بالمعلومات، في حين ينشئ الوسم  ارتباطًا إلى ملفات CSS الخاصة ببوتستراب، ويضمِّن الوسم 
     src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
     src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
  



	ضمنّا في الشفرة السابقة عنصر قائمة 
 في شريط التصفّح، وربطناه مع دالة فلاسك ()stats باستخدام دالة ()url_for، وبذلك يصبح بالإمكان الوصول إلى صفحة الإحصائيات من شريط التصفّح، التي ستعرض معلومات عن كل رابط، تتضمّن الرابط المُختصر المكافئ وعدد مرات زيارته.



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



	نهايةً يمكنك الاطلاع على شيفرة تطبيق اختصار الروابط كاملةً.



	الخاتمة



	ستحصل مع نهاية هذا المقال وبتطبيق الخطوات الواردة فيه على تطبيق يسمح للمستخدمين بإدخال روابط طويلة لاختصارها، إذ يحوِّل الأعداد الصحيحة إلى سلاسل معمّاة قصيرة، لإعادة توجيه المستخدمين من رابطٍ لآخر، كما يمكّنك من خلاله مراقبة الروابط المُختصرة عن طريق صفحة الإحصائيات.



	يمكنك الاطلاع على مزيدٍ من المقالات التعليمية حول فلاسك من خلال الروابط التالية:




		روابط المقال الأوّل والثاني والثالث بعد النشر في الأكاديمية.
	
	
		كيفية إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask في لغة بايثون 3.
	
	
		كيفية استخدام علاقات قاعدة البيانات من نوع واحد-إلى-متعدد one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite.
	
	
		الثالث.
	


	ترجمة -وبتصرف- للمقال How To Make a URL Shortener with Flask and SQLite لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا




		إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask من لغة بايثون
	
	
		استخدام علاقة one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite
	
	
		استخدام علاقة many-to-many مع فلاسك Flask ومحرك قواعد البيانات SQLite 
	
	
		تعديل العناصر في علاقات one-to-many باستخدام فلاسك Flask ومحرك قاعدة البيانات SQLite 
	




استخدام علاقة many-to-many مع فلاسك Flask ومحرك قواعد البيانات SQLite
Sat, 16 Jul 2022 07:08:48 +0000




	يُعد فلاسك إطار عمل يستخدم لغة البرمجة بايثون Python لبناء تطبيقات الويب، أما SQLite فهو محرّك قواعد بيانات يستخدم لغة البرمجة بايثون لتخزين بيانات تطبيق الويب. سنعمل في هذا المقال على تعديل تطبيق ويب مبني باستخدام فلاسك و SQLite من خلال إضافة علاقة من نوع متعدد-إلى-متعدد إليه.



	يمكنك البدء بقراءة هذا المقال مباشرةً، إلّا أنّه متابعةٌ للمقال السابق، لذلك من الأفضل قراءة المقال السابق بدايةً، إذ بيّنا فيه طريقة إدارة قاعدة بيانات متعدّدة الجداول ذات علاقة واحد-إلى-متعدد من خلال إنشاء تطبيق لإدارة المهام، ويمكِّن هذا التطبيق مستخدميه من إضافة عناصر مهام جديدة وتصنيفها ضمن قوائم مختلفة مع إمكانية تعديل العناصر.



	تُعرَّف علاقة قاعدة البيانات متعدّد-إلى-متعدّد على أنها علاقةٌ بين جدولين، إذ يمكن لأي سجلٍ من الجدولين الارتباط مع عدّة سجلات من الآخر، فمثلًا في تطبيق مدونة يمكن لجدول التدوينات posts أن يرتبط بعلاقة من نوع متعدد-إلى-متعدّد مع جدول أسماء المؤلفين (كُتَّاب التدوينات)، بمعنى أن كل تدوينة قد ترتبط بعدّة أسماء مؤلفين، وأيضًا قد يرتبط كل اسم مؤلف بعدّة تدوينات، وبالتالي فإنّ العلاقة ما بين التدوينات وأسماء المؤلفين هي علاقة متعدّد-إلى-متعدّد. أيُّ تطبيقٍ آخر من تطبيقات التواصل الاجتماعي هو مثالٌ آخر، إذ أن كل منشور قد يحتوي عدّة إشارات مرجعية، وكل إشارة مرجعية قد تتضمّن عدة منشورات.



	ومع اتباع الخطوات الواردة في هذا المقال، سنضيف على تطبيق إدارة المهام المُنشأ سابقًا ميزة تخصيص عناصر المهام لمستخدمين مختلفين، وسندعو المستخدمين الذين خُصَّصت لهم مهام بالمُخَصَّصين؛ فبفرض لدينا عنصر مهام من قائمة المهام المنزلية وهو "تنظيف المطبخ"، والتي من الممكن تخصيصها لشخصين مُختلفين وليكونا مثلًا أحمد ومحمّد، فكل مهمّة يمكن أن تملك عدّة مُخَصَّصين وهم في مثالنا أحمد ومحمّد، وبالمقابل يمكن تخصيص عدّة مهام للمستخدم الواحد، فمن الممكن مثلًا تخصيص عدّة مهام لأحمد، وبذلك نجد أنّ العلاقة ما بين عناصر المهام والمُخَصَّصين هي فعليًا من نوع متعدّد-إلى-متعدّد.



	سيُضاف إلى التطبيق مع نهاية هذا المقال وسم مُخصّص إلى Assigned to مع قائمة بأسماء المُخَصَّصين.



	



	مستلزمات العمل



	قبل المتابعة في هذا المقال لا بدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، وسنستدعي في مقالنا مجلد المشروع flask_todo المُنشأ مُسبقًا من الخطوات في المقال السابق.
	
	
		توفّر تطبيق إدارة المهام المُنجز في المقال السابق، وفي الخطوة الأولى من هذا المقال سيكون لديك الخيار إما باستنساخ التطبيق مُباشرةً دون إعداده من قبلك، أو اتباع الخطوات التفصيلية في المقال السابق لبناء التطبيق ومن ثمّ الإكمال في هذا المقال، كما يمكنك الحصول على الشيفرة الكاملة للتطبيق.
	
	
		يجب فهم مختلف مفاهيم فلاسك الأساسية، مثل إنشاء الوجهات وإخراج قوالب HTML والاتصال بقاعدة بيانات SQLite.
	


	الخطوة الأولى - إعداد تطبيق الويب الخاص بإدارة المهام سنُعدّ في هذه الخطوة تطبيق الويب الخاص بإدارة المهام ليكون جاهزاً لإجراء التعديلات عليه، ولكن إذا كنت قد اتبعت الخطوات الواردة في المقال السابق (المذكور ضمن فقرة مستلزمات العمل من مقالنا هذا)، فستكون لديك شيفرة التطبيق إضافةً إلى البيئة الافتراضية مُفعلّةً على حاسوبك، وبإمكانك تجاوز هذه الخطوة مباشرةً.



	سنستخدم لشرح آلية إضافة علاقة من النوع متعدّد-إلى-متعدّد لتطبيق ويب مبني باستخدام فلاسك شيفرة تطبيق إدارة المهام الذي أنشأناه سابقًا (راجع فقرة مستلزمات العمل) والمبني باستخدام فلاسك و SQLite وإطار العمل بوتستراب Bootstrap، إذ يمكِّن هذا التطبيق مستخدميه من إنشاء مهام جديدة وتعديلها وحذفها وتمييزها على أنها "مُنجزة".



	بدايةً، استخدم الأمر Git لاستنساخ شيفرة تطبيق إدارة المهام المُنشأ سابقًا:


$ git clone https://github.com/do-community/flask-todo


	بالانتقال إلى المجلد flask-todo:


$ cd flask_todo


	سننشئ بيئة عمل افتراضية جديدة:


$ python -m venv env


	ثمّ سنفعِّلها كما يلي:


$ source env/bin/activate


	الآن، سنحمّل إطار فلاسك ونثبته باستخدام الأمر:


$ pip install Flask


	ثمّ سنهيء قاعدة البيانات باستخدام البرنامج الموجود في الملف init_db.py:


(env)user@localhost:$ python init_db.py


	بعد ذلك، سنسند القيم اللازمة إلى متغيرات بيئة فلاسك على النحو التالي:


(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development


	إذ يشير متغير البيئة FLASK_APP إلى تطبيق الويب الخاص بإدارة المهام الذي نطوّره في هذا المقال، والموجود في الملف app.py في حالتنا؛ بينما يشير المتغير FLASK_ENV إلى وضع بيئة العمل، وهنا أُسندت القيمة development للعمل بوضع تطوير التطبيق، ما يتيح تشغيل منقّح الأخطاء، ومن المهم تذكّر عدم استخدام هذا الوضع في مرحلة التشغيل الفعلي للتطبيق أي في بيئة الإنتاج.



	سنشغّل خادم التطوير:


(env)user@localhost:$ flask run


	يمكننا الآن الذهاب إلى الرابط "/http://127.0.0.1:5000" باستخدام المتصفح للوصول إلى التطبيق. ولإيقاف خادم التطوير، نستخدم الاختصار "CTRL + C".



	أمّا الآن فسنطّلع على ملف تخطيط قاعدة البيانات لفهم بنية قاعدة البيانات الحالية والعلاقات ما بين الجداول فيها. إذا كنت قد اطلعت مُسبقًا من المقال السابق على الملف schema.sql وأصبح مألوفًا بالنسبة لك، فبإمكانك تجاوز هذه الخطوة.



	سنفتح الملف schema.sql:


(env)user@localhost:$ nano schema.sql


	فتظهر محتويات الملف على النحو التالي:


DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;

CREATE TABLE lists (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL
);

CREATE TABLE items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    list_id INTEGER NOT NULL,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    content TEXT NOT NULL,
    done INTEGER NOT NULL DEFAULT 0,
    FOREIGN KEY (list_id) REFERENCES lists (id)
);


	وفيه جدولين، الأول lists لتخزين القوائم، مثل قائمة المهام المنزلية Home أو قائمة المهام الدراسية study، والثاني items لتخزين عناصر المهام، مثل مهمّة غسل الأطباق Do the dishes أو مهمّة تعلّم فلاسك Learn Flask.



	ويحتوي جدول القوائم lists على الأعمدة التالية:




		"id": ويحتوي على معرّف ID القائمة.
	
	
		"created": يحتوي على تاريخ ووقت إنشاء قائمة المهام.
	
	
		"title": عنوان قائمة المهام.
	


	أمّا جدول عناصر المهام، فيحتوي على الأعمدة التالية:




		"id": يحتوي على معرّف ID العنصر.
	
	
		"list_id": يحتوي على معرّف القائمة التي ينتمي إليها العنصر.
	
	
		"created": يحتوي تاريخ إنشاء العنصر.
	
	
		"content": محتوى العنصر.
	
	
		"done": يحدّد حالة عنصر المهام من حيث الإنجاز، إذ تدل القيمة "0" على أنّ المهمّة لم تُنجز بعد، أمّا القيمة "1" فتعني أنّ المهمّة قد أُنجزت.
	


	ويتضمّن جدول العناصر items مفتاحًا أجنبيًا foreign key، إذ يشير العمود list_id إلى العمود id من جدول القوائم lists الأب، وهذا ما يمثّل علاقةً من النوع واحد-إلى-متعدّد one-to-many ما بين العناصر والقوائم، بمعنى أنّ القائمة الواحدة يمكن أن تضم عدّة عناصر في حين ينتمي كل عنصر لقائمة واحدة:


FOREIGN KEY (list_id) REFERENCES lists (id)


	سنستخدم في الخطوة التالية العلاقة من نوع متعدّد-إلى-متعدّد للربط بين جدولين في قاعدة البيانات.



	الخطوة الثانية - إضافة جدول المخصصين



	سنستعرض في هذه الخطوة كيفية تطبيق علاقة من نوع متعدّد-إلى-متعدّد وكيفية دمج الجداول، ومن ثمّ سنضيف جدولًا جديدًا إلى قاعدة البيانات لتخزين المُخَصَّصين.



	العلاقة من نوع متعدّد-إلى-متعدّد هي طريقةٌ لربط جدولين، بحيث يكون لكل عنصر من أحدهما عدّة علاقات مع عدّة عناصر من الجدول الآخر.



	بفرض لدينا جدولٌ بسيط لعناصر المهام على النحو التالي:


Items
+----+-------------------+
| id | content           |
+----+-------------------+
| 1  | Buy eggs          |
| 2  | Fix lighting      |
| 3  | Paint the bedroom |
+----+-------------------+


	وجدول للمُخَصَّصين على النحو التالي:


assignees
+----+------+
| id | name |
+----+------+
| 1  | Ahmad|
| 2  | Mohammad   |
+----+------+


	وعلى فرض أنّنا نريد تخصيص مهمّة إصلاح المصباح Fix lighting لكلٍ من أحمد ومحمّد، فمن الممكن إنجاز ذلك بإضافة صفٍ جديد لجدول العناصر كما يلي:


items
+----+-------------------+-----------+
| id | content           | assignees |
+----+-------------------+-----------+
| 1  | Buy eggs          |           |
| 2  | Fix lighting      | 1, 2      |
| 3  | Paint the bedroom |           |
+----+-------------------+-----------+


	ولكن وبما أنّ كل عمود ينبغي أن يحتوي على قيمةٍ واحدة لضمان سلاسة العمليات، نجد أنّ المنهجية أعلاه خاطئة؛ فعند إسناد قيم متعدّدة للسجل الواحد في العمود، ستغدو العمليات الأساسية البسيطة، مثل إضافة، أو تحديث البيانات معقّدةً وبطيئة، والحل يكون باستخدام جدول ثالث يحوي أعمدةً تشير إلى المفاتيح الأساسية للجداول ذات الصلة، وهو ما ندعوه عادةً جدول الدمج join table، وهو يخزّن المعرّفات لكل عنصر في كل جدول.



	وفيما يلي مثالٌ لجدول دمج يربط بين جدولي العناصر والمُخَصَّصين:


item_assignees
+----+---------+-------------+
| id | item_id | assignee_id |
+----+---------+-------------+
| 1  | 2       | 1           |
| 2  | 2       | 2           |
+----+---------+-------------+


	ففي السطر الأوّل من جدول الدمج أعلاه، يرتبط العنصّر ذو المعرّف 2، الذي يمثّل مهمّة إصلاح المصباح Fix lighting مع المُخّصَّص ذو المعرّف 1 (أحمد)، أمّا في السطر الثاني فإنّ عنصر المهام نفسه يرتبط مع المُخّصَّص ذو المعرّف 2 (محمّد)، ما يعني أنّ عنصر المهام قد خُصِّص لكل من أحمد ومحمّد، ويمكننا تخصيص عدّة عناصر مهام على نحوٍ مشابه لشخص مُخَصَّص واحد.



	سنعمل الآن على تعديل قاعدة بيانات تطبيق المهام لإضافة الجدول الذي يخزّن المُخَصَّصين.



	لذا بدايةً، سنفتح ملف تخطيط قاعدة البيانات schema.sql لإضافة جدولٍ جديد باسم assignees:


(env)user@localhost:$ nano schema.sql


	وسنضيف سطرًا برمجيًا لحذف أي جداول موجودة أصلًا في قاعدة البيانات باسم assignees، وهذا ما يجنبنا أي تضاربات قد تحصل مُستقبلًا نتيجة وجود جدولين بنفس الاسم وبأعمدة مُختلفة في قاعدة البيانات، والذي قد يؤدي لتوقف تنفيذ الشيفرة نتيجة عدم توافق الجدول الموجود مع تخطيط قاعدة البيانات.



	الآن، سنضيف شيفرة SQL اللازمة للجدول الجديد:


DROP TABLE IF EXISTS assignees;
DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;

CREATE TABLE lists (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL
);

CREATE TABLE items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    list_id INTEGER NOT NULL,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    content TEXT NOT NULL,
    done INTEGER NOT NULL DEFAULT 0,
    FOREIGN KEY (list_id) REFERENCES lists (id)
);

CREATE TABLE assignees (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL
);


	اِحفظ الملف وأغلقه.



	يحتوي جدول المُخَصَّصين assignees الجديد على الأعمدة التالية:




		"id": ويحتوي على معرّف ID المُخَصَّص.
	
	
		"name": يحتوي على اسم المُخَصَّص.
	


	الآن، سنعدّل ملف تهيئة قاعدة البيانات init_db.py بغية إضافة بعض المُخَصَّصين إلى قاعدة البيانات:


(env)user@localhost:$ nano init_db.py


	عدّل الملف ليصبح كما يلي:


import sqlite3

connection = sqlite3.connect('database.db')

with open('schema.sql') as f:
    connection.executescript(f.read())

cur = connection.cursor()

cur.execute("INSERT INTO lists (title) VALUES (?)", ('Work',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Home',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Study',))

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (1, 'Morning meeting')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Buy fruit')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Cook dinner')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn Flask')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn SQLite')
            )

cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Ahmad',))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Mohammad',))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('sami',))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Yousef',))

connection.commit()
connection.close()


	اِحفظ الملف وأغلقه.



	استخدمنا في الشيفرة السابقة كائن المؤشّر cursor لتنفيذ تعليمة INSERT في SQL اللازمة لإدخال أربعة أسماء إلى جدول المُخّصَّصين assignees، كما استخدمنا الموضع المؤقت ? في الدالة ()execute ومرّرنا له السجل الحاوي على اسم المُخَصًّص بما يضمن إدخال البيانات في قاعدة البيانات بأمان، ثمّ حفظنا التغييرات باستخدام الدالة ()connection.commit، وأُغلق الاتصال مع قاعدة البيانات باستخدام الدالة ()connection.close.



	وبذلك سيُضاف أربعة مُخّصَّصين إلى قاعدة البيانات، أسماؤهم أحمد ومحمّد وسامي ويوسف.



	الآن سنعيد تهيئة قاعدة البيانات بتشغيل البرنامج init_db.py:


(env)user@localhost:$ python init_db.py


	وبذلك يصبح لدينا جدول لتخزين المُخّصَّصين في قاعدة البيانات. فيما يلي سنضيف جدول الدمج بهدف إنشاء علاقةٍ من نوع متعدّد-إلى-متعدّد بين عناصر المهام والمُخّصَّصين.



	الخطوة الثالثة - إضافة جدول دمج ذو علاقة متعدد-إلى-متعدد



	سنستخدم في هذه الخطوة جدول دمج لربط عناصر المهام بالمُخَصَّصين، لذا بدايةً سنعدّل ملف تخطيط قاعدة البيانات بغية إضافة جدول دمج جديد، كما سنعدّل ملف تهيئة قاعدة البيانات لإضافة بعض التخصيصات، أي تخصيص بعض عناصر المهام لبعض المُخَصَّصين، ثمّ سنستعرض المُخَصَّصين لكل مهمّة باستخدام برنامج تجريبي لفهم التغييرات الحاصلة في قاعدة البيانات.



	سنفتح بدايةً ملف تخطيط قاعدة البيانات schema.sql لإضافة جدول جديد:


(env)user@localhost:$ nano schema.sql


	وبما أنّ هذا الجدول يدمج العناصر مع المُخَصَّصين فسنسميه جدول عناصر مُخَصَّصين item_assignees، وسنضيف سطرًا برمجيًا لحذف أي جداول موجودة أصلًا في قاعدة البيانات بنفس الاسم، ومن ثمّ سنضيف شيفرة SQL اللازمة لهذا الجدول:


DROP TABLE IF EXISTS assignees;
DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;
DROP TABLE IF EXISTS item_assignees;


CREATE TABLE lists (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL
);

CREATE TABLE items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    list_id INTEGER NOT NULL,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    content TEXT NOT NULL,
    done INTEGER NOT NULL DEFAULT 0,
    FOREIGN KEY (list_id) REFERENCES lists (id)
);

CREATE TABLE assignees (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL
);

CREATE TABLE item_assignees (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id INTEGER,
    assignee_id INTEGER,
    FOREIGN KEY(item_id) REFERENCES items(id),
    FOREIGN KEY(assignee_id) REFERENCES assignees(id)
);


	اِحفظ الملف وأغلقه.



	يحتوي جدول عناصر مُخَصَّصين item_assignees الجديد على الأعمدة التالية:




		"id": ويحتوي على معرّف ID المُدخَل والدال على العلاقة ما بين مهمّة ومُخَصَّص، إذ يمثّل كل سطر من هذا الجدول علاقةً ما بين مهمّة ومُخَصَّص.
	
	
		"item_id": ويحتوي على معرّف ID لعنصر المهام المُسند للمُخَصَّص ذا المعرّف "assignee_id" الموافق.
	
	
		"assignee_id": ويحتوي على معرّف ID للمُخَصَّص المُسند إليه عنصر المهام ذا المعرّف "item_id" الموافق.
	


	ويملك الجدول item_assignees مفتاحين أجنبيين، الأول يربط عمود معرّف العنصر item_id في هذا الجدول مع عمود المعرّف id من جدول العناصر items، والثاني يربط عمود معرّف المُخَصَّص من هذا الجدول مع عمود المعرّف id من جدول المُخَصَّصين assignees.



	والآن سنفتح ملف تهيئة قاعدة البيانات لإضافة بعض التخصيصات، أي إسناد مهام لمُخَصَّصين:


(env)user@localhost:$ nano init_db.py


	وسنعدّل الملف ليصبح كما يلي:


import sqlite3

connection = sqlite3.connect('database.db')


with open('schema.sql') as f:
    connection.executescript(f.read())

cur = connection.cursor()

cur.execute("INSERT INTO lists (title) VALUES (?)", ('Work',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Home',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Study',))

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (1, 'Morning meeting')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Buy fruit')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Cook dinner')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn Flask')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn SQLite')
            )

cur.execute("INSERT INTO assignees (name) VALUES (?)", (Ahmad,))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Mohammad',))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Sami',))
cur.execute("INSERT INTO assignees (name) VALUES (?)", ('Yousef',))

# Assign "Morning meeting" to "Ahmad"
cur.execute("INSERT INTO item_assignees (item_id, assignee_id) VALUES (?, ?)",
            (1, 1))

# Assign "Morning meeting" to "Mohammad"
cur.execute("INSERT INTO item_assignees (item_id, assignee_id) VALUES (?, ?)",
            (1, 2))

# Assign "Morning meeting" to "Yousef"
cur.execute("INSERT INTO item_assignees (item_id, assignee_id) VALUES (?, ?)",
            (1, 4))

# Assign "Buy fruit" to "Ahmad"
cur.execute("INSERT INTO item_assignees (item_id, assignee_id) VALUES (?, ?)",
            (2, 1))

connection.commit()
connection.close()


	يُخصِّص الجزء الجديد المُضاف إلى الشيفرة السابقة عناصر مهام إلى مُخَصَّصين وذلك بإدخال كل منهما في جدول الدمج item_assignees، بحيث نُدخل معرّف قائمة المهام item_id المُراد تخصيصها (إسنادها) مع معرّف الشخص (المُخَصَّص) الموافق assignee_id. فمثلًا، أسندنا في الشيفرة أعلاه مهمّة الاجتماع الصباحي Morning meeting ذات المعرّف 1 إلى المُخَصَّص Ahmad ذو المعرّف 1، وأكملنا الأسطر التالية وفق النمط ذاته، ومجدّدًا استخدمنا الموضع المؤقت ? لتمرير القيم المراد إدخالها على هيئة مجموعة إلى التابع ()cur.execute بأمان.



	اِحفظ الملف وأغلقه.



	الآن سنعيد تهيئة قاعدة البيانات مجدّدًا بتشغيل البرنامج في الملف init_db.py كما يلي:


(env)user@localhost:$ python init_db.py


	ثم سنشغّل البرنامج التجريبي list_example.py، الذي يعرض عناصر المهام الموجودة في قاعدة البيانات:


(env)user@localhost:$ python list_example.py


	ويكون الخرج على النحو التالي:


Home
     Buy fruit | id: 2 | done: 0
     Cook dinner | id: 3 | done: 0
Study
     Learn Flask | id: 4 | done: 0
     Learn SQLite | id: 5 | done: 0
Work
     Morning meeting | id: 1 | done: 0


	نلاحظ من الخرج أنه يعرض كل عناصر المهام تحت القائمة التي يتبع لها، إضافةً لعرض معرّف وحالة كل عنصر (مُنجز / غير مُنجز)، إذ تدل القيمة 0 على عدم إنجازه بعد، أمّا القيمة 1 فتعني أنّه مُنجز.



	الآن، سنعمل على عرض المُخَصَّصين لكل عنصر مهام، لذلك سنفتح الملف list_example.py:


(env)user@localhost:$ nano list_example.py


	ونعدله بحيث يعرض المُخَصَّصين لكل عنصر مهام كما يلي:


from itertools import groupby
from app import get_db_connection

conn = get_db_connection()
todos = conn.execute('SELECT i.id, i.done, i.content, l.title \
                      FROM items i JOIN lists l \
                      ON i.list_id = l.id ORDER BY l.title;').fetchall()

lists = {}

for k, g in groupby(todos, key=lambda t: t['title']):
    # Create an empty list for items
    items = []
    # Go through each to-do item row in the groupby() grouper object
    for item in g:
        # Get the assignees of the current to-do item
        assignees = conn.execute('SELECT a.id, a.name FROM assignees a \
                                  JOIN item_assignees i_a \
                                  ON a.id = i_a.assignee_id \
                                  WHERE i_a.item_id = ?',
                                  (item['id'],)).fetchall()
        # Convert the item row into a dictionary to add assignees
        item = dict(item)
        item['assignees'] = assignees

        items.append(item)

    # Build the list of dictionaries
    # the list's name (ex: Home/Study/Work) as the key

    # and a list of dictionaries of to-do items
    # belonging to that list as the value
    lists[k] = list(items)


for list_, items in lists.items():
    print(list_)
    for item in items:
        assignee_names = ', '.join(a['name'] for a in item['assignees'])

        print('    ', item['content'], '| id:',
              item['id'], '| done:', item['done'],
              '| assignees:', assignee_names)


	اِحفظ الملف وأغلقه.



	استخدمنا في الشيفرة السابقة دالة الفرز ()groupby لفرز عناصر المهام بحسب عناوين القوائم التي ينتمي لها كل عنصر (لمزيد من التفاصيل حول هذه النقطة يمكنك الاطلاع على الخطوة الثانية من مقال استخدام علاقات قاعدة البيانات من نوع واحد-إلى-متعدد، وخلال إجراء عملية الفرز السابقة، أنشأنا قائمةً فارغةً باسم items، وهي ستحتوي كافّة بيانات عناصر المهام، من معرّف العنصر ومحتواه والمُخَصَّص



	ومن ثمّ نمر ضمن حلقة for المُخصّصة للعناصر وخلال g دورة (تكرار) على كافّة عناصر المهام لجلب المُخَصَّص لكل عنصر وحفظه ضمن المتغير assignees، الذي سيخزّن نتائج الاستعلام SELECT في SQL؛ إذ يجلب هذا الاستعلام معرّف المُخَصَّص a.id واسمه a.name من جدول المُخَصَّصين assignees (وقد رمزنا لهذا الجدول بالحرف a بهدف اختصار الاستعلام)، ثمّ يدمج معرّف واسم المُخَصَّص item_assignees المرتبط بالقائمة المطلوبة في جدول الدمج (رمزه المُختصَر i_a) وذلك من خلال تحقيق شرط كون معرّف المُخَصّص المأخوذ من جدول المُخَصَّصين مساويًا للمعرّف في جدول الدمج a.id = i_a.assignee_id وذلك عند كون قيمة معرّف عنصر المهام i_a.item_id في جدول الدمج مساويةً لقيمة معرّف العنصر الحالي ['item['id'، ومن ثمّ نحصل على نتائج الاستعلام ضمن قائمة باستخدام التابع()fetchall.



	وبما أنّ كائن sqlite3.Row العادي لا يدعم مبدأ الإسناد، أضفنا السطر البرمجي التالي:


item = dict(item)


	لتحويل العناصر إلى قواميس بايثون، والتي سنستخدمها لإضافة المُخَصَّصين إلى العناصر، ثمّ أضفنا مفتاحًا جديدًا وهو assignees إلى قاموس العناصر item باستخدام السطر البرمجي التالي:


item['assignees'] = assignees


	وذلك بهدف الوصول إلى مُخَصَّصي العناصر مباشرةً من قاموس العناصر، ثمّ أضفنا العنصر المعدّل هذا إلى قائمة العناصر items، ثم بنينا قائمة القواميس المحتوية لكامل البيانات، فكل مفتاح ضمن القاموس يمثّل عنوان قائمة المهام وقيمة هذا المفتاح تضم كافّة العناصر التابعة لهذه القائمة.



	أما لطباعة النتائج استُخدمت الحلقة:


 for list_, items in lists.items()


	للمرور على كافّة عناوين قوائم المهام والعناصر التابعة لكل منها، بحيث يُطبَع عنوان القائمة _list، ثمّ نمر باستخدام حلقة على كافّة العناصر التابعة لها؛ كما أُضيف متغيّرٌ باسم assignee_names، بحيث تستخدم قيمته دالة الدمج ()join لدمج العناصر الناتجة عن تعليمة البناء generator expression التالية، التي تجلب اسم المُخَصَّص ['a['name:


a['name'] for a in item['assignees']


	مع بيانات هذا المُخَصَّص من القائمة ['item['assignees، وهذا ما يضمن إضافة أسماء المُخَصَّصين، ونهايةً تُطبع باقي بيانات عناصر المهام باستخدام الدالة ()print.



	نشغِّل الآن البرنامج التجريبي list_example.py:


(env)user@localhost:$ python list_example.py


	فيكون الخرج على النحو التالي:


Home
     Buy fruit | id: 2 | done: 0 | assignees: Ahmad
     Cook dinner | id: 3 | done: 0 | assignees:
Study
     Learn Flask | id: 4 | done: 0 | assignees:
     Learn SQLite | id: 5 | done: 0 | assignees:
Work
     Morning meeting | id: 1 | done: 0 | assignees: Ahmad, Mohammad, Yousef


	وبذلك أصبح بالإمكان عرض المُخَصَّصين لكل عنصر مهام لكامل البيانات.



	ومع نهاية هذه الخطوة، نكزن قد عرضنا أسماء المُخَصَّصين لكل عنصر مهام. سنستخدم هذه الشيفرة في الخطوة التالية لعرض أسماء المُخَصَّصين تحت كل عنصر مهام وذلك في الصفحة الرئيسية للتطبيق.



	الخطوة الرابعة - عرض المخصصين في الصفحة الرئيسية للتطبيق سنعدّل في هذه الخطوة الصفحة الرئيسية لتطبيق إدارة المهام، بحيث تعرض المُخَصَّصين لكل عنصر مهام. سنعدّل بدايةً الملف app.py، الذي يحتوي على شيفرة تطبيق فلاسك، ثمّ سنعدّل القالب index.html لعرض المُخَصَّصين تحت كل عنصر مهام في الصفحة الرئيسية.



	لذا، سنفتح الملف app.py لتعديل دالة فلاسك ()index:


(env)user@localhost:$ nano app.py


	وسنعدّل الدالة لتصبح كما يلي:


@app.route('/')
def index():
    conn = get_db_connection()
    todos = conn.execute('SELECT i.id, i.done, i.content, l.title \
                          FROM items i JOIN lists l \
                          ON i.list_id = l.id ORDER BY l.title;').fetchall()

    lists = {}

    for k, g in groupby(todos, key=lambda t: t['title']):
        # Create an empty list for items
        items = []
        # Go through each to-do item row in the groupby() grouper object
        for item in g:
            # Get the assignees of the current to-do item
            assignees = conn.execute('SELECT a.id, a.name FROM assignees a \
                                    JOIN item_assignees i_a \
                                    ON a.id = i_a.assignee_id \
                                    WHERE i_a.item_id = ?',
                                    (item['id'],)).fetchall()
            # Convert the item row into a dictionary to add assignees
            item = dict(item)
            item['assignees'] = assignees

            items.append(item)

        # Build the list of dictionaries
        # the list's name (ex: Home/Study/Work) as the key

        # and a list of dictionaries of to-do items
        # belonging to that list as the value
        lists[k] = list(items)

    conn.close()
    return render_template('index.html', lists=lists)


	اِحفظ الملف وأغلقه.



	الشيفرة السابقة مماثلةٌ لتلك المُستخدمة في البرنامج التجريبي list_example.py في الخطوة الثالثة، وباستخدامنا لها سيحتوي المتغير lists على كافّة البيانات التي نحتاج بما فيها بيانات المُخَصًّصين التي سنستخدمها في القالب index.html للوصول إلى أسمائهم.



	لذا سنفتح الملف index.html:


(env)user@localhost:$ nano templates/index.html


	ثم نعدّله بهدف إضافة أسماء المُخَصًّصين بعد كل عنصر ليصبح كما يلي:


{% extends 'base.html' %}

{% block content %}
    <h1>{% block title %} Welcome to FlaskTodo {% endblock %}h1>
    {% for list, items in lists.items() %}
        <div class="card" style="width: 18rem; margin-bottom: 50px;">
            <div class="card-header">
                <h3>{{ list }}h3>
            div>
            <ul class="list-group list-group-flush">
                {% for item in items %}
                    <li class="list-group-item"
                    {% if item['done'] %}
                    style="text-decoration: line-through;"
                    {% endif %}
                    >{{ item['content'] }}
                    {% if not item ['done'] %}
                        {% set URL = 'do' %}
                        {% set BUTTON = 'Do' %}
                    {% else %}
                        {% set URL = 'undo' %}
                        {% set BUTTON = 'Undo' %}
                    {% endif %}
                    <div class="row">
                        <div class="col-12 col-md-3">
                            <form action="{{ url_for(URL, id=item['id']) }}"
                                method="POST">
                                <input type="submit" value="{{ BUTTON }}"
                                    class="btn btn-success btn-sm">
                            form>
                        div>

                        <div class="col-12 col-md-3">
                            <a class="btn btn-warning btn-sm"
                            href="{{ url_for('edit', id=item['id']) }}">Edita>
                        div>

                        <div class="col-12 col-md-3">
                            <form action="{{ url_for('delete', id=item['id']) }}"
                                method="POST">
                                <input type="submit" value="Delete"
                                    class="btn btn-danger btn-sm">
                            form>
                        div>
                    div>

                    <hr>
                    {% if item['assignees'] %}
                        <span style="color: #6a6a6a">Assigned tospan>
                        {% for assignee in item['assignees'] %}
                            <span class="badge badge-primary">
                                {{ assignee['name'] }}
                            span>
                        {% endfor %}
                    {% endif %}

                    li>
                {% endfor %}
            ul>
        div>
    {% endfor %}
{% endblock %}


	اِحفظ الملف وأغلقه.



	وبهذه التعديلات أعلاه نكون قد أضفنا فاصل أسطر تحت كل عنصر باستخدام وسم الفاصل الأفقي 
، وبالتالي في حال أُسندت مهامٌ معينة إلى مُخَصَّصين بواسطة التعليمة:


if item['assignees']


	ستظهر عبارة Assigned to وإلى جانبها أسماء المُخَصَّصين ['assignee['name الموافقين من القائمة ['item['assignees



	الآن، نشغِّل خادم التطوير:


(env)user@localhost:$ flask run


	ونصل إلى الصفحة الرئيسية index للتطبيق من خلال الذهاب إلى الرابط "/http://127.0.0.1:5000" في المتصفح.



	وبذلك أصبح من الممكن إسناد المهمّة الواحدة إلى عدّة مُخَصَّصين وإسناد عدّة مهام للمُخَصًّص الواحد.



	



	يمكنك الاطلاع على شيفرة التطبيق كاملةً.



	الخاتمة



	تعرفّنا في هذا المقال على علاقة قاعدة البيانات من نوع متعدّد-إلى-متعدّد، وكيفية استخدامها في تطبيق ويب مبني باستخدام فلاسك و SQLite، وكيفية دمج جدولين وفرز وتصنيف البيانات المترابطة باستخدام بايثون.



	ومع نهاية هذا المقال نكون قد أنجزنا تطبيق إدارة المهام كاملًا، والذي يمكّن مستخدميه من إنشاء عناصر مهام جديدة، وتمييز المُنجز منها، مع إمكانية تعديل أو حذف المهام الموجودة أصلًا، وإنشاء قوائم جديدة، بحيث من الممكن تخصيص كل عنصر مهام إلى عدّة مُخَصَّصين.



	ترجمة -وبتصرف- للمقال How To Use Many-to-Many Database Relationships with Flask and SQLite لصاحبه Abdelhadi Dyouri.



	اقرا أيضًا




		إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask من لغة بايثون
	
	
		استخدام علاقة one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite
	
	
		تعديل العناصر في علاقات one-to-many باستخدام فلاسك Flask ومحرك قاعدة البيانات SQLite 
	




تعديل العناصر في علاقات one-to-many باستخدام فلاسك Flask ومحرك قاعدة البيانات SQLite
Tue, 19 Jul 2022 16:02:00 +0000




	يُعد فلاسك إطار عمل لبناء تطبيقات الويب مبني باستخدام لغة البرمجة بايثون Python، أمّا SQLite فيُعرَّف على أنّه محرّك قاعدة بيانات يُستخدم ضمن بايثون لتخزين بيانات التطبيقات. سنتعلّم في هذا المقال كيفية التعديل على عناصر تطبيق مبني باستخدام فلاسك و SQLite.



	يأتي مقالنا هذا استكمالًا للمقال السابق الذي أنشأنا فيه تطبيق ويب لإدارة المهام باستخدام فلاسك و SQLite، إذ أتاح لمستخدميه إمكانية إدارة عناصر المهام وتنظيمها ضمن قوائم، وإضافة عناصر جديدة إلى قاعدة البيانات؛ وفي مقالنا هذا سنضيف للتطبيق السابق الآليات اللازمة لإتاحة إمكانية تخصيص عناصر مهام مُنجزة، وتعديل عناصر موجودة أصلًا وحذف عناصر وإضافة قوائم جديدة إلى قاعدة البيانات، وباتبّاع الخطوات التالية سيُضاف للتطبيق السابق أزرار تحرير وحذف، إضافةً لإمكانية وضع خط متوسط لتمييّز المهام المُنجزة.



	



	مستلزمات العمل



	قبل المتابعة في هذا المقال لا بُدّ من:




		توفُّر بيئة برمجة بايثون 3 محلية، وسنستدعي في مقالنا مجلد المشروع flask_todo المُنشأ مُسبقًا من الخطوات في المقال السابق.
	
	
		توفّر تطبيق إدارة المهام المُنجز في المقال السابق، وفي الخطوة الأولى من هذا المقال سيكون لديك الخيار إما باستنساخ التطبيق مُباشرةً دون إعداده من قبلك، أو باتباع الخطوات التفصيلية في المقال السابق كيفية استخدام علاقات قاعدة البيانات من نوع واحد-إلى-متعدد one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite لبناء التطبيق، ومن ثمّ الإكمال في هذا المقال، كما يمكنك الحصول على الشيفرة الكاملة للتطبيق.
	
	
		يجب فهم مختلف مفاهيم فلاسك الأساسية، مثل إنشاء الوجهات وإخراج قوالب HTML والاتصال بقاعدة بيانات SQLite.
	


	الخطوة الأولى - إعداد تطبيق الويب الخاص بإدارة المهام



	سنُعدّ في هذه الخطوة تطبيق الويب الخاص بإدارة المهام ليكون جاهزاً لإجراء التعديلات عليه، ولكن إن كنت قد اتبعت الخطوات الواردة في المقال السابق (المذكور ضمن فقرة مستلزمات العمل من مقالنا هذا)، ولديك شيفرة التطبيق إضافةً إلى البيئة الافتراضية مُفعلّةً على حاسوبك، فبإمكانك تجاوز هذه الخطوة مباشرةً.



	سنبدأ باستخدم الأمر Git لاستنساخ شيفرة تطبيق إدارة المهام المُنشأ سابقًا:


$ git clone https://github.com/do-community/flask-todo


	ثم ننتقل إلى المجلّد flask-todo:


$ cd flask-todo


	سننشئ بيئة عمل افتراضية جديدة:


$ python -m venv env


	ومن ثمّ سنفعلها على النحو التالي:


$ source env/bin/activate


	الآن سنحمّل إطار فلاسك ونثبته باستخدام الأمر:


$ pip install Flask


	ثمّ سنهيء قاعدة البيانات باستخدام البرنامج الموجود في الملف init_db.py:


(env)user@localhost:$ python init_db.py


	ثمّ سنسند القيم اللازمة إلى متغيرات بيئة فلاسك:


(env)user@localhost:$ export FLASK_APP=app
(env)user@localhost:$ export FLASK_ENV=development


	إذ يشير متغير البيئة FLASK_APP إلى تطبيق الويب الخاص بإدارة المهام الذي نطوّره في هذا المقال، والموجود في الملف app.py في حالتنا؛ بينما يشير المتغير FLASK_ENV إلى وضع بيئة العمل، وهنا أُسندت القيمة development للعمل بوضع تطوير التطبيق، ما يتيح تشغيل منقّح الأخطاء، ومن المهم تذكّر عدم استخدام هذا الوضع في مرحلة التشغيل الفعلي للتطبيق أي في بيئة الإنتاج.



	سنشغّل خادم التطوير:


(env)user@localhost:$ flask run



	يمكننا الآن الذهاب إلى الرابط "/http://127.0.0.1:5000" باستخدام المتصفح للوصول إلى التطبيق. ولإيقاف خادم التطوير، نستخدم الاختصار "CTRL + C".



	وسنعدّل في الخطوة التالية تطبيق إدارة المهام ليُتيح لمستخدميه إمكانية تمييز عناصر المهام المُنجزة.



	الخطوة الثانية - إضافة إمكانية تمييز عناصر المهام المنجزة



	سنضيف في هذه الخطوة زرًا يُمكّن المستخدم من وضع علامةٍ على كل عنصر مهام مُنجز لتمييزه، لذا سنضيف عمودًا جديدًا إلى جدول العناصر items في قاعدة البيانات يحتوي على علامة تميّز ما إذا كان عنصر المهام قد أُنجز أم لا، وهذا بدوره يتطلّب إنشاء وجهة جديدة ضمن ملف البرنامج app.py، إذ سيعمل على تغيير قيم العمود الجديد لكل عنصر تبعًا لنشاطات المستخدم وتفاعله مع واجهة التطبيق.



	وللتذكير، الأعمدة الموجودة حاليًا في الجدول items من قاعدة البيانات قبل إضافة العمود الجديد، هي:




		"id": يحتوي معرّف العنصر.
	
	
		"list_id": يحتوي معرّف القائمة التي ينتمي إليها العنصر.
	
	
		"created": يحوي تاريخ إنشاء العنصر.
	
	
		"content": محتوى العنصر.
	


	بدايةً، سنفتح ملف تخطيط قاعدة البيانات schema.sql لتعديل جدول العناصر items:


(env)user@localhost:$ nano schema.sql


	وسنضيف عمودًا جديدًا باسم done إلى جدول العناصر items على النحو التالي:


DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;

CREATE TABLE lists (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL
);

CREATE TABLE items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    list_id INTEGER NOT NULL,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    content TEXT NOT NULL,
    done INTEGER NOT NULL DEFAULT 0,
    FOREIGN KEY (list_id) REFERENCES lists (id)
);


	اِحفظ الملف وأغلقه.



	سيتضمّن العمود المُضاف حديثًا done إلى قاعدة بيانات التطبيق إحدى القيمتين الصحيحتين "0" أو "1"، إذ تمثّل القيمة "0" القيمة المنطقية "false للدلالة على عنصر مهام غير مُنجز، في حين تمثّل القيمة "1" القيمة المنطقية "true" للدلالة على عنصر مهام مُنجز، علمًا أن القيمة الافتراضية هي "0"، وبالتالي عند إضافة أي عنصر مهام جديد إلى قاعدة البيانات فإنّ العمود done سيشير تلقائيًا إلى القيمة "0" دلالةً على أنّ المهمّة غير مُنجزة بعد، ولن تتغير حتى يضع المستخدم علامةً على العنصر أنه مُنجز، وعندها تتغير القيمة المقابلة لهذا العنصر في العمود done من القيمة "0" إلى القيمة "1".



	ولتطبيق التغييرات المُنفّذة على ملف تخطيط قاعدة البيانات schema.sql، سنهيئ قاعدة البيانات مجدّدًا باستخدام برنامج init_db.py:


(env)user@localhost:$ python init_db.py


	الآن، سنفتح الملف app.py لتحريره:


(env)user@localhost:$ nano app.py



	ثم سنجلب كلًا من معرّف العنصر وقيمة عمود done الموافقة له إلى الدالة ()index، التي تجلب أصلًا القوائم والعناصر من قاعدة البيانات، مرسلةً إياها إلى ملف HTML المُسمّى index.html ليعمل على عرضها، لذا عدّلنا على تعليمات SQL السابقة لتصبح مثل الشيفرة التالية:


@app.route('/')
def index():
    conn = get_db_connection()
    todos = conn.execute('SELECT i.id, i.done, i.content, l.title \
                          FROM items i JOIN lists l \
                          ON i.list_id = l.id ORDER BY l.title;').fetchall()
    lists = {}
    for k, g in groupby(todos, key=lambda t: t['title']):
        lists[k] = list(g)
    conn.close()
    return render_template('index.html', lists=lists)


	اِحفظ الملف وأغلقه.



	وبإجراء هذه التعديلات على الشيفرة السابقة، ستُجلب معرّفات العناصر من قاعدة البيانات باستخدام التعليمة i.id، والقيمة من عمود done الموافقة باستخدام التعليمة i.done.



	ولفهم نتائج هذه التعديلات بوضوح، سننشئ الملف list_example.py على سبيل التجربة، وسنكتب ضمنه برنامجًا صغيرًا بهدف فهم محتويات قاعدة البيانات الجديدة:


(env)user@localhost:$ nano list_example.py


	سنكتب ضمن هذا الملف التجريبي نفس الشيفرة السابقة مع التعديلات التي أجريناها على تعليمات SQL، ولكن سنعدّل دالة الطباعة ()print الأخيرة لتعرض كلًا من معرّف العنصر ID والقيمة الدالة على حالة إنجازه done:


from itertools import groupby
from app import get_db_connection
conn = get_db_connection()
todos = conn.execute('SELECT i.id, i.done, i.content, l.title \
                      FROM items i JOIN lists l \
                      ON i.list_id = l.id ORDER BY l.title;').fetchall()
lists = {}
for k, g in groupby(todos, key=lambda t: t['title']):
    lists[k] = list(g)
for list_, items in lists.items():
    print(list_)
    for item in items:
        print('    ', item['content'], '| id:',
              item['id'], '| done:', item['done'])


	اِحفظ الملف وأغلقه.



	الآن سنشغِّل هذا البرنامج التجريبي:


(env)user@localhost:$ python list_example.py


	لنحصل على الخرج التالي:


Home
     Buy fruit | id: 2 | done: 0
     Cook dinner | id: 3 | done: 0
Study
     Learn Flask | id: 4 | done: 0
     Learn SQLite | id: 5 | done: 0
Work
     Morning meeting | id: 1 | done: 0


	نلاحظ من الخرج السابق أنّ قيمة العمود done هي 0 لكافّة عناصر المهام، لعدم تحديد أيٍّ منها على أنه مُنجز بعد، والآن وحتى يتمكن المستخدمون من تعديل هذه القيمة للمهام المُنجزة، سننشئ وجهة جديدة في الملف app.py.



	لذلك، سنفتح الملف app.py:


(env)user@localhost:$ nano app.py


	ومن ثمّ سنضيف الشيفرة التالية إلى نهاية الملف لإضافة وجهة جديدة /do/:


. . .
@app.route('//do/', methods=('POST',))
def do(id):
    conn = get_db_connection()
    conn.execute('UPDATE items SET done = 1 WHERE id = ?', (id,))
    conn.commit()
    conn.close()
    return redirect(url_for('index'))


	تتعامل هذه الوجهة الجديدة مع الطلبات الواردة وفق الطريقة POST فقط، إذ تستقبل دالة فلاسك ()do معرّف العنصر المراد تمييزه على أنه منجز id وسيطًا، ليفتح اتصالًا مع قاعدة البيانات، ثمّ يغيّر قيمة العمود done من 0 إلى 1 للعنصر المطلوب تمييزه على أنه مُنجزٌ باستخدام التعليمة UPDATE في SQL.



	وقد استخدمنا الموضع المؤقت ? في الدالة ()execute، ثم مررنا مجموعة البيانات الحاوية على معرّف العنصر ID ما يضمن إدراجًا صحيحًا وآمنًا للبيانات في قاعدة البيانات. نهايةً، أغلقنا الاتصال مع قاعدة البيانات بعد تأكيد التغييرات ليُعاد توجيه المستخدم إلى الصفحة الرئيسية index.



	الآن وبعد الانتهاء من إضافة الوجهة المسؤولة عن تمييز عناصر المهام على أنها مُنجزة، لا بدّ من إضافة وجهة جديدة للتراجع، بمعنى إمكانية إلغاء تمييز عنصر المهام على أنه مُنجز، لذا سنضيف الوجهة التالية إلى نهاية الملف app.py:


. . .
@app.route('//undo/', methods=('POST',))
def undo(id):
    conn = get_db_connection()
    conn.execute('UPDATE items SET done = 0 WHERE id = ?', (id,))
    conn.commit()
    conn.close()
    return redirect(url_for('index'))


	نلاحظ أنّ شيفرة هذه الوجهة مشابهةٌ إلى حدٍ كبير لسابقتها /do/، كما أنّ دالة فلاسك ()undo تماثل الدالة ()do تمامًا بطريقة عملها ماعدا كونها تخصّص القيمة 0 للعمود done بدلًا من القيمة 1.



	اِحفظ الملف وأغلقه.



	الآن وبعد إضافة كل من الوجهتين /do/ و /undo/، سنضيف زرًا مهمّته تمييز عنصر المهام المعروض على أنه مُنجز (من خلال إضافة خط متوسّط له) أم لا اعتمادًا على حالته، أي حسب قيمة العمود done في قاعدة البيانات، لذا سنفتح ملف قالب HTML المُسمّى index.html:


(env)user@localhost:$ nano templates/index.html


	وسنعدّل محتويات حلقة for التكرارية داخل عنصر القائمة غير المرتبة 
 لتصبح على النحو التالي:


{% block content %}
    <h1>{% block title %} Welcome to FlaskTodo {% endblock %}h1>
    {% for list, items in lists.items() %}
        <div class="card" style="width: 18rem; margin-bottom: 50px;">
            <div class="card-header">
                <h3>{{ list }}h3>
            div>
            <ul class="list-group list-group-flush">
                {% for item in items %}
                    <li class="list-group-item"
                    {% if item['done'] %}
                    style="text-decoration: line-through;"
                    {% endif %}
                    >{{ item['content'] }}
                    {% if not item ['done'] %}
                        {% set URL = 'do' %}
                        {% set BUTTON = 'Do' %}
                    {% else %}
                        {% set URL = 'undo' %}
                        {% set BUTTON = 'Undo' %}
                    {% endif %}
                  <div class="row">
                        <div class="col-12 col-md-3">
                            <form action="{{ url_for(URL, id=item['id']) }}"
                                method="POST">
                                <input type="submit" value="{{ BUTTON }}"
                                    class="btn btn-success btn-sm">
                            form>
                        div>
                    div>
                    li>
                {% endfor %}
            ul>
        div>
    {% endfor %}
{% endblock %}


	أسندنا في الشيفرة السابقة وضمن الحلقة for القيمة line-through لسمة تنسيق النص text-decoration في CSS، والتي تضيف خطًّا متوسطًا للنص في حال كان عنصر القوائم مُنجزًا تبعًا لقيمة السجل الموافق للعنصر من العمود done في قاعدة البيانات، ثمّ استخدمنا تعليمة set من تعليمات محرّك القوالب جينجا Jinja لنصرّح عن متغيرين، هما URL و BUTTON؛ فإذا كان العنصر غير مُحدّدٍ على أنه مُنجز، سيأخذ المتغير BUTTON القيمة Do وسيشير المتغيّر URL إلى الوجهة /do/؛ أمّا إذا كان العنصر محّددًا على أنه مُنجَز، فسيأخذ المتغير BUTTON القيمة Undo، وسيشير المتغيّر URL إلى الوجهة /undo/. استخدمنا بعد ذلك هذين المتغيرين في نموذج إدخال يُرسل الطلب المناسب اعتمادًا على حالة عنصر المهام.



	نشغّل الخادم:


(env)user@localhost:$ flask run


	الآن وبالذهاب إلى الرابط "/http://127.0.0.1:5000" في المتصفح، أصبح بالإمكان تمييز عناصر المهام المُنجزة من الصفحة الرئيسية للتطبيق، في الخطوة التالية سنعمل على إضافة إمكانية تعديل عناصر المهام.



	الخطوة الثالثة - تعديل عناصر المهام



	سنضيف إلى التطبيق في هذه الخطوة صفحةً جديدةً خاصةً بتحرير عناصر المهام، ما سيتيح إمكانية تعديل محتويات كل عنصر من عناصر المهام، إضافةً لإمكانية ربط هذه العناصر مع قوائم مختلفة.



	الآن وضمن الملف app.py سنضيف وجهة جديدة /edit/، مهمته إخراج صفحة HTML جديدة باسم edit.html، والتي تتيح للمستخدمين إمكانية التعديل على عناصر المهام الحالية، وهنا يتوجب علينا تحديث الملف index.html لإضافة زر Edit لكل عنصر مهام.



	بدايةً سنفتح الملف app.py:


(env)user@localhost:$ nano app.py


	ثم سنضيف الشيفرات الخاصّة بالوجهة الجديدة في نهاية الملف على النحو التالي:


. . .
@app.route('//edit/', methods=('GET', 'POST'))
def edit(id):
    conn = get_db_connection()

    todo = conn.execute('SELECT i.id, i.list_id, i.done, i.content, l.title \
                         FROM items i JOIN lists l \
                         ON i.list_id = l.id WHERE i.id = ?', (id,)).fetchone()

    lists = conn.execute('SELECT title FROM lists;').fetchall()

    if request.method == 'POST':
        content = request.form['content']
        list_title = request.form['list']

        if not content:
            flash('Content is required!')
            return redirect(url_for('edit', id=id))

        list_id = conn.execute('SELECT id FROM lists WHERE title = (?);',
                                 (list_title,)).fetchone()['id']

        conn.execute('UPDATE items SET content = ?, list_id = ?\
                      WHERE id = ?',
                     (content, list_id, id))
        conn.commit()
        conn.close()
        return redirect(url_for('index'))

    return render_template('edit.html', todo=todo, lists=lists)


	تُستخدم القيمة id وسيطًا في دالة فلاسك الجديدة المُبيّنة في الشيفرة السابقة لجلب معرّف عنصر المهام المُراد تحريره، إضافةً إلى معرّف وعنوان القائمة التي ينتمي إليها، وقيمة السجل الموافق من العمود done، ومحتوى العنصر، وذلك باستخدام التعليمة JOIN في SQL. تُحفظ هذه البيانات في متغيرٍ باسم todo، ثمّ تُجلب كافّة قوائم المهام من قاعدة البيانات وتُخزّن في المتغير lists.



	في حال كان الطلب عاديًا وفق الطريقة GET، فإن الشرط التالي الدال على كون الطلب من نوع POST لن يتحقّق:


if request.method == 'POST'


	وبالتالي سينتقل التطبيق لتنفيذ دالة إخراج القوالب ()render_template الذي سيمرِّر قيم المتغيرين todo و lists إلى الملف edit.html المُخرج.



	أمّا في حال تأكيد نموذج وإرساله من قبل المستخدم، عندها سيتحقّق الشرط:


request.method == 'POST'


	ونستخلص بالتالي المحتوى والعنوان المُعدّلين المُدخلين في النموذج المُرسل؛ وفي حال عدم وجود أي محتوى، ستُعرض رسالةٌ تُخبر المستخدم بأن حقل المحتوى مطلوب "!Content is required"، ويُعاد توجيهه إلى الصفحة الرئيسية index مجدّدًا؛ وإلّا في حال وجود عنوان ومحتوى في النموذج المُرسل، يُجلب معرّف ID القائمة المُرسلة في النموذج بما يسمح للمُستخدم بنقل عنصر المهام من قائمةٍ لأُخرى.



	نُحدّث محتوى عنصر المهام -باستخدام التعليمة UPDATE في SQL- إلى المحتوى الجديد المُدخل من قبل المستخدم، ويحدث الأمر نفسه بالنسبة لمعرّف القائمة، إذ يُربط عنصر المهام مع القائمة الجديدة في حال تعديل المستخدم القائمة التي ينتمي إليها العنصر. نهايةً، نحفظ التغييرات ونغلق الاتصال مع قاعدة البيانات ونعيد توجيه المستخدم إلى الصفحة الرئيسية index.



	اِحفظ الملف وأغلقه.



	لاستخدام هذه الوجهة سنحتاج إلى قالب HTML جديد باسم edit.html:


(env)user@localhost:$ nano templates/edit.html


	ونكتب ضمنه الشيفرة التالية:


{% extends 'base.html' %}

{% block content %}

{% block title %} Edit an Item {% endblock %}

 method="post">
     class="form-group">
         for="content">Content
         type="text" name="content"
               placeholder="Todo content" class="form-control"
               value="{{ todo['content'] or request.form['content'] }}">
    

     class="form-group">
         for="list">List
         class="form-control" name="list">
            {% for list in lists %}
                {% if list['title'] == request.form['list'] %}
                     value="{{ request.form['list'] }}" selected>
                        {{ request.form['list'] }}
                    

                {% elif list['title'] == todo['title'] %}
                     value="{{ todo['title'] }}" selected>
                        {{ todo['title'] }}
                    

                {% else %}
                     value="{{ list['title'] }}">
                        {{ list['title'] }}
                    
                {% endif %}
            {% endfor %}
        
    
     class="form-group">
         type="submit" class="btn btn-primary">Submit
    

{% endblock %}


	تُستخدم التعليمة التالية:


{{ todo['content'] or request.form['content']‎ }}


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



	وبالنسبة لنموذج اختيار القائمة التي ينتمي إليها العنصر، سنتبِّع الآلية السابقة ذاتها، بمعنى أننا سنمر على المتغير lists الحاوي على عنوان القائمة؛ فإذا كان هذا العنوان مطابقًا لذلك المُخزّن في الكائن request.form (من النموذج المُرسل) عندها يقع الاختيار على عنوان القائمة هذه ليصبح العنصر تابعًا لها؛ أما في حال كان عنوان القائمة في المتغير lists مطابقًا للعنوان في المتغير todo فهذا يعني أنّه لم يطرأ أي تعديل على عنوان القائمة التي ينتمي إليها العنصر ويبقى كما كان أصلًا دون تعديلات؛ وبالنسبة لباقي الخيارات فستُعرض دون وجود السمة selected بمعنى أنها غير قابلةٍ للتعديل.



	اِحفظ الملف وأغلقه.



	الآن، سنفتح الملف index.html لإضافة زر تحرير عنصر القوائم Edit:


(env)user@localhost:$ nano templates/index.html


	سنغيّر محتويات الوسم div بالصنف "row" لإضافة عمودٍ جديد، كما هو مُوضَّح في الشيفرة التالية:


. . .
 class="row">
     class="col-12 col-md-3">
         action="{{ url_for(URL, id=item['id']) }}"
            method="POST">
             type="submit" value="{{ BUTTON }}"
                class="btn btn-success btn-sm">
        
    
     class="col-12 col-md-3">
         class="btn btn-warning btn-sm"
        href="{{ url_for('edit', id=item['id']) }}">Edit
    



	اِحفظ الملف وأغلقه.



	استخدمنا في الشيفرة السابقة وسم الروابط  الذي سيوجّه المستخدم إلى وجهة التحرير /edit/ لكل عنصرٍ من عناصر المهام.



	شغِّل خادم التطوير في حال لم يكن مُشغّلًا:


(env)user@localhost:$ flask run


	وبالذهاب إلى الرابط "/http://127.0.0.1:5000" في المتصفح، نجد أنّه أصبح بالإمكان تعديل أي عنصر مهام. سنعمل في الخطوة التالية على إضافة زر حذف عناصر مهام.



	الخطوة الرابعة - حذف عناصر مهام



	سنضيف في هذه الخطوة إمكانية حذف عناصر مهام محدّدة، لذا سننشئ وجهة جديدة في الملف app.py باسم delete:


(env)user@localhost:$ nano app.py


	ثمّ سنضيف الشيفرة التالية إلى نهاية الملف لإضافة وجهة جديدة باسم /delete/:


. . .
@app.route('//delete/', methods=('POST',))
def delete(id):
    conn = get_db_connection()
    conn.execute('DELETE FROM items WHERE id = ?', (id,))
    conn.commit()
    conn.close()
    return redirect(url_for('index'))


	اِحفظ الملف وأغلقه.



	تستخدم دالة فلاسك ()delete معرّف id العنصر وسيطًا، فعند إرسال طلب HTTP من نوع POST، نستخدم تعليمة DELETE في SQL لحذف العنصر الموافق لهذا المعرّف، ثمّ نحفظ التغييرات ونغلق الاتصال مع قاعدة البيانات ونعيد توجيه المستخدم إلى الصفحة الرئيسية index.



	الآن، سنفتح الملف index.html الموجود في مجلد القوالب templates لإضافة زر الحذف:


(env)user@localhost:$ nano templates/index.html


	نضيف بعد ذلك وسم 
 لإضافة زر الحذف Delete بعد الجزء الخاص بزر التحرير Edit:


 class="row">
     class="col-12 col-md-3">
         action="{{ url_for(URL, id=item['id']) }}"
            method="POST">
             type="submit" value="{{ BUTTON }}"
                class="btn btn-success btn-sm">
        
    


     class="col-12 col-md-3">
         class="btn btn-warning btn-sm"
        href="{{ url_for('edit', id=item['id']) }}">Edit
    

     class="col-12 col-md-3">
         action="{{ url_for('delete', id=item['id']) }}"
            method="POST">
             type="submit" value="Delete"
                class="btn btn-danger btn-sm">
        
    



	يرسل زر الحذف الجديد في الشيفرة السابقة طلبًا من نوع POST إلى وجهة route الحذف /delete/ لكل عنصرٍ مراد حذفه.



	اِحفظ الملف وأغلقه.



	الآن، نشغّل خادم التطوير:


(env)user@localhost:$ flask run


	وبالذهاب إلى الرابط "/http://127.0.0.1:5000" في المتصفح، أصبح بالإمكان حذف أي عنصر مهام باستخدام زر الحذف Delete. سنضيف في الخطوة التالية والأخيرة إمكانية إنشاء قوائم جديدة.



	الخطوة الخامسة - إضافة قوائم جديدة



	لا يتيح تطبيقنا حتى الآن إضافة قوائم جديدة سوى في قاعدة البيانات مباشرةً، لذا في هذه الخطوة سنضيف إمكانية إنشاء قوائم جديدة لدى إضافة المستخدم عناصر جديدة بدلًا من إلزامه باختيار قائمة حصرًا من القوائم الموجودة أصلًا في قاعدة البيانات، وذلك بإضافة خيار جديد باسم قائمة جديدة New List، والذي باختياره سيتمكّن المستخدم من إدخال اسم القائمة الجديدة التي يرغب بإنشائها.



	لتنفيذ ذلك، سنفتح بدايةً الملف app.py:


(env)user@localhost:$ nano app.py


	ثمّ سنعدّل دالة فلاسك ()create من خلال إضافة الشيفرات المبينة أدناه إلى الجملة الشرطية التالية:


if request.method == 'POST'


	التي تختبر ما إذا كان الطلب مُرسلًا وفق الطريقة POST، على النحو التالي:


. . .
@app.route('/create/', methods=('GET', 'POST'))
def create():
    conn = get_db_connection()

    if request.method == 'POST':
        content = request.form['content']
        list_title = request.form['list']

        new_list = request.form['new_list']

        # If a new list title is submitted, add it to the database
        if list_title == 'New List' and new_list:
            conn.execute('INSERT INTO lists (title) VALUES (?)',
                         (new_list,))
            conn.commit()
            # Update list_title to refer to the newly added list
            list_title = new_list

        if not content:
            flash('Content is required!')
            return redirect(url_for('index'))

        list_id = conn.execute('SELECT id FROM lists WHERE title = (?);',
                                 (list_title,)).fetchone()['id']
        conn.execute('INSERT INTO items (content, list_id) VALUES (?, ?)',
                     (content, list_id))
        conn.commit()
        conn.close()
        return redirect(url_for('index'))

    lists = conn.execute('SELECT title FROM lists;').fetchall()

    conn.close()
    return render_template('create.html', lists=lists)


	اِحفظ الملف وأغلقه.



	حفظنا في الشيفرة السابقة قيمة حقل نموذج الإدخال الجديد المُسمّى new_list ضمن متغير ليُضاف هذا الحقل لاحقًا إلى الملف create.html، ثمّ اختبرنا كون قيمة المتغير list_title تساوي New List من خلال الشرط:


list_title == 'New List' and new_list


	والذي يعني بتحقيقه أنّ المستخدم يرغب بإنشاء قائمة جديدة، وهنا لا بدّ من التحقّق من كون قيمة المتحول new_list ليست فارغة None، فعندها سنستخدم التعليمة INSERT INTO في SQL لإضافة عنوان السلسلة الجديد المُدخل من قبل المستخدم إلى جدول القوائم lists من قاعدة البيانات. نهايةً، سنحفظ التغييرات ونحدّث قيمة متغير عنوان القائمة list_title لتصبح موافقةً لعنوان القائمة الجديدة لاستخدامه لاحقًا.



	بعد ذلك، سنفتح الملف create.html لإضافة وسم اختيار  جديد، وهذا يتيح للمستخدم إمكانية إضافة قائمة مهام جديدة:


(env)user@localhost:$ nano templates/create.html


	وسنعدِّله ليصبح كما يلي:


 class="form-group">
         for="list">List
         class="form-control" name="list">
             value="New List" selected>New List
            {% for list in lists %}
                {% if list['title'] == request.form['list'] %}
                     value="{{ request.form['list'] }}" selected>
                        {{ request.form['list'] }}
                    
                {% else %}
                     value="{{ list['title'] }}">
                        {{ list['title'] }}
                    
                {% endif %}
            {% endfor %}
        
    

     class="form-group">
         for="new_list">New List
         type="text" name="new_list"
                placeholder="New list name" class="form-control"
                value="{{ request.form['new_list'] }}">
    

     class="form-group">
         type="submit" class="btn btn-primary">Submit
    


	اِحفظ الملف وأغلقه.



	أضفنا في الشيفرة السابقة وسم اختيار  جديد لإضافة خيار إنشاء قائمة جديدة New List، وهذا سيسمح للمستخدم بإضافة قائمة جديدة إن رغب، ثمّ أضفنا وسم 
 آخر ذو حقل إدخال باسم new_list، إذ سيُدخل فيه المستخدم عنوان القائمة الجديدة المُنشأة.



	الآن نشغّل خادم التطوير:


(env)user@localhost:$ flask run


	وبالذهاب إلى الرابط "/http://127.0.0.1:5000" في المتصفح، ستبدو الصفحة الرئيسية index كما هي موضحة في الصورة التالية:



	



	وبذلك نكون قد أنشأنا تطبيق إدارة مهام بعدّة ميزات تمكّن مستخدميه من تمييز عناصر المهام المُنجزة، إضافةً لإمكانية تعديل أو حذف العناصر الموجودة أصلًا، وإمكانية إنشاء قوائم جديدة لمختلف أنواع المهام.



	يمكنك الاطلاع على شيفرة البرنامج كاملةً.



	الخاتمة



	من خلال اتبّاع ما شرحناه في مقالنا هذا ستحصل على تطبيق متكامل لإدارة قوائم وعناصر المهام، والذي يتمتّع بالعديد من الميزات المتمثلة بتمكين مستخدميه من تمييّز عناصر مهامهم، مثل عناصر "مُنجزة complete" أو إعادة تعيين العناصر المميزة على أنها مُنجزة مجدّدًا إلى الحالة "غير مُنجزة non-completed"، فضلًا عن توفّر إمكانية تعديل وحذف العناصر الموجودة أصلًا، وإمكانية إنشاء قوائم جديدة لمختلف أنواع المهام.



	يمثّل هذا المقال وسيلةً عمليةً لتعلّم كيفية استخدام فلاسك وSQLite لإدارة جداول قواعد البيانات، وتوظيف المعارف النظرية هذه في إطار عملي عن طريق تطوير تطبيق ويب قائم على فلاسك والتعديل عليه وإضافة ميزات جديدة ضمنه وتعديل عناصر قاعدة البيانات من النوع one-to-many.



	ترجمة -وبتصرف- للمقال How To Modify Items in a One-to-Many Database Relationships with Flask and SQLite لصاحبه Abdelhadi Dyouri.



	اقرأ أيضًا




		إنشاء تطبيق ويب باستخدام إطار عمل فلاسك Flask من لغة بايثون
	
	
		استخدام علاقة one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite
	




استخدام علاقة one-to-many مع إطار العمل فلاسك Flask ومحرك قواعد البيانات SQLite
Tue, 12 Jul 2022 16:07:00 +0000




	فلاسك هو إطار عمل يستخدم لغة بايثون Python لبناء تطبيقات الويب؛ أما SQLite فهو محرّك قواعد بيانات يُستخدم لتخزين بيانات تطبيق الويب.



	سننشئ في هذا المقال تطبيق ويب لإدارة المهام باستخدام كلٍ من إطار العمل فلاسك ومحرّك قاعدة البيانات SQLite، إذ سيتمكّن مستخدمو التطبيق من إنشاء قوائم تمثّل عناصر المهام المطلوبة.



	تتمثّل الفائدة العلمية والعملية من هذا المقال بتعلمّك كيفيّة استخدام SQLite مع فلاسك، بالإضافة لتعلّم كيفيّة إنشاء علاقات قاعدة البيانات من النوع واحد-إلى-متعدد.



	تُعرَّف علاقة قاعدة البيانات من النوع واحد-إلى-متعدد one-to-many بكونها علاقةٌ بين جدولين من قاعدة البيانات، بحيث يمكن لسجلٍ موجودٍ في أحد الجدولين الإشارة إلى عدّة سجلات من الجدول الثاني، ويشكّل تطبيق المدونة خير مثال على العلاقات في قواعد البيانات من النوع واحد-إلى-متعدد، نظرًا لارتباط الجدول الخاص بتخزين التدوينات posts مع الجدول الخاص بتخزين التعليقات comments بعلاقة من نوع واحد-إلى-متعدد؛ إذ يمكن أن يكون لكل تدوينة عدّة تعليقاتٍ مرتبطةٍ بها، وبالمقابل يرتبط كل تعليق بتدوينة واحدةٍ فقط، وبذلك فإنّ للتدوينة الواحدة علاقةٌ بالعديد من التعليقات. وفي هذه الحالة يُعد الجدول الخاص بالتدوينات "الجدول الأب parent"، في حين يُعد الجدول الخاص بالتعليقات "الجدول الابن child"؛ إذ يمكن للسجل الموجود في الجدول الأب الإشارة إلى عدّة سجلات موجودة في الجدول الابن، وهو أمرٌ أساسي لإتاحة إمكانية الوصول إلى البيانات المطلوبة في كل جدول.



	تتجلى إحدى دوافع استخدامنا لمحرّك قاعدة البيانات SQLite بكونه مرنًا من ناحية نقل البيانات عبر الأجهزة وبيئات التشغيل المختلفة Portable من جهة؛ وبكونه يعمل بسهولة مع لغة البرمجة بايثون دون الحاجة لتطبيق أي إعدادات إضافية من جهة أخرى؛ أمّا الدافع الآخر لاستخدامه فيتمثل بكونه مناسبًا جدًا لتصميم النماذج الأولية لتطبيقات الويب المنشئة قبل الانتقال إلى العمل على قاعدة البيانات الأكبر، مثل قاعدة بيانات MySQL، أو Postgres.



	مستلزمات العمل



	توجد مجموعةٌ من المتطلبات الواجب توفرّها وإعدادها قبل البدء في اتباع الخطوات التفصيلية المشروحة تاليًا ضمن هذا المقال، وهذه المتطلبات هي:




		توفُّر بيئة برمجة بايثون 3 محلية، وفي مقالنا سنسمّي مجلد المشروع بالاسم flask_todo.
	
	
		فهم مختلف مفاهيم فلاسك الأساسية، مثل إنشاء الوجهات وإخراج قوالب HTML والاتصال بقاعدة بيانات SQLite.
	


	الخطوة الأولى - إنشاء قاعدة البيانات



	سننفّذ في هذه الخطوة مجموعةً من الخطوات الفرعية المتمثّلة بتنشيط البيئة البرمجية التي سنعمل عليها، وتثبيت فلاسك، وإنشاء قاعدة بيانات SQLite، وتعبئتها ببيانات معياريّة، وسنتعلم كذلك كيفيّة استخدام المفاتيح الأجنبية foreign keys، لإنشاء علاقة واحد-إلى-متعدّد بين القوائم والعناصر؛ إذ يمثّل المفتاح الأجنبي صلة الوصل لربط جدول من قاعدة البيانات بآخر، فهو الرابط بين الجدول الابن والجدول الأب في قاعدة البيانات هذه، والمفتاح الأساسي لجدولٍ ما هو مفتاحٌ أجنبي للجداول الأُخرى.



	إذا لم تنشّط البيئة البرمجية الخاصة بك بعد، فاستخدم الأمر التالي لتنشيطها بعد التأكّد من كون موجه الأوامر يشير إلى مسار مجلد المشروع flask_todo:


$ source env/bin/activate


	وبمجرّد تنشيط البيئة البرمجية، ثبّت فلاسك باستخدام الأمر التالي:


(env)user@localhost:$ pip install flask


	ومع اكتمال تثبيت فلاسك، أصبح بإمكانك الآن إنشاء مخطّط قاعدة البيانات المتضمِّن أوامر SQL اللازمة لإنشاء الجداول التي تحتاجها لتخزين بيانات المهام المطلوبة، إذ ستحتاج إلى جدولين، جدول يسمى lists لتخزين قوائم المهام، وجدول يسمى items لتخزين عناصر كل قائمة.



	الآن سننشئ ملفًا باسم schema.sql ضمن المجلد flask_todo:


(env)user@localhost:$ nano schema.sql


	وسنكتب أوامر SQL التالية داخل هذا الملف:


DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;

CREATE TABLE lists (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    title TEXT NOT NULL
);

CREATE TABLE items (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    list_id INTEGER NOT NULL,
    created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    content TEXT NOT NULL,
    FOREIGN KEY (list_id) REFERENCES lists (id)
);


	اِحفظ الملف وأغلقه.



	أوّل سطرين من شيفرة SQL السابقة مسؤولان عن حذف أي جداول موجودة سابقًا ضمن قاعدة البيانات باسم lists أو items، وهما:


DROP TABLE IF EXISTS lists;
DROP TABLE IF EXISTS items;


	وبذلك لن يكون هناك أي سلوكٍ متضاربٍ أو عشوائي ناجمٍ عن تشابه الأسماء ضمن قاعدة البيانات، ومن الجدير بالملاحظة أنّ تطبيق هذين الأمرين سيؤدي إلى حذف كامل محتوى قاعدة البيانات الحالي، لذا لا تُدخل أي بيانات مهمّة في التطبيق حتى تنتهي من كافّة الخطوات التعليميّة في المقال وتجربة نتائجه النهائية.



	بعد ذلك، يمكنك استخدام الأمر CREATE TABLE lists لإنشاء جدول القوائم lists، الذي سيخزن قوائم المهام المطلوبة، مثل قائمة الدراسة وقائمة العمل والقائمة الرئيسية، وما إلى ذلك، باستخدام الأعمدة التالية:




		"id": ويحتوي على بيانات من نوع الرقم الصحيح، ويمثّل مفتاحًا أساسيًا للجدول lists، وسيتضمّن قيم فريدة في قاعدة البيانات من أجل كل سجل، والسجل هو نوعٌ من أنواع قوائم المهام في حالتنا.
	
	
		"created": يحتوي على تاريخ ووقت إنشاء قائمة المهام، وتشير NOT NULL لكون هذا العمود لا يجب أن يحتوي على قيم فارغة، أما القيمة الافتراضية فهي CURRENT_TIMESTAMP، والتي تمثّل تاريخ ووقت إضافة قائمة المهام إلى قاعدة البيانات، وكما هو الحال في عمود "id" لا يتوجب عليك تحديد قيم لهذا العمود، لأن تعبئتها تلقائية.
	
	
		"title": عنوان قائمة المهام.
	


	وبعد إنشاء جدول القوائم lists، سننشئ الآن جدول العناصر items لتخزين عناصر المهام، إذ يحتوي هذا الجدول على معرّف "ID"، وعمود "list_id" يحوي أعدادًا صحيحة تحدّد معرّف القائمة التي ينتمي إليها العنصر، إضافةً لعمود تاريخ إنشاء العنصر، وعمود محتوى المهمّة.



	يمكنك استخدام مفتاح أجنبي لربط عنصرٍ ما بقائمةٍ معيّنة في قاعدة البيانات عن طريق كتابة الشيفرة التالية:


 FOREIGN KEY (list_id) REFERENCES lists (id)


	يمثّل جدول القوائم lists الجدول الأب المربوط بالجدول الآخر باستخدام المفتاح الأجنبي، وهذا يبيّن امكانية احتواء القائمة الواحدة على عدّة عناصر؛ في حين يمثّل جدول العناصر items الجدول الحاوي على المفتاح الأجنبي، وهذا يعني أن كل عنصر ينتمي إلى قائمة واحدةٍ فقط. يشير العمود list_id من جدول العناصر items الابن إلى عمود المعرِّف id من جدول القوائم lists الأب.



	وبذلك نجد أنّه قد حققنا فعليًا علاقة واحد-إلى-متعدّد بين جدولي lists و items، نظرًا لأنّ القائمة يمكن أن تحتوي على عدّة عناصر، وأنّ العنصر الواحد سينتمي إلى قائمةٍ واحدةٍ فقط.



	بعد الانتهاء من إنشاء الجداول، سنستخدم ملف schema.sql لإنشاء قاعدة البيانات. لذلك، أنشئ ملفًا باسم init_db.py ضمن المجلد flask_todo على النحو التالي:


(env)user@localhost:$ nano init_db.py


	ثم أضِف فيه الشيفرة التالية:


import sqlite3

connection = sqlite3.connect('database.db')


with open('schema.sql') as f:
    connection.executescript(f.read())

cur = connection.cursor()

cur.execute("INSERT INTO lists (title) VALUES (?)", ('Work',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Home',))
cur.execute("INSERT INTO lists (title) VALUES (?)", ('Study',))

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (1, 'Morning meeting')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Buy fruit')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (2, 'Cook dinner')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn Flask')
            )

cur.execute("INSERT INTO items (list_id, content) VALUES (?, ?)",
            (3, 'Learn SQLite')
            )

connection.commit()
connection.close()


	اِحفظ الملف وأغلقه، وبمجرّد تنفيذ الشيفرة السابقة سيُنشأ ملفٌ باسم database.db ويُحقَّق الاتصال به، وبعدها يمكننا فتح ملف schema.sql وتشغيله باستخدام التابع ()executescript الذي ينفِّذ العديد من تعليمات SQL البرمجية في وقتٍ واحد.



	سيؤدي تشغيل الملف schema.sql لإنشاء جداول القوائم والعناصر، ومن ثمّ سننفّذ عددًا من تعليمات الإدخال في SQL لإنشاء ثلاث قوائم وخمسة عناصر مهام باستخدام كائن المؤشر Cursor.



	سنستخدم العمود "list_id" لربط كلّ عنصرٍ بقائمة عن طريق قيمة معرّف القائمة. فعلى سبيل المثال، إذا كانت القائمة المسمّاة "العمل Work" هي الإدخال الأوّل في قاعدة البيانات، فسيكون معرّفها ذو القيمة 1، وسنتمكّن باستخدامه من ربط عنصر المهام المسمّى "الاجتماع الصباحي Morning meeting" مثلًا بقائمة مهام العمل، وينطبق المبدأ نفسه على كافّة القوائم والعناصر الأُخرى.



	ومن ثمّ سنحفظ التغييرات ونغلق الاتصال، وسنشغّل البرنامج كما يلي:


(env)user@localhost:$ python init_db.py


	وبعد تنفيذ هذا البرنامج سيظهر ملفٌ جديدٌ ضمن المجلد flask_todo باسم database.db، ومع انتهاء هذه الخطوة نكون قد فعّلنا البيئة البرمجية وثبتنا فلاسك، وأنشأنا قاعدة بيانات SQLite، وبذلك سنتمكن من استرجاع كل ما أُدخِل في قاعدة البيانات من قوائم وعناصر لعرضها في الصفحة الرئيسية للتطبيق الذي نحن في صدد إنشائه.



	الخطوة الثانية - عرض عناصر المهام



	سنعمل في هذه الخطوة على ربط قاعدة البيانات التي أنشأناها في الخطوة السابقة مع تطبيق فلاسك الذي سيعرض قوائم المهام والعناصر الموجودة في كلٍ منها، كما سنستخدم استعلامات قواعد البيانات المركّبة SQLite joins للاستعلام عن بيانات من الجدولين معًا، وسنعمل على تجميع عناصر المهام حسب القوائم التابعة لها.



	أولاً، سننشئ ملف التطبيق، لذا أنشئ ملفًا باسم app.py في المجلد flask_todo:


(env)user@localhost:$ nano app.py


	ومن ثمّ سنضيف الشيفرة التالية إلى الملف:


from itertools import groupby
import sqlite3
from flask import Flask, render_template, request, flash, redirect, url_for


def get_db_connection():
    conn = sqlite3.connect('database.db')
    conn.row_factory = sqlite3.Row
    return conn


app = Flask(__name__)
app.config['SECRET_KEY'] = 'this should be a secret random string'


@app.route('/')
def index():
    conn = get_db_connection()
    todos = conn.execute('SELECT i.content, l.title FROM items i JOIN lists l \
                          ON i.list_id = l.id ORDER BY l.title;').fetchall()

    lists = {}

    for k, g in groupby(todos, key=lambda t: t['title']):
        lists[k] = list(g)

    conn.close()
    return render_template('index.html', lists=lists)


	اِحفظ الملف وأغلقه.



	تفتح الدالة ()get_db_connection اتصالًا مع ملف قاعدة البيانات database.db، وتحدّد بعد ذلك قيمة السمة row_factory لتكون sqlite3.Row لنتمكّن من الوصول إلى الأعمدة باستخدام أسمائها، ما يعني أنّ اتصال قاعدة البيانات سيعيد سجلات يمكننا التعامل معها كما هو الحال مع قواميس بايثون Dictionaries الاعتيادية (وهي حاويات لتخزين القيم المنظمّة في بايثون)، ونهايةً تعيد الدالة كائن الاتصال conn المُستخدم للوصول إلى قاعدة البيانات.



	الآن سنفتح اتصالًا مع قاعدة البيانات باستخدام دالة عرض فلاسك ()index، وسننفّذ استعلام SQL التالي:


SELECT i.content, l.title FROM items i JOIN lists l ON i.list_id = l.id ORDER BY l.title;


	وسنتمكن باستخدام الدالة ()fetchall من الحصول على نتائج الاستعلام وحفظها ضمن متغيّر todos.



	استخدمنا في الاستعلام السابق الأمر SELECT لجلب محتوى العنصر مع عنوان القائمة المنتمي إليها، عبر ربط كلٍ من جدولي القوائم والعناصر (إذ يشير الرمز i للعناصر، والرمز l للقوائم)، إذ سنحصل بالنتيجة على كافّة سجلات جدول العناصر ذات القيمة list_id الموافقة لقيمة المعرّف id من جدول القوائم باستخدام شرط التجميع i.list_id = l.id المكتوب بعد البادئة البرمجية ON، ومن ثمّ استخدمنا أمر الترتيب ORDER BY لفرز النتائج وفقًا لعناوين القوائم.



	الآن ولفهم هذا الاستعلام بوضوح، سنفتح موجه أوامر بايثون التفاعلي Python REPL في مجلد المشروع flask_todo:


(env)user@localhost:$ python


	ومن ثمّ سنختبر محتويات المتغير todos الحاوي على نتائج الاستعلام السابق عبر تشغيل الشيفرة التالية:


from app import get_db_connection
conn = get_db_connection()
todos = conn.execute('SELECT i.content, l.title FROM items i JOIN lists l \
ON i.list_id = l.id ORDER BY l.title;').fetchall()
for todo in todos:
    print(todo['title'], ':', todo['content'])


	استوردنا في الشيفرة السابقة قاعدة البيانات getdbconnection من الملف app.py، ومن ثمّ فُتِح الاتصال مع قاعدة البيانات ونُفِّذ الاستعلام (وهو استعلام SQL ذاته الموجود في الملف app.py)، وباستخدام حلقة for التكرارية طُبِع عنوان كل قائمة ومحتويات كل عنصر مهام مرتبطٍ بها، وبذلك سيظهر الخرج في حالتنا على النحو التالي:


Home : Buy fruit
Home : Cook dinner
Study : Learn Flask
Study : Learn SQLite
Work : Morning meeting


	أغلق موجه أوامر بايثون REPL باستخدام الاختصار "CTRL+D".



	الآن، وبعدما فهمت آلية عمل ونتائج الاستعلامات المُجمّعة في SQL، سنعود إلى دالة فلاسك ()index الموجودة في الملف app.py، إذ سنصرّح بدايةً عن المتغير todos ومن ثمّ سنستخدم الشيفرة التالية لتجميع النتائج:


lists = {}
for k, g in groupby(todos, key=lambda t: t['title']):
    lists[k] = list(g)


	تبدأ الشيفرة المبينة أعلاه بالتصريح عن قاموس dictionary فارغ باسم lists، ثم تستخدم حلقة for التكرارية لتجميع النتائج الموجودة في المتغير todos وترتيبها حسب عنوان قائمة المهام باستخدام دالة الترتيب ()groupby المستوردة من المكتبة المعيارية itertools، إذ تولّد هذه الدالة مجموعةً من النتائج من أجل كل تكرار في الحلقة عبر مروره على كل عنصرٍ مخزّنٍ في المتغير todos.



	يمثّل متغيّر الحلقة k عناوين قوائم المهام (المنزل والدراسة والعمل في حالتنا) المُستخرجة من قاعدة البيانات عبر تمرير قيمة التابع ['lambda t: t['title وسيطًا لدالة التجميع ()groupby، التي تُعيد عنوان القائمة التي يتبع لها هذا العنصر (بنفس مبدأ الدالة ['todo['title المُستخدم في حلقة for السابقة)؛ بينما يمثّل المتغير g المجموعة الحاوية على عناصر المهام التابعة لكل عنوان قائمة. فمن أجل أول دورة في الحلقة مثلًا، سيمثّل المتغير k القائمة Home، في حين سيتكرر المتغير g ليحتوي بالنتيجة عناصر القائمة الموجودة في k وهي في حالتنا "Buy fruit" و "Cook".



	وهذا ما يمثّل علاقةً من نوع واحد-إلى-متعدّد بين القوائم والعناصر، بحيث يضم كل عنوان قائمة مجموعةً من عناصر المهام. وبذلك، ستظهر القوائم عند تشغيل الملف app.py وبعد انتهاء تنفيذ حلقة for على النحو التالي:


{'Home': [<sqlite3.Row object at 0x7f9f58460950>,
          <sqlite3.Row object at 0x7f9f58460c30>],
 'Study': [<sqlite3.Row object at 0x7f9f58460b70>,
           <sqlite3.Row object at 0x7f9f58460b50>],
 'Work': [<sqlite3.Row object at 0x7f9f58460890>]}


	وسيحتوي كل كائن sqlite3.Row على البيانات المُسترجعة باستخدام استعلام SQL في الدالة ()index من جدول العناصر items، ولعرض هذه البيانات بوضوح أكثر، سنكتب برنامجًا يمر على محتويات الحاوية lists مستعرضًا كل قائمة وعناصرها.



	لكتابة هذا البرنامج، سنفتح ملفًا باسم list_example.py في المجلد flask_todo:


(env)user@localhost:$ nano list_example.py


	ثمّ سنكتب ضمنه الشيفرات التالية:


from itertools import groupby
from app import get_db_connection

conn = get_db_connection()
todos = conn.execute('SELECT i.content, l.title FROM items i JOIN lists l \
                        ON i.list_id = l.id ORDER BY l.title;').fetchall()

lists = {}

for k, g in groupby(todos, key=lambda t: t['title']):
    lists[k] = list(g)

for list_, items in lists.items():
    print(list_)
    for item in items:
        print('    ', item['content'])


	اِحفظ الملف وأغلقه.



	الشيفرة السابقة مشابهةٌ إلى حد كبير لتلك الموجودة في الدالة ()index، وتبيّن حلقة for التكرارية فيها كيفيّة هيكلة حاوية القوائم، إذ تبدأ بالمرور على عناصر الحاوية، التي تمثّل القوائم لطباعة عناوين هذه القوائم والموجودة ضمن المتغير list_variable، ومن ثمّ المرور على كافّة عناصر المهام التابعة لكل قائمة وطباعة محتويات كل منها.



	وبتشغيل البرنامج list_example.py:


(env)user@localhost:$ python list_example.py


	نحصل على الخرج التالي:


Home
     Buy fruit
     Cook dinner
Study
     Learn Flask
     Learn SQLite
Work
     Morning meeting


	الآن وبعد فهم كل جزئية في الدالة ()index، سننشئ قالبًا رئيسي وسنعمل على إخراج الملف index.html باستخدام الأمر التالي:


return render_template('index.html', lists=lists)


	لذا، سننشئ مجلدًا للقوالب باسم templates ضمن المجلد flask_todo وسنفتح ضمنه ملفًا باسم base.html:


(env)user@localhost:$ mkdir templates
(env)user@localhost:$ nano templates/base.html


	والآن سنكتب شيفرة بوتستراب Bootstap التالية ضمن الملف base.html، وإن لم تكن قوالب HTML في فلاسك مألوفةً بالنسبة لك، يمكنك قراءة الخطوة الثالثة من المقال كيفية إنشاء تطبيق ويب باستخدام إطار فلاسك في لغة بايثون 3.



 lang="en">
  
    
     charset="utf-8">
     name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    
     rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">

    </span><span class="pln">{% block title %} {% endblock %}</span><span class="tag">
  
  
     class="navbar navbar-expand-md navbar-light bg-light">
         class="navbar-brand" href="{{ url_for('index')}}">FlaskTodo
         class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
             class="navbar-toggler-icon">
        
         class="collapse navbar-collapse" id="navbarNav">
             class="navbar-nav">
             class="nav-item active">
                 class="nav-link" href="#">About
            
            
        
    
     class="container">
        {% block content %} {% endblock %}
    

    
    
     src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous">
     src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous">
     src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous">
  



	اِحفظ الملف وأغلقه.



	الجزء الأكبر من الشيفرة السابقة هو تعليمات HTML معيارية وشيفرات لازمة لعمل بوتستراب، إذ تزوّد الوسوم  متصفح الويب بالمعلومات، في حين ينشئ الوسم



	ارتباطًا إلى ملفات CSS الخاصة ببوتستراب، أما الوسم