dbm — Интерфейсы к Unix-базам данных

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

dbm — это универсальный интерфейс к вариантам баз данных DBM — dbm.gnu или dbm.ndbm. Если ни один из этих модулей не установлен, будет использоваться медленное, но простое реализация в модуле dbm.dumb. Существует интерфейс сторонних разработчиков к базе данных Oracle Berkeley DB.

exception dbm.error: Кортеж, содержащий исключения, которые могут быть подняты каждым из поддерживаемых модулей, с уникальным исключением, также именованным dbm.error как первым элементом — последнее используется, когда dbm.error поднимается.

dbm.whichdb(filename)

Эта функция пытается определить, какой из нескольких доступных простых модулей баз данных — dbm.gnu, dbm.ndbm или dbm.dumb — следует использовать для открытия заданного файла.

Возвращает одно из следующих значений: None если файл не может быть открыт, потому что он недоступен для чтения или не существует; пустую строку ('') если формат файла не может быть угадан; или строку, содержащую имя необходимого модуля, например, 'dbm.ndbm' или 'dbm.gnu'.

Изменено в версии 3.11: Принимает объект, подобный пути в качестве имени файла.

dbm.open(file, flag='r', mode=0o666)

Открывает файл базы данных file и возвращает соответствующий объект.

Если файл базы данных уже существует, используется функция whichdb() для определения его типа, и используется соответствующий модуль; если он не существует, используется первый из перечисленных выше модулей, который может быть импортирован.

Необязательный аргумент flag может быть:

Значение	Значение
`'r'`	Открыть существующую базу данных только для чтения (по умолчанию)
`'w'`	Открыть существующую базу данных для чтения и записи
`'c'`	Открыть базу данных для чтения и записи, создав её, если она не существует
`'n'`	Всегда создать новую пустую базу данных, открытую для чтения и записи

Необязательный аргумент mode — это режим Unix файла, используемый только при необходимости создания базы данных. По умолчанию он равен восьмеричному 0o666 (и будет изменён текущим umask).

Объект, возвращаемый open(), поддерживает ту же базовую функциональность, что и словари; ключи и соответствующие им значения могут храниться, извлекаться и удаляться, а оператор in и метод keys() доступны, а также get() и setdefault().

Изменено в версии 3.2: get() и setdefault() теперь доступны во всех модулях баз данных.

Изменено в версии 3.8: Удаление ключа из базы данных только для чтения приводит к ошибке, специфичной для модуля базы данных, вместо KeyError.

Изменено в версии 3.11: Принимает объект, подобный пути в качестве файла.

Ключи и значения всегда хранятся в виде байтов. Это означает, что при использовании строк они неявно преобразуются в кодировку по умолчанию перед хранением.

Эти объекты также поддерживают использование в операторе with, который автоматически закроет их по завершении.

Изменено в версии 3.4: Добавлена поддержка протокола управления контекстом в объекты, возвращаемые open().

В следующем примере записываются некоторые имена хостов и соответствующее название, а затем выводится содержимое базы данных:

import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

См. также

Module shelve: Модуль сохранения, который хранит данные, отличные от строк.

Индивидуальные подмодули описаны в следующих разделах.

dbm.gnu — Переосмысление dbm в GNU

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

Этот модуль очень похож на модуль dbm, но использует библиотеку GNU gdbm для предоставления дополнительных функций. Обратите внимание, что форматы файлов, созданные с помощью dbm.gnu и dbm.ndbm, несовместимы.

Модуль dbm.gnu предоставляет интерфейс к библиотеке GNU DBM. Объекты dbm.gnu.gdbm ведут себя как отображения (словари), за исключением того, что ключи и значения всегда преобразуются в байты перед сохранением. Вывод объекта gdbm не выводит ключи и значения, и методы items() и values() не поддерживаются.

exception dbm.gnu.error: Вызывается при возникновении ошибок, специфичных для dbm.gnu, таких как ошибки ввода-вывода. KeyError генерируется для общих ошибок отображения, таких как указание некорректного ключа.

dbm.gnu.open(filename[, flag[, mode]])

Открыть базу данных gdbm и вернуть объект gdbm. Аргумент filename — имя файла базы данных.

Необязательный аргумент flag может принимать следующие значения:

Значение	Описание
`'r'`	Открыть существующую базу данных только для чтения (по умолчанию)
`'w'`	Открыть существующую базу данных для чтения и записи
`'c'`	Открыть базу данных для чтения и записи, создав её, если она не существует
`'n'`	Всегда создать новую пустую базу данных, открытую для чтения и записи

К флагу можно добавить следующие дополнительные символы для управления способом открытия базы данных:

Значение	Описание
`'f'`	Открыть базу данных в быстром режиме. Записи в базу данных не будут синхронизированы.
`'s'`	Режим синхронизации. Это заставит изменения в базе данных немедленно записываться в файл.
`'u'`	Не блокировать базу данных.

Не все флаги допустимы для всех версий gdbm. Модульная константа open_flags представляет собой строку поддерживаемых символов флагов. Исключение error генерируется, если указан недопустимый флаг.

Необязательный аргумент mode — это режим Unix файла, используемый только при создании базы данных. По умолчанию он равен восьмеричному 0o666.

В дополнение к методам, похожим на методы словарей, объекты gdbm имеют следующие методы:

Изменено в версии 3.11: Принимает объект, подобный пути для имени файла.

gdbm.firstkey(): Возможно перебрать каждый ключ в базе данных с помощью этого метода и метода nextkey(). Перебор упорядочен по внутренним значениям хешей gdbm, а не по значениям ключей. Этот метод возвращает начальный ключ.

gdbm.nextkey(key)

Возвращает ключ, следующий за key в процессе обхода. Следующий код выводит каждый ключ в базе данных db, не создавая список, содержащий все ключи в памяти:

k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)

gdbm.reorganize(): Если вы выполнили много удалений и хотите уменьшить занимаемое пространство файла gdbm, эта процедура перестроит базу данных. Объекты gdbm не сократят размер файла базы данных, кроме как с помощью этой перестройки; в противном случае удаленное пространство файла будет сохранено и повторно использовано, когда добавляются новые пары (ключ, значение).

gdbm.sync(): Если база данных открыта в быстром режиме, этот метод принудительно записывает любые несохраненные данные на диск.

gdbm.close(): Закрыть базу данных gdbm.

dbm.ndbm — Интерфейс, основанный на ndbm

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

Модуль dbm.ndbm предоставляет интерфейс к библиотеке Unix “(n)dbm”. Объекты Dbm ведут себя как отображения (словари), за исключением того, что ключи и значения всегда сохраняются как байты. Вывод объекта dbm не выводит ключи и значения, а методы items() и values() не поддерживаются.

Этот модуль можно использовать с классическим интерфейсом ndbm или интерфейсом совместимости GNU GDBM. В Unix скрипт configure попытается найти соответствующий заголовочный файл, чтобы упростить сборку этого модуля.

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

Библиотека ndbm, поставляемая в составе macOS, имеет недокументированное ограничение на размер значений, что может привести к повреждению файлов базы данных при сохранении значений, превышающих это ограничение. Чтение таких поврежденных файлов может привести к аварийной остановке (ошибке сегментации).

exception dbm.ndbm.error: Возникает при ошибках, специфичных для dbm.ndbm, таких как ошибки ввода-вывода. KeyError генерируется при общих ошибках отображения, таких как указание некорректного ключа.

dbm.ndbm.library: Имя библиотеки реализации ndbm.

dbm.ndbm.open(filename[, flag[, mode]])

Открыть базу данных dbm и вернуть объект ndbm. Аргумент filename — имя файла базы данных (без расширений .dir или .pag).

Необязательный аргумент flag должен быть одним из следующих значений:

Значение	Описание
`'r'`	Открыть существующую базу данных только для чтения (по умолчанию)
`'w'`	Открыть существующую базу данных для чтения и записи
`'c'`	Открыть базу данных для чтения и записи, создав её, если она не существует
`'n'`	Всегда создать новую пустую базу данных, открытую для чтения и записи

Необязательный аргумент mode — это режим Unix файла, используемый только при создании базы данных. По умолчанию он равен восьмеричному 0o666 (и будет изменён действующим umask).

В дополнение к методам, похожим на методы словарей, объекты ndbm предоставляют следующие методы:

Изменено в версии 3.11: Принимает объект, подобный пути для имени файла.

ndbm.close(): Закрыть базу данных ndbm.

END_OF_DOCUMENT_MARKER

dbm.dumb — Переносимая реализация DBM

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

Примечание

Модуль dbm.dumb предназначен в качестве резервного варианта для модуля dbm, когда более надёжный модуль недоступен. Модуль dbm.dumb не оптимизирован под скорость и используется значительно реже, чем другие модули базы данных.

Модуль dbm.dumb предоставляет интерфейс, подобный словарям, сохраняющим данные постоянно и написанный полностью на Python. В отличие от других модулей, например dbm.gnu, не требуется внешняя библиотека. Как и для других сохраняемых словарей, ключи и значения всегда хранятся в формате байтов.

Модуль определяет следующее:

exception dbm.dumb.error: Вызывается при ошибках, специфичных для dbm.dumb, например, при ошибках ввода-вывода. KeyError генерируется при общих ошибках работы со словарями, например, при указании некорректного ключа.

dbm.dumb.open(filename[, flag[, mode]])

Открывает базу данных dumbdbm и возвращает объект dumbdbm. Аргумент filename — имя файла базы данных (без расширений). При создании базы данных dumbdbm создаются файлы с расширениями .dat и .dir.

Необязательный аргумент flag может принимать значения:

Значение	Значение
`'r'`	Открыть существующую базу данных только для чтения (по умолчанию)
`'w'`	Открыть существующую базу данных для чтения и записи
`'c'`	Открыть базу данных для чтения и записи, создав её, если она не существует
`'n'`	Всегда создать новую пустую базу данных, открыть для чтения и записи

Необязательный аргумент mode — права доступа в стиле Unix для файла, используемые только при создании базы данных. По умолчанию он равен 0o666 (и будет изменён действующей маской umask).

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

Возможна аварийная остановка интерпретатора Python при загрузке базы данных с достаточно большим/сложным записями из-за ограничений глубины стека в компиляторе AST Python.

Изменено в версии 3.5: open() всегда создаёт новую базу данных, когда флаг имеет значение 'n'.

Изменено в версии 3.8: База данных, открытая с флагом 'r', теперь только для чтения. Открытие с флагами 'r' и 'w' больше не создаёт базу данных, если она не существует.

Изменено в версии 3.11: Принимает объект пути в качестве значения filename.

В дополнение к методам, предоставляемым классом collections.abc.MutableMapping, объекты dumbdbm предоставляют следующие методы:

dumbdbm.sync(): Синхронизирует файлы каталога и данных на диске. Этот метод вызывается методом Shelve.sync().

dumbdbm.close(): Закрыть базу данных dumbdbm.