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

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