shelve – сохранение объектов Python¶shelve – Python object persistence

Ограничения¶Restrictions

• Выбор используемого пакета базы данных (например, dbm.ndbm или dbm.gnu) зависит от доступного интерфейса. Поэтому открывать базу данных напрямую с помощью dbm небезопасно. База данных также (к сожалению) подвержена ограничениям dbm, если он используется – это означает, что (рассоленное представление) хранящихся в базе объектов должно быть достаточно небольшим, и в редких случаях коллизии ключей могут привести к отказу базы данных в обновлении.

• Модуль shelve не поддерживает одновременный доступ на чтение и запись к объектам на полке. (Одновременный доступ на чтение от нескольких программ безопасен.) Когда программа открыла полку для записи, никакая другая программа не должна открывать её для чтения или записи. Для решения этой проблемы можно использовать блокировку файлов в Unix, но она отличается в разных версиях Unix и требует знания используемой реализации базы данных.

• В macOS dbm.ndbm может незаметно повредить файл базы данных при обновлениях, что может привести к серьёзным сбоям при попытке чтения из базы данных.

• Shelf.reorganize() может быть недоступен для всех пакетов баз данных и может временно увеличивать использование ресурсов (особенно дискового пространства) при вызове. Кроме того, он никогда не запускается автоматически и вместо этого должен вызываться явно.

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

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

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

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

Параметр 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(). Необязательные параметры протокол, 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 вместо dict-подобного объекта. Основной файл будет открыт с помощью dbm.open(). По умолчанию файл будет создан и открыт для чтения и записи. Необязательный параметр flag имеет ту же интерпретацию, что и для функции open(). Необязательные параметры протокол, writeback, serializer и deserializer имеют ту же интерпретацию, что и в open().

Изменено в версии 3.15: Добавлены параметры serializer и deserializer.

Пример¶Example

Обобщая интерфейс (key – строка, data – произвольный объект):

import shelve

d = shelve.open(filename)  # open -- файл может получить суффикс, добавленный низкоуровневой
                           # библиотекой

d[key] = data              # сохраняет данные по ключу (перезаписывает старые данные, если
                           # используется существующий ключ)
data = d[key]              # извлекает КОПИЮ данных по ключу (вызывает KeyError
                           # если такого ключа нет)
del d[key]                 # удалить данные, хранящиеся по ключу (вызывает KeyError
                           # если такого ключа нет)

flag = key in d            # true, если ключ существует
klist = list(d.keys())     # список всех существующих ключей (медленно!)

# так как d был открыт БЕЗ writeback=True, внимание:
d['xx'] = [0, 1, 2]        # это работает как ожидается, но...
d['xx'].append(3)          # *это не работает!* -- d['xx'] всё ещё [0, 1, 2]!

# открыв d без writeback=True, нужно писать код аккуратно:
temp = d['xx']             # извлекает копию
temp.append(5)             # изменяет копию
d['xx'] = temp             # сохраняет изменённую копию обратно для сохранения

# или, d=shelve.open(filename,writeback=True) позволил бы просто написать
# d['xx'].append(5) и это бы работало как ожидается, НО это также бы
# потребляло больше памяти и замедляло операцию d.close().

d.close()                  # закрыть его

Исключения¶Exceptions

exception shelve.ShelveError¶

Исключение возбуждается, когда один из аргументов deserializer и serializer отсутствует в open(), Shelf, BsdDbShelf и DbfilenameShelf.

Аргументы deserializer и serializer должны передаваться вместе.

Добавлено в версии 3.15.