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 is not 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.