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.

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

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.

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 предоставляет интерфейс к постоянному словарю, написанный полностью на языке 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).

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

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

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

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

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

dumbdbm.sync()

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

dumbdbm.close()

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