Содержание страницы

`dbm` – Интерфейсы к Unix-«базам данных»¶dbm – Interfaces to Unix “databases”

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

dbm – это универсальный интерфейс к разновидностям базы данных DBM:

dbm.sqlite3
dbm.gnudbm.gnu – GNU database manager
dbm.ndbmdbm.ndbm – New Database Manager

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

Примечание

Ни один из базовых модулей не будет автоматически уменьшать дисковое пространство, занимаемое файлом базы данных. Однако dbm.sqlite3, dbm.gnu и dbm.dumb предоставляют метод reorganize(), который можно использовать для этой цели.

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 принимает path-like object.

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

# Открыть базу данных, создав её при необходимости.
with dbm.open('cache', 'c') as db:

    # Записать несколько значений.
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Обратите внимание: теперь ключи считаются байтами.
    assert db[b'www.python.org'] == b'Python Website'
    # Обратите внимание, что теперь значение хранится в байтах.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Часто используемые методы интерфейса dict также работают.
    print(db.get('python.org', b'not present'))

    # Сохранение нестрокового ключа или значения вызовет исключение (скорее всего,
    # TypeError).
    db['www.yahoo.com'] = 4

# db автоматически закрывается при выходе из оператора with.

См. также

Модуль shelve: Модуль персистентности, который хранит нестроковые данные.

Отдельные подмодули описаны в следующих разделах.

`dbm.sqlite3` – SQLite-бэкенд для dbm¶dbm.sqlite3 – SQLite backend for 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-базу данных.

Параметры:

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

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

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

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

sqlite3.reorganize()¶: Если вы произвели много удалений и хотите уменьшить занимаемое на диске пространство, этот метод переорганизует базу данных; в противном случае пространство, освобождённое при удалении, будет сохранено и повторно использовано при добавлении новых пар (ключ, значение).

Примечание

При переорганизации требуется до двух раз больше свободного дискового пространства, чем размер исходной базы данных. Однако учтите, что этот коэффициент меняется для каждого подмодуля dbm.

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

`dbm.gnu` – менеджер баз данных GNU¶dbm.gnu – GNU database manager

Исходный код: 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 принимает path-like object.

Объекты 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 объекты не уменьшат размер файла базы данных иначе, чем с помощью такой переорганизации; в противном случае освобождённое пространство файла будет сохраняться и повторно использоваться при добавлении новых пар (ключ, значение).

Примечание

При переорганизации требуется свободное дисковое пространство, равное размеру исходной базы данных. Однако учтите, что этот коэффициент меняется для каждого подмодуля dbm.

gdbm.sync()¶: Когда база данных открыта в быстром режиме, этот метод принудительно записывает на диск все незаписанные данные.

`dbm.ndbm` – Новый менеджер баз данных¶dbm.ndbm – New Database Manager

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

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

Примечание

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

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

Библиотека 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.

Параметры:

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

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

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

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

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

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

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

`dbm.dumb` – переносимая реализация DBM¶dbm.dumb – Portable DBM implementation

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

Примечание

Модуль dbm.dumb предназначен в качестве запасного варианта для модуля dbm, когда более надёжный модуль недоступен. Модуль dbm.dumb не оптимизирован для скорости и используется не так интенсивно, как другие модули баз данных.

Модуль dbm.dumb предоставляет постоянный (persistent) интерфейс, подобный 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.

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

dbm.dumb не поддерживает одновременный доступ на чтение и запись. (Множественные одновременные чтения безопасны.) Когда программа открыла базу данных для записи, никакая другая программа не должна открывать её ни для чтения, ни для записи.

Изменено в версии 3.5: open() всегда создаёт новую базу данных, когда flag равен 'n'.

Изменено в версии 3.8: База данных открывается только для чтения, если flag равен 'r'. База данных не создаётся, если она не существует, когда flag равен 'r' или 'w'.

Изменено в версии 3.11: filename принимает path-like object.

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

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

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

dumbdbm.reorganize()¶: Если вы произвели много удалений и хотите уменьшить занимаемое на диске пространство, этот метод переорганизует базу данных; в противном случае пространство, освобождённое при удалении, не будет повторно использовано.

Примечание

При переорганизации не требуется дополнительного свободного дискового пространства. Однако учтите, что этот коэффициент меняется для каждого подмодуля dbm.

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

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

dbm – Интерфейсы к Unix-«базам данных»¶dbm – Interfaces to Unix “databases”

dbm.sqlite3 – SQLite-бэкенд для dbm¶dbm.sqlite3 – SQLite backend for dbm

dbm.gnu – менеджер баз данных GNU¶dbm.gnu – GNU database manager

dbm.ndbm – Новый менеджер баз данных¶dbm.ndbm – New Database Manager

dbm.dumb – переносимая реализация DBM¶dbm.dumb – Portable DBM implementation

`dbm` – Интерфейсы к Unix-«базам данных»¶dbm – Interfaces to Unix “databases”

`dbm.sqlite3` – SQLite-бэкенд для dbm¶dbm.sqlite3 – SQLite backend for dbm

`dbm.gnu` – менеджер баз данных GNU¶dbm.gnu – GNU database manager

`dbm.ndbm` – Новый менеджер баз данных¶dbm.ndbm – New Database Manager

`dbm.dumb` – переносимая реализация DBM¶dbm.dumb – Portable DBM implementation