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'

Изменено в версии 3.11: filename принимает объект, подобный пути.

dbm.open(file, flag='r', mode=0o666)

Открывает базу данных и возвращает соответствующий объект базы данных.

Параметры:

file (объект, подобный пути) –

Файл базы данных, который нужно открыть.

Если файл базы данных уже существует, для определения его типа используется функция whichdb(), после чего используется соответствующий модуль; если файл не существует, используется первый из перечисленных выше подмодулей, который можно импортировать.
flag (str) –
- 'r' (по умолчанию): открыть существующую базу данных только для чтения.
- 'w': открыть существующую базу данных для чтения и записи.
- 'c': открыть базу данных для чтения и записи, создав её, если она не существует.
- 'n': всегда создавать новую пустую базу данных и открывать её для чтения и записи.
mode (int) – Режим доступа к файлу в Unix (по умолчанию: восьмеричное значение 0o666); используется только при создании базы данных.

Изменено в версии 3.11: file принимает объект, подобный пути.

Объект, возвращаемый функцией open(), поддерживает те же основные возможности, что и dict: ключи и соответствующие им значения можно сохранять, получать и удалять; также доступны оператор in и метод keys(), а также методы get() и setdefault().

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

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

Изменено в версии 3.2: Методы get() и setdefault() теперь доступны во всех серверных модулях dbm.

Изменено в версии 3.4: Для объектов, возвращаемых функцией open(), добавлена встроенная поддержка протокола управления контекстом.

Изменено в версии 3.8: При удалении ключа из базы данных, открытой только для чтения, вызывается исключение, специфичное для модуля базы данных, а не KeyError.

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

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 — менеджер баз данных GNU

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

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

Примечание

Форматы файлов, создаваемые модулями dbm.gnu и dbm.ndbm, несовместимы и не могут использоваться взаимозаменяемо.

exception dbm.gnu.error: Вызывается при ошибках, специфичных для dbm.gnu, например при ошибках ввода-вывода. При общих ошибках сопоставления, например при указании неверного ключа, вызывается KeyError.

dbm.gnu.open(filename, flag='r', mode=0o666, /)

Открывает базу данных GDBM и возвращает объект gdbm.

Параметры:

filename (объект, подобный пути) – Файл базы данных, который нужно открыть.
flag (str) –
- 'r' (по умолчанию): открыть существующую базу данных только для чтения.
- 'w': открыть существующую базу данных для чтения и записи.
- 'c': открыть базу данных для чтения и записи, создав её, если она не существует.
- 'n': всегда создавать новую пустую базу данных и открывать её для чтения и записи.
Для управления способом открытия базы данных можно добавить следующие дополнительные символы:
- 'f': открыть базу данных в быстром режиме. Записи в базу данных не будут синхронизироваться.
- 's': режим синхронизации. Изменения в базе данных будут немедленно записываться в файл.
- 'u': не блокировать базу данных.
Не все флаги допустимы во всех версиях GDBM. Список поддерживаемых символов флагов приведён в атрибуте open_flags.
mode (int) – Режим доступа к файлу в Unix (по умолчанию: восьмеричное значение 0o666); используется только при создании базы данных.

Вызывает исключения:

error – Если передан недопустимый аргумент flag.

Изменено в версии 3.11: filename принимает объект, подобный пути.

dbm.gnu.open_flags: Строка символов, поддерживаемых параметром flag функции open().

Объекты gdbm ведут себя подобно сопоставлениям, но методы items() и values() не поддерживаются. Также доступны следующие методы:

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 — новый менеджер баз данных

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

Модуль dbm.ndbm предоставляет интерфейс к библиотеке NDBM. Этот модуль можно использовать с «классическим» интерфейсом NDBM или интерфейсом совместимости с GDBM.

Примечание

Форматы файлов, создаваемые модулями dbm.gnu и dbm.ndbm, несовместимы и не могут использоваться взаимозаменяемо.

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

Библиотека NDBM, поставляемая в составе macOS, имеет недокументированное ограничение на размер значений, из-за которого при сохранении значений, превышающих этот предел, файлы базы данных могут быть повреждены. Чтение таких повреждённых файлов может привести к серьёзному сбою (ошибке сегментации).

exception dbm.ndbm.error: Вызывается при ошибках, специфичных для dbm.ndbm, например при ошибках ввода-вывода. При общих ошибках сопоставления, например при указании неверного ключа, вызывается KeyError.

dbm.ndbm.library: Имя используемой библиотеки реализации NDBM.

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

Открывает базу данных NDBM и возвращает объект ndbm.

Параметры:

filename (объект, подобный пути) – Базовое имя файла базы данных (без расширений .dir или .pag).
flag (str) –
- 'r' (по умолчанию): открыть существующую базу данных только для чтения.
- 'w': открыть существующую базу данных для чтения и записи.
- 'c': открыть базу данных для чтения и записи, создав её, если она не существует.
- 'n': всегда создавать новую пустую базу данных и открывать её для чтения и записи.
mode (int) – Режим доступа к файлу в Unix (по умолчанию: восьмеричное значение 0o666); используется только при создании базы данных.

Объекты ndbm ведут себя подобно сопоставлениям, но методы items() и values() не поддерживаются. Также доступны следующие методы:

Изменено в версии 3.11: Для параметра filename принимается объект, подобный пути.

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

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

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

Примечание

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

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

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

exception dbm.dumb.error: Вызывается при ошибках, специфичных для dbm.dumb, например при ошибках ввода-вывода. При общих ошибках сопоставления, например при указании неверного ключа, вызывается KeyError.

dbm.dumb.open(filename, flag='c', mode=0o666)

Открывает базу данных dbm.dumb. Возвращаемый объект базы данных ведёт себя подобно сопоставлению и дополнительно предоставляет методы sync() и close().

Параметры:

filename –

Базовое имя файла базы данных (без расширений). Для новой базы данных создаются следующие файлы:
- filename.dat
- filename.dir
flag (str) –
- 'r': открыть существующую базу данных только для чтения.
- 'w': открыть существующую базу данных для чтения и записи.
- 'c' (по умолчанию): открыть базу данных для чтения и записи, создав её, если она не существует.
- 'n': всегда создавать новую пустую базу данных и открывать её для чтения и записи.
mode (int) – Режим доступа к файлу в Unix (по умолчанию: восьмеричное значение 0o666); используется только при создании базы данных.

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

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

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

Изменено в версии 3.8: Если flag имеет значение 'r', база данных открывается только для чтения. Если flag имеет значение 'r' или 'w', база данных не создаётся, если она не существует.

Изменено в версии 3.11: filename принимает объект, подобный пути.

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

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

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