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().

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

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

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

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.

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

12.5.1. 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 имеют следующие методы:

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.

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

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

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

Модуль 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 поддерживает только семантику значений 'c' и 'n'. Другие значения по умолчанию открывают базу данных для обновления и создают её, если она не существует.

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

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

Устарело начиная с версии 3.6, будет удалено в версии 3.8: Создание базы данных в режимах 'r' и 'w'. Изменение базы данных в режиме 'r'.

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

dumbdbm.sync()

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

dumbdbm.close()

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