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'.

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.

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

Эти объекты также поддерживают использование в операторе 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'`	Всегда создать новую пустую базу данных, открыть для чтения и записи

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

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

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

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

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

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 попытается найти соответствующий заголовочный файл для упрощения сборки этого модуля.

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 предоставляют следующий метод:

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

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' больше не создаёт базу данных, если она не существует.

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

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

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