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, включая CLI 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.

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 — Новый менеджер баз данных

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

Изменено в версии 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().