محدودیت‌ها¶

• انتخاب بسته‌ی پایگاه داده‌ای که استفاده خواهد شد (مانند dbm.ndbm یا dbm.gnu) به این بستگی دارد که کدام رابط در دسترس باشد. بنابراین باز کردن پایگاه داده به‌صورت مستقیم با استفاده از dbm ایمن نیست. پایگاه داده نیز (متأسفانه) در صورت استفاده از dbm مشمول محدودیت‌های آن است — این بدان معناست که بازنمایی pickleشده (pickled representation) از اشیاء ذخیره‌شده در پایگاه داده باید نسبتاً کوچک باشد، و در موارد نادر ممکن است برخورد کلیدها باعث شود پایگاه داده از پذیرفتن به‌روزرسانی‌ها خودداری کند.

• ماژول shelve از دسترسی همزمان خواندن/نوشتن به اشیای ذخیره‌شده در shelf پشتیبانی نمی‌کند. (چندین دسترسی خواندن همزمان بی‌خطر است.) هنگامی که برنامه‌ای یک shelf را برای نوشتن باز نگه داشته است، هیچ برنامه دیگری نباید آن را برای خواندن یا نوشتن باز نگه دارد. می‌توان از قفل‌گذاری پرونده در یونیکس برای حل این مسئله استفاده کرد، اما این رفتار در نسخه‌های مختلف یونیکس متفاوت است و به دانش درباره‌ی پیاده‌سازی پایگاه داده‌ی استفاده‌شده نیاز دارد.

• در macOS، dbm.ndbm می‌تواند هنگام به‌روزرسانی‌ها بدون هشدار پرونده پایگاه داده را خراب کند، که این می‌تواند هنگام تلاش برای خواندن از پایگاه داده باعث فروپاشی‌های سخت شود.

• ممکن است Shelf.reorganize() برای همه‌ی بسته‌های پایگاه داده در دسترس نباشد و هنگام فراخوانی ممکن است به طور موقت استفاده از منابع (به ویژه فضای دیسک) را افزایش دهد. علاوه بر این، هرگز به طور خودکار اجرا نمی‌شود و در عوض باید به طور صریح فراخوانی شود.

class shelve.Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8', *, serializer=None, deserializer=None)¶

زیرکلاسی از collections.abc.MutableMapping که مقادیر پیکل‌شده را در شیء dict ذخیره می‌کند.

به‌طور پیش‌فرض، از پیکل‌های ایجادشده با pickle.DEFAULT_PROTOCOL برای سریال‌سازی مقادیر استفاده می‌شود. نسخه‌ی پروتکل پیکل را می‌توان با پارامتر protocol مشخص کرد. برای بحثی درباره‌ی پروتکل‌های پیکل، مستندات pickle را ببینید.

اگر پارامتر writeback برابر True باشد، شیء نهانگاهی از تمام آیتم‌های دسترسی‌شده را نگه می‌دارد و آن‌ها را در زمان sync و close به دیکشنری بازمی‌نویسد. این امر عملیات طبیعی روی آیتم‌های تغییرپذیر را ممکن می‌سازد، اما می‌تواند حافظه بسیار بیشتری مصرف کند و باعث شود sync و close زمان زیادی طول بکشند.

پارامتر keyencoding کدگذاری‌ای است که برای کدگذاری کلیدها پیش از استفاده از آن‌ها در دیکشنری زیرین به کار می‌رود.

پارامترهای serializer و deserializer همان تفسیری را دارند که در open() وجود دارد.

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

تغییر یافته در نسخه‌ی 3.2: پارامتر keyencoding افزوده شد؛ پیش‌تر، کلیدها همیشه با UTF-8 کدگذاری می‌شدند.

تغییر یافته در نسخه‌ی 3.4: پشتیبانی از مدیر زمینه افزوده شد.

تغییر یافته در نسخه‌ی 3.10: pickle.DEFAULT_PROTOCOL اکنون به‌عنوان پروتکل پیش‌فرض pickle استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.15: پارامترهای serializer و deserializer اضافه شدند.

class shelve.BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8', *, serializer=None, deserializer=None)¶

زیرکلاسی از Shelf که متدهای first()، next()، previous()، last() و set_location() را ارائه می‌دهد. این موارد در ماژول شخص ثالث bsddb از pybsddb موجود هستند اما در سایر ماژول‌های پایگاه داده حضور ندارند. شیء dict ارسال‌شده به سازنده باید از این متدها پشتیبانی کند. این کار معمولاً با فراخوانی یکی از توابع bsddb.hashopen()، bsddb.btopen() یا bsddb.rnopen() انجام می‌شود. پارامترهای اختیاری protocol، writeback، keyencoding، serializer و deserializer همان تفسیری را دارند که در open() دیده می‌شود.

تغییر یافته در نسخه‌ی 3.15: پارامترهای serializer و deserializer اضافه شدند.

class shelve.DbfilenameShelf(filename, flag='c', protocol=None, writeback=False, *, serializer=None, deserializer=None)¶

زیرکلاسی از Shelf که به جای یک شیء دیکشنری‌مانند، یک filename را می‌پذیرد. پرونده‌ی زیربنایی با استفاده از dbm.open() باز خواهد شد. به طور پیش‌فرض، پرونده برای خواندن و نوشتن ایجاد و باز می‌شود. پارامتر اختیاری flag همان تفسیری را دارد که برای تابع open() در نظر گرفته شده است. پارامترهای اختیاری protocol، writeback، serializer و deserializer همان تفسیری را دارند که در open() وجود دارد.

تغییر یافته در نسخه‌ی 3.15: پارامترهای serializer و deserializer اضافه شدند.

مثال¶

برای جمع‌بندی رابط (key یک رشته است، data یک شیء دلخواه است):

import shelve

d = shelve.open(filename)  # open -- file may get suffix added by low-level
                           # library

d[key] = data              # store data at key (overwrites old data if
                           # using an existing key)
data = d[key]              # retrieve a COPY of data at key (raise KeyError
                           # if no such key)
del d[key]                 # delete data stored at key (raises KeyError
                           # if no such key)

flag = key in d            # true if the key exists
klist = list(d.keys())     # a list of all existing keys (slow!)

# as d was opened WITHOUT writeback=True, beware:
d['xx'] = [0, 1, 2]        # this works as expected, but...
d['xx'].append(3)          # *this doesn't!* -- d['xx'] is STILL [0, 1, 2]!

# having opened d without writeback=True, you need to code carefully:
temp = d['xx']             # extracts the copy
temp.append(5)             # mutates the copy
d['xx'] = temp             # stores the copy right back, to persist it

# or, d=shelve.open(filename,writeback=True) would let you just code
# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.

d.close()                  # close it

استثناها¶

exception shelve.ShelveError¶

استثنایی که وقتی یکی از آرگومان‌های deserializer و serializer در open()، Shelf، BsdDbShelf و DbfilenameShelf وجود نداشته باشد، بالا آورده می‌شود.

آرگومان‌های deserializer و serializer باید با هم داده شوند.

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