عرض مصدر Python/Connection

<noinclude>{{DISPLAYTITLE:كائنات <code>Connection‎</code> في بايثون}}</noinclude>
تقدّم كائنات الاتصال <code>Connection</code> عددًا من الخصائص والتوابع التي تساعد المستخدم في التعامل مع قواعد بيانات SQLite، كالاتصال بقاعدة البيانات وتحميل الملحقات وإنشاء النسخ الاحتياطية وغيرها. تنشأ كائنات الاتصال كنتيجة لاستدعاء الدالة <code>[[Python/sqlite3/connect|sqlite3.connect()‎]]</code>.

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

===الخاصية <code>isolation_level</code>===
يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة <code>None</code> لنمط الحفظ التلقائي <code>autocommit</code> أو إحدى القيم <code>"DEFERRED"</code> أو <code>"IMMEDIATE"</code> أو <code>"EXCLUSIVE"</code>. راجع قسم التحكم بالإجراءات للمزيد من المعلومات.
===الخاصية <code>in_transaction</code>===
تأخذ الخاصية القيمة <code>True</code> إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة <code>False</code> فيما عدا ذلك. هذه الخاصية للقراءة فقط.
===الخاصية <code>row_factory</code>===
يمكن تبديل هذه الخاصية إلى كائن قابل للاستدعاء يستقبل كائن المؤشّر والصفّ row الأصلي على هيئة [[Python/tuples|صفّ <code>tuple</code>]] وسيعيد النتيجة الحقيقية للصف row. يمكن بهذه الطريقة تطبيق طرق متقدّمة لإعادة النتائج، مثل إعادة كائن بمقدوره الوصول إلى الأعمدة عن طريق أسمائها، مثال:<syntaxhighlight lang="python3">
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"])
</syntaxhighlight>إن لم يكن [[Python/type|الصف <code>tuple</code>]] كافيًا، وكنت ترغب في الوصول إلى الأعمدة بواسطة أسمائها، فيمكنك تعيين النوع <code>sqlite3.Row</code> إلى هذه الخاصية. يتيح [[Python/sqlite3#.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B5.D9.81 Row|النوع <code>Row</code>]] الوصول إلى الأعمدة عن طريق أرقامها وعن طريق أسمائها دون تحسّس حالة الأحرف ودون استهلاك الكثير من الذاكرة. وقد يكون هذا النوع خيارًا أفضل من استخدام [[Python/dict|القواميس]] للوصول إلى الأعمدة، أو أفضل حتى من استخدام <code>db_row</code>.
===الخاصية <code>text_factory</code>===
يمكن عن طريق هذه الخاصية التحكم في طبيعة الكائنات المعادة لأنواع البيانات النصية <code>TEXT</code>. القيمة الافتراضية لهذه الخاصية هي <code>str</code> وتعيد وحدة <code>sqlite3</code> كائنات Unicode للأعمدة النصية. يمكن تعيين القيمة <code>bytes</code> لهذه الخاصية إن كان المطلوب إعادة سلاسل بايتات نصية <code>bytestrings</code>.

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

يبين المثال التالي طريقة عمل الخاصية:<syntaxhighlight lang="python3">
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"
</syntaxhighlight>
===الخاصية <code>total_changes</code>===
تعيد الخاصية العدد الإجمالي للصفوف الخاضعة للتعديلات، أو المدرجة أو المحذوفة من قاعدة البيانات منذ إجراء الاتصال مع قاعدة البيانات.

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

===التابع <code rel="mw:WikiLink" href="./Python/Connectin/cursor" title="Python/Connectin/cursor">[[Python/Connection/cursor|cursor()‎]]</code>===
يعيد التابع نسخة من صنف <code>Cursor</code> أو أحد أصنافه الفرعية.
===التابع [[Python/Connection/commit|<code>commit()‎</code>]]===
يحفظ التابع الإجراء الحالي.
===التابع [[Python/Connection/rollback|<code>rollback()‎</code>]]===
يلغي التابع جميع التعديلات التي أجريت على قاعدة البيانات بعد آخر استدعاء للتابع [[Python/Connection/commit|<code>commit()‎</code>]].
===التابع [[Python/Connection/close|<code>close()‎</code>]]===
يغلق التابع الاتصال بقاعدة البيانات.
===التابع [[Python/Connection/execute|<code>execute()‎</code>]]===
يستدعي التابع [[Python/Cursor/execute|<code>execute()‎</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
===التابع [[Python/Connection/excutemany|<code>excutemany()‎</code>]]===
يستدعي التابع [[Python/Cursor/executemany|<code>executemany()‎</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
===التابع [[Python/Connection/executescript|<code>executescript()‎</code>]]===
يستدعي التابع [[Python/Cursor/executescript|<code>executescript()‎</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
===التابع [[Python/Connection/create function|<code>create_function()‎</code>]]===
ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل [[SQL]].
===التابع [[Python/Connection/create aggregate|<code>create_aggregate()‎</code>]]===
ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم.
===التابع [[Python/Connection/create collation|<code>create_collation()‎</code>]]===
ينشئ التابع مقارنة collation تحمل الاسم المعطى مع الكائن القابل للاستدعاء المعطى.
===التابع [[Python/Connection/interrupt|<code>interrupt()‎</code>]]===
يمكن استدعاء هذا التابع من خيط آخر لتجاهل أي استعلامات قد تكون قيد التنفيذ عبر الاتصال الحالي.
===التابع [[Python/Connection/set authorizer|<code>set_authorizer()‎</code>]]===
يسجّل هذا التابع كائن استدعاء خلفيٍّ، وينفّذ هذا الكائن في كل محاولة للوصول إلى عمود في جدول ضمن قاعدة البيانات.
===التابع [[Python/Connection/set progress handler|<code>set_progress_handler()‎</code>]]===
يسجّل هذا التابع استدعاءً خلفيًا يجري تنفيذه لكل <code>n</code> من تعليمات SQLite في الجهاز الافتراضي virtual machine.
===التابع [[Python/Connection/set trace callback|<code>set_trace_callback()‎</code>]]===
يسجل التابع كائن استدعاء خلفي للأخطاء trace_callback يجري استدعاؤه لكل جملة [[SQL]] تنفّذ بواسطة SQLite.
===التابع [[Python/Connection/enable load extension|<code>enable_load_extension()‎</code>]]===
يحدّد هذا التابع ما إذا كان بإمكان محرّك SQLite من تحميل الملحقات من المكتبات المشتركة.
===التابع [[Python/Connection/load extension|<code>load_extension()‎</code>]]===
يحمل هذا التابع إحدى ملحقات SQlite من المكتبة المشتركة.
===التابع [[Python/Connection/iterdump|<code>iterdump()‎</code>]]===
يعيد التابع مكرِّرًا iterator يمكن استخدامه لعرض dump قاعدة البيانات بصيغة [[SQL]] النصية.
===التابع [[Python/Connection/backup|<code>backup()‎</code>]]===
ينشئ هذا التابع نسخة احتياطية من قاعدة بيانات SQLite.

'''ملاحظة:''' هذه الخاصية جديدة في الإصدار 3.2.

== انظر أيضًا ==
* كائنات Cursor في بايثون.
* كائنات Row في بايثون.

== مصادر ==
* [https://docs.python.org/3/library/sqlite3.html#connection-objects قسم كائنات Connect في صفحة DB-API 2.0 interface for SQLite databases في توثيق بايثون الرسمي.]