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

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

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

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

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

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

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

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 — Переосмысление 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 предназначен в качестве последнего варианта резервного копирования для модуля dbm, когда более надёжный модуль недоступен. Модуль dbm.dumb не написан для скорости и не используется так часто, как другие модули базы данных.

Модуль 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 может быть:

Значение	Значение
`'r'`	Открыть существующую базу данных только для чтения (по умолчанию)
`'w'`	Открыть существующую базу данных для чтения и записи
`'c'`	Открыть базу данных для чтения и записи, создав её, если она не существует
`'n'`	Всегда создать новую пустую базу данных, открыть для чтения и записи

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

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

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

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

Изменено в версии 3.8: База данных, открытая с флагами 'r' , теперь является только для чтения. Открытие с флагами 'r' и 'w' больше не создаёт базу данных, если она не существует.

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

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

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