`dbm` --- رابط‌هایی برای «پایگاه‌های داده»ی یونیکس¶

dbm یک رابط عام برای انواع پایگاه داده DBM است:

dbm.sqlite3
dbm.gnu
dbm.ndbm

اگر هیچ‌کدام از این ماژول‌ها نصب‌نشده باشند، از پیاده‌سازی کند اما ساده در ماژول dbm.dumb استفاده خواهد شد. یک رابط شخص ثالث برای Oracle Berkeley DB وجود دارد.

exception dbm.error¶: تاپلی شامل استثناهایی که هر یک از ماژول‌های پشتیبانی‌شده می‌توانند پرتاب کنند، با یک استثنای یکتا که آن نیز dbm.error نام دارد به‌عنوان اولین آیتم --- این استثنا زمانی استفاده می‌شود که dbm.error پرتاب شود.

dbm.whichdb(filename)¶

این تابع تلاش می‌کند حدس بزند که کدام‌یک از چندین ماژول ساده پایگاه داده موجود --- dbm.sqlite3، dbm.gnu، dbm.ndbm، یا dbm.dumb --- باید برای باز کردن یک پرونده مشخص استفاده شود.

یکی از مقادیر زیر را برمی‌گرداند:

None اگر پرونده به دلیل غیرقابل‌خواندن بودن یا وجود نداشتن نتواند باز شود
رشته خالی ('') اگر نتوان قالب پرونده را حدس زد
رشته‌ای شامل نام ماژول مورد نیاز، مانند 'dbm.ndbm' یا 'dbm.gnu'

تغییر یافته در نسخه‌ی 3.11: filename یک شیء شبه‌مسیر (path-like object) را می‌پذیرد.

dbm.open(file, flag='r', mode=0o666)¶

یک پایگاه داده را باز می‌کند و شیء پایگاه داده‌ی متناظر را برمی‌گرداند.

پارامترها:

file (path-like object) -- پرونده پایگاه داده برای باز کردن. اگر پرونده پایگاه داده از قبل وجود داشته باشد، از تابع whichdb() برای تعیین نوع آن استفاده می‌شود و ماژول مناسب به کار می‌رود؛ اگر وجود نداشته باشد، از اولین زیرماژول فهرست‌شده در بالا که قابل ایمپورت باشد استفاده می‌شود.
flag (str) --
- 'r' (پیش‌فرض): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

تغییر یافته در نسخه‌ی 3.11: file یک path-like object را می‌پذیرد.

شیء برگردانده‌شده توسط open()، از کارکرد پایه‌ی نگاشت‌های تغییرپذیر پشتیبانی می‌کند؛ کلیدها و مقدارهای متناظرشان می‌توانند ذخیره، بازیابی و حذف شوند و پیمایش، عملگر in و متدهای keys()، get()، setdefault() و clear() در دسترس هستند. متد keys() به‌جای یک شیء نما، یک فهرست برمی‌گرداند. متد setdefault() به دو آرگومان نیاز دارد.

کلید و مقادیر همیشه به‌صورت bytes ذخیره می‌شوند. این بدان معناست که وقتی از رشته‌ها استفاده می‌شود، آن‌ها پیش از ذخیره شدن به‌طور ضمنی به کدگذاری پیش‌فرض تبدیل می‌شوند.

این اشیاء همچنین از استفاده در دستور with پشتیبانی می‌کنند، که به‌طور خودکار آن‌ها را پس از اتمام کار می‌بندد.

تغییر یافته در نسخه‌ی 3.2: متدهای get() و setdefault() اکنون برای تمام بک‌اندهای (backends) dbm در دسترس هستند.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی ذاتی از پروتکل مدیریت زمینه به اشیای برگردانده‌شده از open() افزوده شد.

تغییر یافته در نسخه‌ی 3.8: حذف یک کلید از پایگاه داده‌ی فقط‌خواندنی، به‌جای KeyError، یک استثنای مخصوص ماژول پایگاه داده را پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: متدهای clear() اکنون برای تمام بک‌اندهای dbm در دسترس هستند.

مثال زیر چند نام میزبان و یک عنوان متناظر را ثبت می‌کند، و سپس محتویات پایگاه داده را چاپ می‌کند:

import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

همچنین ملاحظه نمائید

ماژول shelve: ماژول ماندگاری که داده‌های غیررشته‌ای را ذخیره می‌کند.

هر یک از زیرماژول‌ها در بخش‌های زیر شرح داده شده‌اند.

`dbm.sqlite3` --- بک‌اند SQLite برای dbm¶

اضافه شده در نسخه‌ی 3.13.

کد منبع: Lib/dbm/sqlite3.py

این ماژول از ماژول sqlite3 در کتابخانه استاندارد استفاده می‌کند تا یک بک‌اند SQLite برای ماژول dbm فراهم کند. در نتیجه، پرونده‌های ایجادشده توسط dbm.sqlite3 را می‌توان با sqlite3 یا هر مرورگر SQLite دیگری، از جمله SQLite CLI، باز کرد.

دسترس‌پذیری: not WASI.

این ماژول روی WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

dbm.sqlite3.open(filename, /, flag='r', mode=0o666)¶

باز کردن یک پایگاه داده SQLite.

پارامترها:

filename (path-like object) -- مسیر پایگاه داده‌ای که باید باز شود.
flag (str) --
- 'r' (پیش‌فرض): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode -- حالت دسترسی یونیکسی پرونده (پیش‌فرض: 0o666 در مبنای هشت)، که تنها زمانی استفاده می‌شود که پایگاه داده باید ایجاد شود.

شیء پایگاه داده‌ی برگردانده‌شده رفتاری مشابه یک mapping تغییرپذیر دارد، اما متد keys() یک فهرست برمی‌گرداند و متد setdefault() به دو آرگومان نیاز دارد. همچنین از یک مدیر زمینه‌ی «بستن» از طریق کلیدواژه with پشتیبانی می‌کند.

متد زیر نیز ارائه شده است:

sqlite3.close()¶: پایگاه داده‌ی SQLite را ببندید.

`dbm.gnu` --- مدیر پایگاه‌داده GNU¶

کد منبع: Lib/dbm/gnu.py

ماژول dbm.gnu رابطی برای کتابخانه‌ی GDBM فراهم می‌کند، مشابه ماژول dbm.ndbm، اما با قابلیت‌های اضافی مانند تحمل خرابی (crash tolerance).

توجه

قالب‌های پرونده ایجادشده توسط dbm.gnu و dbm.ndbm ناسازگار هستند و نمی‌توانند به‌جای یکدیگر استفاده شوند.

دسترس‌پذیری: not Android, not iOS, not WASI.

این ماژول در پلتفرم‌های موبایل یا پلتفرم‌های WebAssembly پشتیبانی نمی‌شود.

دسترس‌پذیری: Unix.

exception dbm.gnu.error¶: در صورت بروز خطاهای خاص dbm.gnu، مانند خطاهای I/O، پرتاب می‌شود. KeyError برای خطاهای عمومی نگاشت، مانند مشخص کردن یک کلید نادرست، پرتاب می‌شود.

dbm.gnu.open_flags¶: رشته‌ای از نویسه‌ها که پارامتر flag در open() از آن‌ها پشتیبانی می‌کند.

dbm.gnu.open(filename, flag='r', mode=0o666, /)¶

یک پایگاه داده GDBM را باز می‌کند و یک شیء gdbm را برمی‌گرداند.

پارامترها:

filename (path-like object) -- پرونده پایگاه داده‌ای که باید باز شود.
flag (str) --
- 'r' (پیش‌فرض): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
می‌توان نویسه‌های اضافی زیر را برای کنترل چگونگی باز شدن پایگاه داده اضافه کرد:
- 'f': پایگاه داده را در حالت سریع باز می‌کند. نوشتن‌ها در پایگاه داده همگام‌سازی نخواهند شد.
- 's': حالت همگام‌سازی‌شده. تغییرات پایگاه داده بلافاصله در پرونده نوشته می‌شوند.
- 'u': پایگاه داده را قفل نکنید.
همه‌ی پرچم‌ها برای همه‌ی نسخه‌های GDBM معتبر نیستند. برای فهرستی از نویسه‌های پرچم پشتیبانی‌شده، عضو open_flags را ببینید.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

برانگیختن:

error -- اگر آرگومان flag نامعتبری ارسال شود.

تغییر یافته در نسخه‌ی 3.11: filename یک شیء شبه‌مسیر (path-like object) را می‌پذیرد.

اشیای gdbm مانند نگاشت‌های تغییرپذیر رفتار می‌کنند، اما متدهای items()، values()، pop()، popitem() و update() پشتیبانی نمی‌شوند؛ متد keys() یک فهرست برمی‌گرداند و متد setdefault() به ۲ آرگومان نیاز دارد. همچنین از یک مدیر زمینه‌ی «بستن» از طریق کلیدواژه‌ی with پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.2: متدهای get() و setdefault() افزوده شدند.

تغییر یافته در نسخه‌ی 3.13: متد clear() افزوده شد.

متدهای زیر نیز ارائه شده‌اند:

gdbm.close()¶: پایگاه داده GDBM را ببندید.

gdbm.firstkey()¶: می‌توان با استفاده از این متد و متد nextkey()، روی تمام کلیدهای پایگاه داده حلقه زد. پیمایش به ترتیب مقادیر هش داخلی GDBM است و بر اساس مقادیر کلید مرتب نخواهد شد. این متد کلید شروع را برمی‌گرداند.

gdbm.nextkey(key)¶

کلیدی را که در پیمایش پس از key می‌آید برمی‌گرداند. کد زیر همه‌ی کلیدهای پایگاه داده‌ی db را، بدون نیاز به ایجاد فهرستی حاوی همه‌ی آن‌ها در حافظه، چاپ می‌کند:

k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)

gdbm.reorganize()¶: اگر حذف‌های زیادی انجام داده‌اید و می‌خواهید فضای مصرفی پرونده GDBM را کاهش دهید، این روتین پایگاه داده را بازآرایی می‌کند. اشیای gdbm طول پرونده پایگاه داده را کوتاه نمی‌کنند، مگر با استفاده از این بازآرایی؛ در غیر این صورت، فضای حذف‌شده در پرونده نگه داشته شده و با افزودن جفت‌های جدید (کلید، مقدار) دوباره استفاده می‌شود.

gdbm.sync()¶: هنگامی که پایگاه داده در حالت سریع باز شده باشد، این متد باعث می‌شود هرگونه داده‌ی نوشته‌نشده روی دیسک نوشته شود.

`dbm.ndbm` --- مدیر پایگاه داده جدید¶

کد منبع: Lib/dbm/ndbm.py

ماژول dbm.ndbm رابطی به کتابخانه‌ی NDBM فراهم می‌کند. این ماژول را می‌توان با رابط «کلاسیک» NDBM یا رابط سازگاری GDBM استفاده کرد.

توجه

قالب‌های پرونده‌ای که dbm.gnu و dbm.ndbm ایجاد می‌کنند ناسازگار هستند و نمی‌توان از آن‌ها به‌جای یکدیگر استفاده کرد.

هشدار

کتابخانه NDBM که به‌عنوان بخشی از macOS عرضه می‌شود، محدودیت مستندنشده‌ای در اندازه‌ی مقادیر دارد که می‌تواند هنگام ذخیره مقادیر بزرگ‌تر از این حد، منجر به فروپاشی پرونده‌های پایگاه داده شود. خواندن چنین پرونده‌های خرابی می‌تواند منجر به فروپاشی سخت (segmentation fault) شود.

دسترس‌پذیری: not Android, not iOS, not WASI.

این ماژول در پلتفرم‌های موبایل یا پلتفرم‌های WebAssembly پشتیبانی نمی‌شود.

دسترس‌پذیری: Unix.

exception dbm.ndbm.error¶: در صورت بروز خطاهای خاص dbm.ndbm، مانند خطاهای ورودی/خروجی، پرتاب می‌شود. KeyError برای خطاهای عمومی نگاشت، مانند تعیین یک کلید نادرست، پرتاب می‌شود.

dbm.ndbm.library¶: نام کتابخانه پیاده‌سازی NDBM استفاده‌شده.

dbm.ndbm.open(filename, flag='r', mode=0o666, /)¶

یک پایگاه داده NDBM را باز می‌کند و یک شیء ndbm را برمی‌گرداند.

پارامترها:

filename (path-like object) -- نام پایه‌ی پرونده پایگاه داده (بدون پسوندهای .dir یا .pag).
flag (str) --
- 'r' (پیش‌فرض): Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c': Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

تغییر یافته در نسخه‌ی 3.11: path-like object را برای نام پرونده می‌پذیرد.

اشیای ndbm رفتاری مشابه نگاشت‌های تغییرپذیر دارند، اما متدهای items()، values()، pop()، popitem() و update() پشتیبانی نمی‌شوند؛ متد keys() یک فهرست برمی‌گرداند و متد setdefault() به دو آرگومان نیاز دارد. همچنین از یک مدیر زمینه «بستن» از طریق کلیدواژه with پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.2: متدهای get() و setdefault() افزوده شدند.

تغییر یافته در نسخه‌ی 3.13: متد clear() افزوده شد.

متد زیر نیز ارائه شده است:

ndbm.close()¶: پایگاه داده NDBM را ببندید.

`dbm.dumb` --- پیاده‌سازی قابل‌حمل DBM¶

کد منبع: Lib/dbm/dumb.py

توجه

ماژول dbm.dumb به‌عنوان آخرین راه‌حل جایگزین برای ماژول dbm در نظر گرفته شده است، برای زمانی که ماژول قوی‌تری در دسترس نباشد. ماژول dbm.dumb برای سرعت نوشته نشده است و تقریباً به اندازه‌ی سایر ماژول‌های پایگاه داده پرکاربرد نیست.

ماژول dbm.dumb رابطی پایا شبیه به dict فراهم می‌کند که به‌طور کامل به زبان پایتون نوشته شده است. برخلاف سایر بک‌اندهای dbm، مانند dbm.gnu، نیازی به کتابخانه‌ی خارجی نیست.

ماژول dbm.dumb موارد زیر را تعریف می‌کند:

exception dbm.dumb.error¶: در صورت بروز خطاهای مختص dbm.dumb، مانند خطاهای ورودی/خروجی، پرتاب می‌شود. KeyError برای خطاهای عمومی نگاشت، مانند مشخص کردن کلید نادرست، پرتاب می‌شود.

dbm.dumb.open(filename, flag='c', mode=0o666)¶

یک پایگاه داده‌ی dbm.dumb را باز کنید.

پارامترها:

filename -- نام پایه پرونده پایگاه داده (بدون پسوندها). یک پایگاه داده جدید پرونده‌های زیر را ایجاد می‌کند: - filename.dat - filename.dir
flag (str) --
- 'r': Open existing database for reading only.
- 'w': Open existing database for reading and writing.
- 'c' (پیش‌فرض): Open database for reading and writing, creating it if it doesn't exist.
- 'n': Always create a new, empty database, open for reading and writing.
mode (int) -- The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

هشدار

ممکن است بارگذاری پایگاه داده‌ای با یک ورودی به‌اندازه کافی بزرگ/پیچیده، به دلیل محدودیت‌های عمق پشته در کامپایلر AST پایتون، باعث از کار افتادن مفسر پایتون شود.

تغییر یافته در نسخه‌ی 3.5: open() همیشه وقتی flag برابر 'n' باشد، یک پایگاه داده جدید ایجاد می‌کند.

تغییر یافته در نسخه‌ی 3.8: اگر flag برابر 'r' باشد، پایگاه داده به‌صورت فقط‌خواندنی باز می‌شود. اگر flag برابر 'r' یا 'w' باشد، در صورتی که پایگاه داده وجود نداشته باشد، ایجاد نمی‌شود.

تغییر یافته در نسخه‌ی 3.11: filename یک شیء شبه‌مسیر (path-like object) را می‌پذیرد.

شیء پایگاه داده‌ی برگردانده‌شده مانند یک نگاشت تغییرپذیر رفتار می‌کند، اما متدهای keys() و items() فهرست‌ها را برمی‌گردانند و متد setdefault() به دو آرگومان نیاز دارد. همچنین از یک مدیر زمینه‌ی «بستن» از طریق کلیدواژه‌ی with پشتیبانی می‌کند.

متدهای زیر نیز ارائه شده‌اند:

dumbdbm.close()¶: پایگاه داده را ببندید.

dumbdbm.sync()¶: پوشه و پرونده‌های داده روی دیسک را همگام‌سازی می‌کند. این متد توسط متد shelve.Shelf.sync() فراخوانی می‌شود.

`dbm` --- رابط‌هایی برای «پایگاه‌های داده»ی یونیکس¶

`dbm.sqlite3` --- بک‌اند SQLite برای dbm¶

`dbm.gnu` --- مدیر پایگاه‌داده GNU¶

`dbm.ndbm` --- مدیر پایگاه داده جدید¶

`dbm.dumb` --- پیاده‌سازی قابل‌حمل DBM¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

dbm --- رابط‌هایی برای «پایگاه‌های داده»ی یونیکس¶

dbm.sqlite3 --- بک‌اند SQLite برای dbm¶

dbm.gnu --- مدیر پایگاه‌داده GNU¶

dbm.ndbm --- مدیر پایگاه داده جدید¶

dbm.dumb --- پیاده‌سازی قابل‌حمل DBM¶

`dbm` --- رابط‌هایی برای «پایگاه‌های داده»ی یونیکس¶

`dbm.sqlite3` --- بک‌اند SQLite برای dbm¶

`dbm.gnu` --- مدیر پایگاه‌داده GNU¶

`dbm.ndbm` --- مدیر پایگاه داده جدید¶

`dbm.dumb` --- پیاده‌سازی قابل‌حمل DBM¶