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.

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

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.

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.

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() всегда создаёт новую базу данных, когда значение flag равно 'n'.

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

dumbdbm.sync()

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

dumbdbm.close()

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