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


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

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

# Открыть базу данных, создав её при необходимости.
with dbm.open('cache', 'c') as db:

    # Записать некоторые значения
    db[b'hello'] = b'there'
    db['digitology.tech'] = 'Веб-сайт Python'
    db['news.example.loc'] = 'Кабельная Новостная Сеть'

    # Обратите внимание, что ключи теперь считаются байтами.
    assert db[b'digitology.tech'] == b'Веб-сайт Python'
    # Обратите внимание, что значение теперь в байтах.
    assert db['news.example.loc'] == b'Кабельная Новостная Сеть'

    # Часто используемые методы интерфейса dict тоже работают.
    print(db.get('python.loc', b'отсутствует'))

    # Сохранение нестрокового ключа или значения вызовет исключение (большинство
    # скорее всего TypeError).
    db['test'] = 4

# db автоматически закрывается при выходе из оператора with.

См.также

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

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

dbm.gnu — Новая интерпретация GNU dbm


Данный модуль очень похож на модуль 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 есть следующие методы:

gdbm.firstkey()

Если возможно, перебирает каждый ключ в базе данных, используя данный метод и метод nextkey(). Обход упорядочен по внутренним хэш-значениям gdbm и не будет сортироваться по значениям ключа. Данный метод возвращает начальный ключ.

gdbm.nextkey(key)

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

k = db.firstkey()
while k != None:
    print(k)
    k = db.nextkey(k)
gdbm.reorganize()

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

gdbm.sync()

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

gdbm.close()

Закрыть gdbm базу данных.

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


Модуль 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

Примечание

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


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

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

exception dbm.dumb.error

Возникает при ошибках, характерных для dbm.dumb, таких как ошибки ввода-вывода. Вызывается KeyError для общих ошибок отображения, таких как указание неправильного ключа.

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

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

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

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

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

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

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

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

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

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

dumbdbm.sync()

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

dumbdbm.close()

Закрыть базу данных dumbdbm.