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(), поддерживает основные возможности изменяемых отображений: ключи и соответствующие им значения можно сохранять, получать и удалять. Также доступны итерация, оператор in и методы keys(), get(), setdefault() и clear(). Метод keys() возвращает список, а не объект-представление. Метод setdefault() требует два аргумента.

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

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

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

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

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

Изменено в версии 3.13: Методы clear() теперь доступны во всех серверных модулях dbm.

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

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.

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

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

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

Открывает базу данных SQLite.

Параметры:

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

Возвращённый объект базы данных ведёт себя подобно изменяемому отображению, но метод keys() возвращает список, а метод setdefault() требует два аргумента. Кроме того, он поддерживает менеджер контекста, который закрывает объект, при использовании ключевого слова with.

Также предоставляется следующий метод:

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

`dbm.gnu` — менеджер баз данных GNU

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

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

Примечание

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

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

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

Доступность: Unix.

exception dbm.gnu.error: Возбуждается при ошибках, характерных для dbm.gnu, например при ошибках ввода-вывода. При общих ошибках отображения, например при указании неверного ключа, возбуждается KeyError.

dbm.gnu.open_flags: Строка символов, поддерживаемых параметром flag функции open().

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 принимает объект, подобный пути.

Объекты gdbm ведут себя подобно изменяемым отображениям, но методы items(), values(), pop(), popitem() и update() не поддерживаются, метод keys() возвращает список, а метод setdefault() требует два аргумента. Кроме того, они поддерживают менеджер контекста, который закрывает объект, при использовании ключевого слова with.

Изменено в версии 3.2: Добавлены методы get() и setdefault().

Изменено в версии 3.13: Добавлен метод clear().

Также предоставляются следующие методы:

gdbm.close(): Закрывает базу данных 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(): Если база данных была открыта в быстром режиме, этот метод принудительно записывает на диск все данные, которые ещё не были сохранены.

`dbm.ndbm` — New Database Manager

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

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

Примечание

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

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

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

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

Доступность: Unix.

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); используется только при создании базы данных.

Изменено в версии 3.11: Для filename принимается объект, подобный пути.

Объекты ndbm ведут себя подобно изменяемым отображениям, но методы items(), values(), pop(), popitem() и update() не поддерживаются, метод keys() возвращает список, а метод setdefault() требует два аргумента. Кроме того, они поддерживают менеджер контекста, который закрывает объект, при использовании ключевого слова with.

Изменено в версии 3.2: Добавлены методы get() и setdefault().

Изменено в версии 3.13: Добавлен метод clear().

Также предоставляется следующий метод:

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.

Параметры:

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 принимает объект, подобный пути.

Возвращённый объект базы данных ведёт себя подобно изменяемому отображению, но методы keys() и items() возвращают списки, а метод setdefault() требует два аргумента. Кроме того, объект поддерживает менеджер контекста, который закрывает его, при использовании ключевого слова with.

Также предоставляются следующие методы:

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

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

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

dbm.sqlite3 — серверная часть SQLite для dbm

dbm.gnu — менеджер баз данных GNU

dbm.ndbm — New Database Manager

dbm.dumb — переносимая реализация DBM

`dbm.sqlite3` — серверная часть SQLite для dbm

`dbm.gnu` — менеджер баз данных GNU

`dbm.ndbm` — New Database Manager

`dbm.dumb` — переносимая реализация DBM