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

Ограничения

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

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

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

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

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

Параметр keyencoding задаёт кодировку, используемую для кодирования ключей перед их передачей в лежащий в основе объект dict.

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

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

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

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

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 вместо объекта, подобного словарю. Лежащий в основе файл открывается с помощью 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