2.9. القواميس

‏القاموس هو تعيين من المفاتيح إلى القيم. يُبحث عن كل مفتاح مباشرةً؛ ويتذكر القاموس آخر قيمة ارتبطت بذلك المفتاح.

2.9.1. إنشاء القواميس

استخدم الأقواس المعقوفة مع أزواج key: value، أو منشئ dict:

empty   = {}
person  = {"name": "OpenMV", "id": 42}
counts  = dict(a=1, b=2, c=3)            # keyword form
pairs   = dict([("x", 1), ("y", 2)])     # from a list of pairs

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

config = {
    "name":  "OpenMV",
    "id":    42,
    "width": 320,
    "tags":  ["red", "round"],
}

كل مفتاح في القاموس يُعيّن إلى قيمة واحدة بالضبط.

2.9.2. الوصول والعضوية

تُسترجع القيمة الخاصة بمفتاح عبر الفهرسة باستخدام []. ويثير المفتاح المفقود الاستثناء KeyError:

>>> person = {"name": "OpenMV", "id": 42}
>>> person["name"]
'OpenMV'
>>> person["missing"]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'missing'

للبحث المتسامح، استخدم dict.get(). فهو يُعيد None للمفتاح المفقود، أو قيمة تمررها كوسيط ثانٍ:

>>> person.get("name")
'OpenMV'
>>> person.get("missing")            # returns None
>>> person.get("missing", "n/a")
'n/a'

تختبر الكلمة المفتاحية in عضوية المفتاح -- وليس القيمة:

>>> "name" in person
True
>>> "OpenMV" in person
False

2.9.3. الإضافة والتحديث والإزالة

الإسناد إلى d[key] يضيف المُدخل إذا كان المفتاح جديدًا، ويستبدله إذا كان موجودًا بالفعل:

>>> person["seen"] = 1
>>> person["seen"] = 2               # overwrites
>>> person
{'name': 'OpenMV', 'id': 42, 'seen': 2}

للإزالة عدة صور:

• ‏del d[key] -- يزيل مُدخلًا؛ ويثير KeyError إذا كان المفتاح مفقودًا.

• ‏dict.pop() -- يزيل القيمة ويُعيدها؛ وتتيح لك قيمة افتراضية اختيارية تجنّب الاستثناء.

• ‏dict.clear() -- يزيل كل مُدخل.

‏dict.update() يدمج قاموسًا آخر (أو قائمة من أزواج (key, value)) في القاموس المستقبِل، مستبدلًا أي مفاتيح متطابقة:

>>> person.update({"id": 100, "owner": "alice"})
>>> person
{'name': 'OpenMV', 'id': 100, 'seen': 2, 'owner': 'alice'}

2.9.4. التكرار

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

for k in person:
    print(k)

ثلاث طرق عرض تتيح وصولًا صريحًا:

• ‏dict.keys() -- المفاتيح (مثل التكرار على القاموس).

• ‏dict.values() -- القيم.

• ‏dict.items() -- صفوف (key, value)، مثالية للتفكيك داخل حلقة.

for key, value in person.items():
    print(key, "=", value)

2.9.5. ما الذي يصلح مفتاحًا

يجب أن تكون مفاتيح القاموس قابلة للتجزئة (hashable) -- أي لا يمكن أن تتغير قيمتها طوال عمرها. الأنواع الشائعة القابلة للتجزئة هي:

• ‏int و float و bool

• ‏str و bytes

• ‏tuple (عندما يكون كل عنصر بداخله قابلًا للتجزئة بذاته)

• ‏None

الأنواع القابلة للتغيير مثل list و dict و bytearray لا يمكن أن تكون مفاتيح؛ واستخدام أحدها يثير TypeError. والصفوف من القيم غير القابلة للتغيير هي الطريقة القياسية لفهرسة القاموس بمعرّف مركّب مثل إحداثية في شبكة ثنائية الأبعاد:

>>> grid = {}
>>> grid[(0, 0)] = "start"
>>> grid[(5, 7)] = "end"

2.9.6. الطول

‏len() يُعيد عدد المُدخلات:

>>> len(person)
4