dbm — Интерфейсы к Unix-«базам данных»

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

dbm — это обобщённый интерфейс к вариантам баз данных DBM:

dbm.sqlite3
dbm.gnu
dbm.ndbm

Если ни один из этих модулей не установлен, будет использоваться медленный, но простой механизм в модуле dbm.dumb. Существует интерфейс сторонних разработчиков к базе данных Oracle Berkeley DB.

exception dbm.error: Кортеж, содержащий исключения, которые могут быть подняты каждым из поддерживаемых модулей, с уникальным исключением, также именованным dbm.error, как первый элемент — последний используется, когда поднято dbm.error.

dbm.whichdb(filename)

Эта функция пытается угадать, какой из нескольких доступных простых модулей баз данных — dbm.sqlite3, 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.sqlite3 — Бэкенд SQLite для dbm

Добавлен в версии 3.13.

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

Этот модуль использует стандартный модуль sqlite3 для предоставления бэкенда SQLite для модуля dbm. Таким образом, файлы, созданные dbm.sqlite3, могут быть открыты sqlite3 или любым другим браузером SQLite, включая SQLite CLI.

Доступность: не WASI.

Этот модуль не работает или недоступен на платформах WebAssembly. См. Платформы WebAssembly для получения дополнительной информации.

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

Открывает базу данных SQLite. Возвращаемый объект ведет себя как отображение, реализует метод close(), и поддерживает «закрытие» менеджера контекста с помощью ключевого слова with.

Параметры:

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

END_OF_DOCUMENT_MARKER ```

dbm.gnu — Управляющий базой данных GNU

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

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

Примечание

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

Доступность: не Android, не iOS, не WASI.

Этот модуль не поддерживается на мобильных платформах или платформах WebAssembly.

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.

gdbm.clear(): Удалить все элементы из базы данных GDBM.

Добавлен в версии 3.13.

dbm.ndbm — Новый менеджер базы данных

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

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

Примечание

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

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

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

Доступность: не Android, не iOS, не WASI.

Этот модуль не поддерживается на мобильных платформах или платформах WebAssembly.

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.

ndbm.clear(): Удалить все элементы из базы данных NDBM.

Добавлена в версии 3.13.

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