Python/namedtuple

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

البنية العامة

تستخدم الدالة namedtuple()‎ لإنشاء الصفوف المسمّاة وصيغتها العامّة هي:

namedtuple(typename, field_names, *, verbose=False, rename=False, module=None)

تعيد هذه الدالة البانية صنفًا فرعيًا من الصنف tuple يحمل الاسم typename. يُستخدم الصنف الفرعي الجديد في إنشاء كائنات شبيهة بالصفوف تمتلك حقولًا يمكن الوصول إليها عن طريق البحث في الخاصيات إضافة إلى إمكانية فهرسة هذه الحقول والمرور عليها. تمتلك نسخ الكائن الفرعي كذلك سلسلة توثيق نصية (docstring) مفيدة (مع typename و field_names) وتابع ‎__repr__()‎ وظيفته سرد قائمة بمحتويات الصف على هيئة name=value.

field_names هي تسلسل من السلاسل النصية مثل ['x', 'y']، أو يمكن أن تكون سلسلة نصية مفردة تكون فيها أسماء الحقول مفصولة عن بعضها البعض بمسافة بيضاء و/أو فاصلة، مثل: 'x y' أو 'x, y'.

يمكن استخدام أي معرّف صالح في بايثون كاسمٍ للحقل باستثناء الأسماء التي تبدأ بالشرطة السفلية. تشمل المعرّفات الصالحة الحروف، والأرقام والشرطات السفلية، ولا تبدأ بالأرقام أو الشرطات السفلية ولا يمكن أن تكون إحدى الكلمات المفتاحية مثل class أو for أو return أو global أو pass أو raise.

إن أخذ الوسيط rename القيمة True فإنّ أسماء الحقول غير الصالحة تبدّل بصورة تلقائية إلى أسماء موقعية. فمثلًا تحوّل ['abc', 'def', 'ghi', 'abc'] إلى ‎['abc', '_1', 'ghi', '_3']‎ إذ تحذف الكلمة المفتاحية def واسم الحقل المكرر abc.

إن أخذ الوسيط verbose القيمة True فإنّ تعريف الصنف يطبع بعد بنائه. هذا الوسيط مهمل الآن، ومن الأسهل طباعة الخاصية ‎_source بدلًا من ذلك.

إن تم تعريف الوسيط module فإنّ الخاصية ‎__module__‎ التابعة للصف المسمى تأخذ هذه القيمة.

لا تمتلك الصفوف المسمّاة قاموسًا لكل نسخة منها؛ ولهذا تستهلك الصفوف المسمّاة نفس مقدار الذاكرة الذي تستهلكه الصفوف العادية.

أمثلة

>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # إنشاء نسخة باستخدام وسائط موقعية أو مفتاحية
>>> p[0] + p[1]             # يمكن فهرستها مثل الصفوف العادية
33
>>> x, y = p                # فك التحزيم مثل الصفوف العادية
>>> x, y
(11, 22)
>>> p.x + p.y               # يمكن الوصول إلى الحقول عن طريق اسمائها
33
>>> p                       # تمثيل سهل القراءة
Point(x=11, y=22)

الصفوف المسمّاة مفيدة للغاية عند تعيين أسماء الحقول إلى صفوف معادة من وحدة sqlite3 أو csv (القيم المفصولة بفاصلة):

EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')
import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
    print(emp.name, emp.title)
import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
    print(emp.name, emp.title)

التغييرات في الإصدار 3.1

• إضافة الوسيط rename.

التغييرات في الإصدار 3.6

• أصبح الوسيطان verbose و rename وسيطين مفتاحيين فقط.

• إضافة الوسيط module.

مصادر

قسم namedtuples في صفحة Containers Datatypes في توثيق بايثون الرسمي.