مختبر المخزون

مختبر المخزون — Inventory Lab

في هذا المختبر ستبني نظام مخزون صغيراً من البداية. على عكس درس الـ Walkthrough، هنا ستقرر أنت شكل البيانات وكيفية تنظيم الدوال — ستجد توجيهاً أقل وحرية أكبر.

نظام المخزون مثال واقعي لأنه يجمع بين أنواع بيانات متعددة: كل منتج له اسم ورمز SKU وسعر وكمية. هذه المعلومات تعيش معاً — لهذا ستستخدم قائمة من القواميس (list of dicts). كل قاموس يمثل منتجاً، والقائمة تجمع كل المنتجات. هذا الشكل شائع جداً في Python — نتائج قواعد البيانات، استجابات API، وملفات JSON تصل عادةً بهذا الشكل.

شكل البيانات

قبل أن تبدأ بالكتابة، فكّر: لماذا قائمة من القواميس وليس قاموس من القواميس؟

قائمة من القواميس [{...}, {...}]:

ترتيب المنتجات محفوظ (مفيد للعرض)
يمكن وجود منتجات بنفس الاسم (رغم أنه غير مرغوب)
الحذف والإضافة مباشران

قاموس من القواميس {"SKU": {...}}:

البحث بالـ SKU أسرع O(1) مقابل O(n)
لا تكرار للمفاتيح مضمون
لكن الترتيب بحاجة sorted()

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

البداية: تهيئة المخزون

main.go

# تهيئة المخزون — Initialize inventory
inventory = [
    {"name": "قلم", "sku": "PEN-01", "price": 3.5, "qty": 10},
    {"name": "كتاب", "sku": "BOOK-01", "price": 40.0, "qty": 5},
    {"name": "مسطرة", "sku": "RUL-01", "price": 8.0, "qty": 20},
]

# اطبع المخزون — Print inventory
print("المنتجات:")
for item in inventory:
    print(f"  {item['name']} (SKU: {item['sku']}) - {item['qty']} قطعة @ {item['price']} ريال")

print(f"\nإجمالي أنواع المنتجات: {len(inventory)}")

Output:

التحدي 1 — إضافة منتج

تحدي — Challenge

# أضف دالة add_item وتحقق من عملها
# Add add_item function and verify it works
inventory = [
    {"name": "قلم", "sku": "PEN-01", "price": 3.5, "qty": 10},
    {"name": "كتاب", "sku": "BOOK-01", "price": 40.0, "qty": 5},
    {"name": "مسطرة", "sku": "RUL-01", "price": 8.0, "qty": 20},
]

def add_item(inv, name, sku, price, qty):
    """يضيف منتجاً جديداً للمخزون — Adds a new item to inventory"""
    # أنشئ قاموس المنتج وأضفه للقائمة — Create item dict and append to list
    pass  # اكتب هنا — Write here

print("عدد المنتجات قبل:", len(inventory))
add_item(inventory, "محفظة", "WAL-01", 55.0, 8)
print("عدد المنتجات بعد:", len(inventory))

# تحقق أن المحفظة موجودة — Verify wallet exists
exists = any(item["name"] == "محفظة" for item in inventory)
print("محفظة موجودة:", exists)

التحدي 2 — حذف منتج بالاسم

تحدي — Challenge

# اكتب دالة remove_by_name — Write remove_by_name function
inventory = [
    {"name": "قلم", "sku": "PEN-01", "price": 3.5, "qty": 10},
    {"name": "كتاب", "sku": "BOOK-01", "price": 40.0, "qty": 5},
    {"name": "مسطرة", "sku": "RUL-01", "price": 8.0, "qty": 20},
]

def remove_by_name(inv, name):
    """يحذف المنتج بالاسم — Removes item by name
    يرجع True إذا حُذف، False إذا لم يُوجد — Returns True if removed
    """
    original_len = len(inv)
    # استخدم list comprehension لإبقاء ما ليس اسمه name
    # Use list comprehension to keep items that don't match name
    filtered = []  # استبدل بـ comprehension — Replace with comprehension
    inv[:] = filtered   # تعديل الأصل في مكانه — Modify original in place
    return len(inv) < original_len

print("قبل الحذف:", len(inventory))
remove_by_name(inventory, "مسطرة")
print("بعد الحذف:", len(inventory))

still_there = any(item["name"] == "مسطرة" for item in inventory)
print("مسطرة موجودة:", still_there)

التحدي 3 — تحديث الكمية

تحدي — Challenge

# اكتب دالة update_qty — Write update_qty function
inventory = [
    {"name": "قلم", "sku": "PEN-01", "price": 3.5, "qty": 10},
    {"name": "كتاب", "sku": "BOOK-01", "price": 40.0, "qty": 5},
    {"name": "مسطرة", "sku": "RUL-01", "price": 8.0, "qty": 20},
]

def update_qty(inv, name, new_qty):
    """يحدّث كمية منتج موجود — Updates quantity of existing item
    يرجع True إذا نجح، False إذا لم يوجد المنتج — Returns True if successful
    """
    # ابحث عن المنتج باستخدام next() مع default=None
    # Find item using next() with default=None
    item = next((i for i in inv if i["name"] == name), None)
    if item is None:
        return False
    # عدّل الكمية مباشرةً — Modify qty directly
    # اكتب هنا — Write here
    return True

pen = next(i for i in inventory if i["name"] == "قلم")
print("كمية القلم قبل:", pen["qty"])

update_qty(inventory, "قلم", 25)
pen = next(i for i in inventory if i["name"] == "قلم")
print("كمية القلم بعد:", pen["qty"])

result = update_qty(inventory, "طابعة", 5)
print("تحديث غير موجود:", result)

التحدي 4 — قيمة المخزون الكلية ومنتجات نقص المخزون

تحدي — Challenge

# اكتب الدالتين وتحقق من الناتج — Write both functions and verify output
inventory = [
    {"name": "قلم", "sku": "PEN-01", "price": 3.5, "qty": 10},
    {"name": "كتاب", "sku": "BOOK-01", "price": 40.0, "qty": 4},
    {"name": "مسطرة", "sku": "RUL-01", "price": 8.0, "qty": 20},
    {"name": "محفظة", "sku": "WAL-01", "price": 55.0, "qty": 3},
]

def total_value(inv):
    """يحسب القيمة الكلية للمخزون — Computes total inventory value"""
    # استخدم sum() مع generator expression
    # Use sum() with generator expression: price * qty for each item
    return 0.0  # استبدل — Replace

def low_stock(inv, threshold=5):
    """يرجع قائمة المنتجات ذات الكمية القليلة — Returns low stock items"""
    # استخدم list comprehension للفلترة
    # Use list comprehension to filter items where qty < threshold
    return []  # استبدل — Replace

value = total_value(inventory)
print(f"قيمة المخزون: {value} ريال")

low = low_stock(inventory)
print(f"منتجات نقص المخزون (< 5):")
for item in low:
    print(f"  - {item['name']}: {item['qty']} قطعة")

البرنامج الكامل

main.go

# نظام المخزون الكامل — Complete inventory system

def add_item(inv, name, sku, price, qty):
    """يضيف منتجاً — Add item"""
    inv.append({"name": name, "sku": sku, "price": price, "qty": qty})

def remove_by_name(inv, name):
    """يحذف بالاسم — Remove by name"""
    original = len(inv)
    inv[:] = [item for item in inv if item["name"] != name]
    return len(inv) < original

def update_qty(inv, name, new_qty):
    """يحدّث الكمية — Update quantity"""
    item = next((i for i in inv if i["name"] == name), None)
    if item is None:
        return False
    item["qty"] = new_qty
    return True

def total_value(inv):
    """القيمة الكلية — Total value"""
    return sum(item["price"] * item["qty"] for item in inv)

def low_stock(inv, threshold=5):
    """نقص المخزون — Low stock items"""
    return [item for item in inv if item["qty"] < threshold]

def print_inventory(inv):
    """اطبع المخزون — Print inventory"""
    print("=== المخزون الحالي ===")
    for item in sorted(inv, key=lambda x: x["name"]):
        status = " [تنبيه: نقص]" if item["qty"] < 5 else ""
        print(f"  {item['name']:10} | {item['qty']:3} قطعة | {item['price']:.1f} ريال{status}")
    print(f"  القيمة الكلية: {total_value(inv):.1f} ريال")

# تشغيل — Run
inventory = []
add_item(inventory, "قلم", "PEN-01", 3.5, 10)
add_item(inventory, "كتاب", "BOOK-01", 40.0, 4)
add_item(inventory, "مسطرة", "RUL-01", 8.0, 20)
add_item(inventory, "محفظة", "WAL-01", 55.0, 3)

print_inventory(inventory)

print("\n--- عمليات ---")
update_qty(inventory, "كتاب", 12)
print("تحديث كمية الكتاب إلى 12: نجح")

remove_by_name(inventory, "مسطرة")
print("حذف المسطرة: نجح")

print()
print_inventory(inventory)

Output:

ما تعلمته في هذا المختبر

قائمة من القواميس هي الشكل الأنسب عندما:

كل عنصر له عدة حقول مترابطة (اسم + سعر + كمية)
البيانات تأتي من API أو قاعدة بيانات (غالباً بهذا الشكل)
تريد الترتيب والتصفية والتحويل بـ sorted() وList Comprehensions

الفرق المهم عن Go: في Python، القاموس mutable — إذا كان لديك مرجع (reference) لقاموس داخل قائمة، تعديله يُعدّل الأصل مباشرةً. هذا لماذا update_qty تعمل بتعديل item["qty"] مباشرةً بعد إيجاد item بـ next().

inv[:] = [...] في دالة remove_by_name تعدّل القائمة في مكانها بدلاً من إنشاء قائمة جديدة. هذا مهم إذا كان كود آخر يحمل مرجعاً لنفس القائمة.

معيار القبول

الحل الجيد:

كل دالة تفعل شيئاً واحداً فقط
total_value تستخدم sum() مع generator expression، لا حلقة يدوية
low_stock تستخدم list comprehension، لا append داخل for
update_qty تعثر على العنصر بـ next() وتعدّله مباشرةً
لا منطق عرض داخل دوال الحساب، ولا حساب داخل دوال العرض

خلاصة

هذا المختبر جمع كل ما تعلمته في الفصل: قوائم تخزن تسلسلاً، قواميس تخزن بيانات منظّمة، comprehensions تبني وتصفّي، وnext() مع generator expression يجد عنصراً بشرط بكفاءة. هذه الأنماط تظهر في كل مشروع Python حقيقي — من معالجة ملفات JSON إلى استجابات قواعد البيانات إلى إدارة الحالة في تطبيقات الويب.