كائنات `Connection‎` في بايثون

تقدّم كائنات الاتصال Connection عددًا من الخصائص والتوابع التي تساعد المستخدم في التعامل مع قواعد بيانات SQLite، كالاتصال بقاعدة البيانات وتحميل الملحقات وإنشاء النسخ الاحتياطية وغيرها. تنشأ كائنات الاتصال كنتيجة لاستدعاء الدالة sqlite3.connect()‎.

خصائص كائنات الاتصال

تمتلك كائنات الاتصال بقواعد البيانات SQLite الخصائص التالية:

الخاصية `isolation_level`

يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة None لنمط الحفظ التلقائي autocommit أو إحدى القيم "DEFERRED" أو "IMMEDIATE" أو "EXCLUSIVE". راجع قسم التحكم بالإجراءات للمزيد من المعلومات.

الخاصية `in_transaction`

تأخذ الخاصية القيمة True إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة False فيما عدا ذلك. هذه الخاصية للقراءة فقط.

الخاصية `row_factory`

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

import sqlite3

def dict_factory(cursor, row):
    d = {}
    for idx, col in enumerate(cursor.description):
        d[col[0]] = row[idx]
    return d

con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])

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

الخاصية `text_factory`

يمكن عن طريق هذه الخاصية التحكم في طبيعة الكائنات المعادة لأنواع البيانات النصية TEXT. القيمة الافتراضية لهذه الخاصية هي str وتعيد وحدة sqlite3 كائنات Unicode للأعمدة النصية. يمكن تعيين القيمة bytes لهذه الخاصية إن كان المطلوب إعادة سلاسل بايتات نصية bytestrings.

يمكن كذلك تعيين أي قيمة قابلة للاستدعاء وتستقبل معامل واحدًا من نوع bytestring وتعيد الكائن الناتج من الاستدعاء.

يبين المثال التالي طريقة عمل الخاصية:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()

AUSTRIA = "\xd6sterreich"

# تكون الصفوف المعادة بترميز يونيكود افتراضيًا
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA

# ولكن يمكن جعل وحدة sqlite3 تعيد سلاسل بايتات نصية دائمًا...

con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# سترمّز سلاسل البايتات النصية بترميز UTF-8 

assert row[0] == AUSTRIA.encode("utf-8")

# يمكننا كذلك تطبيق text_factory مخصّص
# هنا ستُلحق السلسلة "foo" بجميع السلاسل النصية
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("select ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"