Содержание страницы

12.3. `shelve` – постоянное хранение объектов Python¶shelve – Python object persistence

Исходный код: Lib/shelve.py

«Полка» (shelf) – это постоянный объект, похожий на словарь. Отличие от баз данных «dbm» в том, что значения (не ключи!) на полке могут быть практически произвольными объектами Python – всем, с чем может работать модуль pickle. Сюда входят большинство экземпляров классов, рекурсивные типы данных и объекты, содержащие много общих подобъектов. Ключи – обычные строки.

shelve.open(filename, flag='c', protocol=None, writeback=False)¶

Открывает постоянный словарь. Указанное имя файла является базовым для нижележащей базы данных. Как побочный эффект, к имени файла может быть добавлено расширение, и может быть создано более одного файла. По умолчанию нижележащий файл базы данных открывается для чтения и записи. Необязательный параметр flag имеет ту же интерпретацию, что и параметр flag функции dbm.open().

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

Из-за семантики Python полка не может узнать, когда изменяется изменяемая запись постоянного словаря. По умолчанию изменённые объекты записываются только при присваивании полке (см. Пример). Если необязательный параметр writeback установлен в True, все запрашиваемые записи также кэшируются в памяти и записываются обратно при вызове sync() и close(); это может упростить изменение изменяемых записей в постоянном словаре, но, если запрашивается много записей, может потреблять огромные объёмы памяти для кэша, а также может сделать операцию закрытия очень медленной, так как все запрошенные записи записываются обратно (нет способа определить, какие из запрошенных записей являются изменяемыми и какие из них были фактически изменены).

Примечание

Не полагайтесь на автоматическое закрытие полки; всегда явно вызывайте close(), когда она больше не нужна, или используйте shelve.open() как менеджер контекста:

with shelve.open('spam') as db:
    db['eggs'] = 'eggs'

Предупреждение

Поскольку модуль shelve основан на pickle, загружать полку из ненадёжного источника небезопасно. Как и в случае с pickle, загрузка полки может выполнить произвольный код.

Объекты Shelf поддерживают все методы, поддерживаемые словарями. Это облегчает переход от скриптов, основанных на словарях, к скриптам, требующим постоянного хранения.

Поддерживаются два дополнительных метода:

Shelf.sync()¶: Записывает обратно все записи из кэша, если полка была открыта с writeback, установленным в True. Также очищает кэш и синхронизирует постоянный словарь на диске, если это возможно. Вызывается автоматически при закрытии полки с помощью close().

Shelf.close()¶: Синхронизирует и закрывает постоянный объект dict. Операции над закрытой полкой завершатся ошибкой ValueError.

См. также

Рецепт постоянного словаря с широко поддерживаемыми форматами хранения и скоростью нативных словарей.

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

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

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

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

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

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

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

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

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

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

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(). Необязательные параметры протокол, writeback и keyencoding имеют тот же смысл, что и для класса Shelf.

class shelve.DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)¶: Подкласс Shelf, который принимает filename вместо объекта, похожего на словарь. Базовый файл будет открыт с помощью dbm.open(). По умолчанию файл создаётся и открывается для чтения и записи. Необязательный параметр flag имеет то же значение, что и для функции open(). Необязательные параметры протокол и writeback имеют то же значение, что и для класса Shelf.

12.3.2. Пример¶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()                  # закрыть его