حتى الآن نظّفت السعر " $129.00" مرة، وحسبت إيراد بند واحد مرة، وطبعت بضعة أرقام. لدى Cartwheel 3,991 بندًا في الطلبات. لا تريد نسخ كود التنظيف إلى كل مكان يحتاجه، ثم إصلاح خطأ واحد في سبع نسخ. الدوال تتيح لك كتابة المنطق مرة واحدة، ومنحه اسمًا، واستدعاءه حيثما احتجته.
def line_revenue(quantity, unit_price, discount=0.0):\n \"\"\"Revenue of one order line: quantity x price, minus the discount.\"\"\"\n return round(quantity * unit_price * (1 - discount), 2)\n\nprint(line_revenue(2, 129.0, 0.15)) # 219.3\nprint(line_revenue(1, 39.0)) # discount defaults to 0.0\nprint(line_revenue(quantity=3, unit_price=24.0, discount=0.25))الأجزاء هي: def، ثم اسم الدالة، ثم المُعامِلات بين قوسين، ثم نقطتان رأسيتان، ثم جسم مُزاح. وdiscount=0.0 قيمة افتراضية تُستخدم حين يتركها المستدعي. والسطر المحاط بثلاث علامات تنصيص تحت def هو docstring، يوثّق ما تفعله الدالة؛ وتعرضه المحرّرات حين تمرّر المؤشر فوق الاسم.
ترسل return قيمة إلى المستدعي، فيصبح الاستدعاء line_revenue(2, 129.0, 0.15) هو تلك القيمة. تستطيع تخزينها، أو جمعها، أو تمريرها إلى دالة أخرى. والاستدعاء بالأسماء، كما في المثال الثالث، يجعل قوائم الوسائط الطويلة مقروءة، ويحميك من تبديل رقمين بالخطأ.
هذه أداة تنظيف المبالغ من الدرس 1.2 وقد أصبحت قابلة لإعادة الاستخدام. تتعامل مع علامة الدولار والمسافات الزائدة وفواصل الآلاف:
\ndef parse_money(text):\n \"\"\"Turn strings like ' $1,234.50' into the float 1234.5.\"\"\"\n cleaned = text.strip().replace(\"$\", \"\").replace(\",\", \"\")\n return float(cleaned)\n\nfor raw in [\" $129.00\", \"18.00\", \"$1,234.50\"]:\n print(raw, \"->\", parse_money(raw))امنح الدوال أسماء أفعال تقول ما تعيده (parse_money وline_revenue وclean_country)، واجعل لكل منها مهمة واحدة؛ الدوال الصغيرة سهلة الاختبار ببضعة استدعاءات لـ print مثل الحلقة السابقة. الآن يستطيع كل مجموع فوضوي في الملف المُصدَّر أن يمرّ عبر دالة واحدة مُختبَرة. وإذا اكتشفت صيغة جديدة الشهر القادم (لنقل USD في نهاية النص)، فتصلحها في مكان واحد.
تقرير يقول 146825.4412 يجعل القرّاء يضيّقون أعينهم. الـ f-string، أي نص يسبق علامة تنصيصه الأولى حرف f، تتيح لك وضع القيم داخل النص بين {} وتنسيقها بمواصفة بعد نقطتين رأسيتين:
revenue = 146825.4412\norders = 642\nshare = 0.4493\n\nprint(f\"Q4 2025 revenue: ${revenue:,.2f}\") # thousands separator, 2 decimals\nprint(f\"Orders: {orders}, average {revenue / orders:.2f} per order\")\nprint(f\"Share of the year: {share:.1%}\") # percent with 1 decimal\nprint(f\"|{'Egypt':<12}|{orders:>6}|\") # left- and right-aligned columnsالمواصفات التي ستستخدمها أكثر من غيرها: ,.2f للمبالغ المالية، و.1% للنِّسَب (تضرب في 100 نيابةً عنك)، و,.0f للأعداد الصحيحة الكبيرة، و</> مع عرض محدّد لمحاذاة النص. وأي تعبير يعمل داخل الأقواس المعقوفة، بما في ذلك عمليات حسابية مثل revenue / orders.
حين لا تستطيع Python المتابعة، تُطلق استثناءً (exception) وتطبع traceback (تتبّع الخطأ). المبتدئون يقرؤونه من الأعلى فيتوهون. اقرأه من الأسفل:
\nTraceback (most recent call last):\n File "report.py", line 9, in <module>\n total = parse_money(row["Total"])\n ~~~^^^^^^^^^\nKeyError: 'Total'السطر الأخير هو نوع الخطأ ورسالته: طُلب من قاموس المفتاح 'Total' وهو غير موجود فيه. وفوقه بسطر الكود الذي فشل، مع علامات تحت التعبير بالضبط، وفوق ذلك الملف ورقم السطر. والإصلاح هنا هو الاسم الحقيقي للعمود، 'total'.
الأخطاء التي ستقابلها أكثر من غيرها، وما تعنيه في أغلب الأحيان:
\n| الخطأ | \nالسبب المعتاد | \n
|---|---|
NameError | \nخطأ كتابي في اسم متغيّر، أو استخدامه قبل إسناد قيمة له | \n
KeyError | \nمفتاح قاموس أو عمود DataFrame غير موجود (افحص الكتابة وحالة الأحرف) | \n
TypeError | \nخلط بين الأنواع، مثل نص زائد رقم، أو استدعاء دالة بوسائط خاطئة | \n
ValueError | \nالنوع صحيح لكن المحتوى ليس كذلك، مثل float("$65.00") | \n
IndexError | \nموقع في القائمة بعد نهايتها | \n
AttributeError | \nاستدعاء method لا تملكها القيمة، وكثيرًا ما يحدث مع None | \n
بعض حالات الفشل جزء من البيانات، لا أخطاء في الكود. مجموع فوضوي مثل "N/A" لن يصبح رقمًا أبدًا. تتيح لك try / except أن تقرّر ما يحدث بدلًا من ذلك:
def parse_money_or_none(text):\n try:\n return float(text.strip().replace(\"$\", \"\").replace(\",\", \"\"))\n except ValueError:\n return None\n\nprint(parse_money_or_none(\"$65.00\"), parse_money_or_none(\"N/A\"))التقط الاستثناء المحدّد الذي تتوقّعه (ValueError هنا) ولا شيء غيره. أما except: المجرّدة فستبتلع أيضًا خطأً كتابيًا في كودك أنت، وستحصل على None في كل مكان دون أي فكرة عن السبب.
بهذا تكتمل عُدّتك من Python. القسم 2 يضعها في العمل على نطاق واسع: pandas، حيث يعمل سطر واحد على كل صفوف الجدول.
\n","toc":[{"id":"sec-1","text":"تعريف دالة","level":2},{"id":"sec-2","text":"دوال التنظيف","level":2},{"id":"sec-3","text":"الـ f-strings: أرقام يستطيع الناس قراءتها","level":2},{"id":"sec-4","text":"قراءة الأخطاء دون ذعر","level":2},{"id":"sec-5","text":"التعامل مع خطأ تتوقّعه","level":3}],"takeaways":["الدالة تمنح جزءًا من المنطق اسمًا؛ المُعامِلات (parameters) هي مُدخلاتها، وreturn تعيد مُخرجها.","الدالة التي تطبع بدلًا من أن تُعيد تعطيك None، فلا يمكن استخدام نتيجتها في حسابات لاحقة.","الـ f-strings تنسّق القيم داخل النص: f"{revenue:,.2f}" تعطي 1,234.50، وf"{share:.1%}" تعطي 12.5%.","اقرأ الـ traceback من الأسفل - السطر الأخير يسمّي نوع الخطأ ورسالته، والأسطر التي فوقه تبيّن أين حدث.","استخدم try / except للتعامل مع خطأ تتوقّعه، مثل نص لا يمكن أن يصبح رقمًا؛ ولا تستخدمها أبدًا لإخفاء أخطاء لا تفهمها."],"further":[{"title":"Defining Functions","url":"https://docs.python.org/3/tutorial/controlflow.html#defining-functions"},{"title":"Formatted String Literals (f-strings)","url":"https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals"},{"title":"Errors and Exceptions","url":"https://docs.python.org/3/tutorial/errors.html"},{"title":"Format Specification Mini-Language","url":"https://docs.python.org/3/library/string.html#format-specification-mini-language"}],"quiz":[{"q":"ما قيمة result بعد تشغيل هذا الكود؟
def add_tax(amount):\n print(amount * 1.2)\n\nresult = add_tax(100)120.0","why":"الدالة تعرض 120.0، لكن العرض ليس إعادة. بدون return لا يعود إلى المستدعي شيء."},{"text":"None","why":"صحيح. الدالة التي ليس فيها return تعيد None، أيًّا كان ما طبعته في طريقها."},{"text":"النص "120.0"","why":"الدالة print تكتب النص في المخرجات، ولا تعيده إلى المستدعي."}],"answer":1},{"q":"أيّ f-string تطبع Revenue: $146,825.44 حين تكون revenue = 146825.4412؟
f"Revenue: ${revenue:.2f}"","why":"هذه تعطي $146825.44 بلا فاصل للآلاف. الفاصلة في مواصفة التنسيق هي التي تضيفه."},{"text":"f"Revenue: ${revenue:,}"","why":"الفاصلة تضيف فواصل الآلاف، لكن لا توجد دقة محدّدة، فتحصل على كل المنازل العشرية للعدد."},{"text":"f"Revenue: ${revenue:,.2f}"","why":"صحيح. , تضيف فواصل الآلاف و.2f تثبّت منزلتين عشريتين، فتقرّب القيمة عند العرض."},{"text":"f"Revenue: {round(revenue)}"","why":"هذه تُسقط السنتات وعلامة الدولار تمامًا."}],"answer":2},{"q":"السطر الأخير من الـ traceback يقول:
\nKeyError: 'Total'ما السبب الأرجح؟
\n","options":[{"text":"الكود يطلب من قاموس (أو DataFrame) مفتاحًا اسمه'Total' غير موجود؛ والمفتاح الحقيقي غالبًا 'total'.","why":"صحيح. الخطأ KeyError يسمّي دائمًا المفتاح المفقود. والمفاتيح حسّاسة لحالة الأحرف، فقارن الكتابة بالمفاتيح الفعلية."},{"text":"قيمة total لا يمكن تحويلها إلى رقم.","why":"فشل التحويل يسبّب ValueError، لا KeyError."},{"text":"المتغيّر Total لم يُعرَّف أبدًا.","why":"المتغيّر غير المعرَّف يسبّب NameError برسالة تقول إن الاسم غير معرَّف. علامات التنصيص في الرسالة تشير إلى بحث عن مفتاح."}],"answer":0},{"q":"متى يكون تغليف الكود بـ try / except فكرة جيدة؟
ValueError عند تحويل نص كتبه مستخدم، وإعادة None للقيم التي ليست أرقامًا."},{"text":"كلما رأيت SyntaxError.","why":"أخطاء الصياغة تحدث قبل تشغيل الكود، فلا تستطيع try التقاطها؛ الحل أن تصلح الكود."}],"answer":1}],"exercise":{"kind":"python","files":[],"starter":"def parse_money(text):\n \"\"\"' $1,234.50' -> 1234.5\"\"\"\n pass\n\n\ndef line_revenue(quantity, unit_price, discount=0.0):\n \"\"\"quantity x unit_price x (1 - discount), rounded to 2 decimals\"\"\"\n pass\n\n\ndef format_money(amount):\n \"\"\"1234.5 -> '$1,234.50'\"\"\"\n pass\n\n\nprint(parse_money(\" $1,234.50\"), line_revenue(2, 129.0, 0.15), format_money(1234.5))\n","solution":"def parse_money(text):\n \"\"\"' $1,234.50' -> 1234.5\"\"\"\n return float(text.strip().replace(\"$\", \"\").replace(\",\", \"\"))\n\n\ndef line_revenue(quantity, unit_price, discount=0.0):\n \"\"\"quantity x unit_price x (1 - discount), rounded to 2 decimals\"\"\"\n return round(quantity * unit_price * (1 - discount), 2)\n\n\ndef format_money(amount):\n \"\"\"1234.5 -> '$1,234.50'\"\"\"\n return f\"${amount:,.2f}\"\n\n\nprint(parse_money(\" $1,234.50\"), line_revenue(2, 129.0, 0.15), format_money(1234.5))\n","checks":[{"id":"parse-simple","test":"parse_money('18.00') == 18.0 and parse_money(' $129.00') == 129.0"},{"id":"parse-thousands","test":"parse_money('$1,234.50') == 1234.5"},{"id":"revenue","test":"line_revenue(2, 129.0, 0.15) == 219.3 and line_revenue(3, 24.0, 0.25) == 54.0"},{"id":"revenue-default","test":"line_revenue(1, 39.0) == 39.0"},{"id":"format","test":"format_money(1234.5) == '$1,234.50' and format_money(18) == '$18.00'"}],"title":"ثلاث دوال مساعدة للتقرير","prompt":"أكمل ثلاث دوال. parse_money(text) تعيد عددًا عشريًا من نصوص مثل " $1,234.50" أو "$129.00" أو "18.00". وline_revenue(quantity, unit_price, discount=0.0) تعيد الكمية × سعر الوحدة × (1 − الخصم)، مقرّبًا إلى منزلتين عشريتين؛ والخصم الافتراضي 0. وformat_money(amount) تعيد نصًا مثل "$1,234.50": علامة دولار، وفواصل للآلاف، ومنزلتان عشريتان بالضبط. يجب أن تُعيد كل دالة نتيجتها بـ return، لا أن تطبعها.
pass بجملة return في كل دالة.","في parse_money، سلسِل .strip() و.replace("$", "") و.replace(",", "")، ثم غلّف كل ذلك بـ float().","في format_money، تقوم f-string بالمواصفة ,.2f بكل التنسيق: f"${amount:,.2f}"."],"explanation":"كل دالة تقوم بمهمة واحدة وتعيد نتيجتها، لذا يمكن تركيبها معًا: format_money(line_revenue(2, parse_money("$129.00"), 0.15)) تعطي "$219.30". والقيمة الافتراضية discount=0.0 تعني أن المستدعي يستطيع تركها في البنود التي تُباع بالسعر الكامل. في format_money، علامة $ الأولى نص حرفي، والأقواس المعقوفة تحمل القيمة مع المواصفة ,.2f: فواصل آلاف ومنزلتان عشريتان ثابتتان. ستعيد استخدام هذا المنطق نفسه على أعمدة pandas كاملة في القسم 3.
parse_money تتعامل مع "18.00" و" $129.00"","parse-thousands":"parse_money تتعامل مع فواصل الآلاف: "$1,234.50" تصبح 1234.5","revenue":"line_revenue تطبّق الخصم وتقرّب إلى منزلتين عشريتين","revenue-default":"line_revenue تعمل دون تمرير وسيط الخصم","format":"format_money(1234.5) تعيد "$1,234.50""}},"words":606,"readMinutes":4}