shelve — Постоянное хранение объектов Python

Ограничения

• Выбор модуля базы данных (например, dbm.ndbm или dbm.gnu) зависит от доступного интерфейса. Поэтому небезопасно открывать базу данных непосредственно с помощью dbm. База данных также (к сожалению) ограничена возможностями dbm, если она используется — это означает, что (сериализованное представление) объектов, хранящихся в базе данных, должны быть относительно небольшими, и в редких случаях коллизии ключей могут привести к тому, что база данных откажется от обновлений.
• Модуль shelve не поддерживает параллельный доступ для чтения/записи к объектам на полке. (Несколько одновременных обращений для чтения безопасны.) Когда программа открывает полку для записи, никакая другая программа не должна открывать её для чтения или записи. Для решения этой проблемы можно использовать блокировку файлов Unix, но это различается в разных версиях Unix и требует знания о реализованной базе данных.
• В macOS модуль dbm.ndbm может молча повреждать файл базы данных при обновлении, что может привести к жёстким сбоям при попытке чтения из базы данных.

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

Подкласс collections.abc.MutableMapping, который хранит закодированные значения в объекте dict.

По умолчанию для сериализации значений используются данные, закодированные с помощью протокола pickle.DEFAULT_PROTOCOL. Версия протокола pickle может быть указана с помощью параметра protocol. См. документацию по pickle для обсуждения протоколов pickle.

Если параметр writeback равен True, объект будет хранить кэш всех обращенных элементов и запишет их обратно в dict в момент синхронизации и закрытия. Это позволяет естественным образом работать с мутабельными элементами, но может занимать значительно больше памяти и делать синхронизацию и закрытие более медленными.

Параметр keyencoding — кодировка, используемая для кодирования ключей перед их использованием с основным словарем.

Объект Shelf также может использоваться как менеджер контекста, в этом случае он будет автоматически закрыт при завершении блока with.

Изменено в версии 3.2: Добавлен параметр keyencoding; ранее ключи всегда кодировались в UTF-8.

Изменено в версии 3.4: Добавлена поддержка менеджеров контекста.

Изменено в версии 3.10: pickle.DEFAULT_PROTOCOL теперь используется в качестве стандартного протокола pickle.

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

Подкласс Shelf, который предоставляет first(), next(), previous(), last() и set_location() методы. Они доступны в стороннем модуле bsddb из pybsddb, но не в других модулях баз данных. Объект dict, переданный в конструктор, должен поддерживать эти методы. Это обычно достигается вызовом одного из bsddb.hashopen(), bsddb.btopen() или bsddb.rnopen(). Необязательные параметры protocol, writeback и keyencoding имеют такое же значение, как и для класса Shelf.

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

Подкласс Shelf, который принимает filename вместо объекта dict. Базовый файл будет открыт с помощью dbm.open(). По умолчанию файл будет создан и открыт для чтения и записи. Необязательный параметр flag имеет такое же значение, как и для функции open(). Необязательные параметры protocol и writeback имеют такое же значение, как и для класса Shelf.

Пример

Для обобщения интерфейса (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