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(): Закрывает базу данных.