كائنات 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"
الخاصية total_changes
تعيد الخاصية العدد الإجمالي للصفوف الخاضعة للتعديلات، أو المدرجة أو المحذوفة من قاعدة البيانات منذ إجراء الاتصال مع قاعدة البيانات.
توابع كائنات الاتصال
تقدّم كائنات الاتصال التوابع التالية:
التابع cursor()
يعيد التابع نسخة من صنف Cursor أو أحد أصنافه الفرعية.
التابع commit()
يحفظ التابع الإجراء الحالي.
التابع rollback()
يلغي التابع جميع التعديلات التي أجريت على قاعدة البيانات بعد آخر استدعاء للتابع commit().
التابع close()
يغلق التابع الاتصال بقاعدة البيانات.
التابع execute()
يستدعي التابع execute() في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع excutemany()
يستدعي التابع executemany() في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع executescript()
يستدعي التابع executescript() في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع create_function()
ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل SQL.
التابع create_aggregate()
ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم.
التابع create_collation()
ينشئ التابع مقارنة collation تحمل الاسم المعطى مع الكائن القابل للاستدعاء المعطى.
التابع interrupt()
يمكن استدعاء هذا التابع من خيط آخر لتجاهل أي استعلامات قد تكون قيد التنفيذ عبر الاتصال الحالي.
التابع set_authorizer()
يسجّل هذا التابع كائن استدعاء خلفيٍّ، وينفّذ هذا الكائن في كل محاولة للوصول إلى عمود في جدول ضمن قاعدة البيانات.
التابع set_progress_handler()
يسجّل هذا التابع استدعاءً خلفيًا يجري تنفيذه لكل n من تعليمات SQLite في الجهاز الافتراضي virtual machine.
التابع set_trace_callback()
يسجل التابع كائن استدعاء خلفي للأخطاء trace_callback يجري استدعاؤه لكل جملة SQL تنفّذ بواسطة SQLite.
التابع enable_load_extension()
يحدّد هذا التابع ما إذا كان بإمكان محرّك SQLite من تحميل الملحقات من المكتبات المشتركة.
التابع load_extension()
يحمل هذا التابع إحدى ملحقات SQlite من المكتبة المشتركة.
التابع iterdump()
يعيد التابع مكرِّرًا iterator يمكن استخدامه لعرض dump قاعدة البيانات بصيغة SQL النصية.
التابع backup()
ينشئ هذا التابع نسخة احتياطية من قاعدة بيانات SQLite.
ملاحظة: هذه الخاصية جديدة في الإصدار 3.2.