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

Источник: Lib/dbm/__init__.py

dbm - это общий интерфейс для вариантов базы данных DBM:

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

Availability: не WASI, не iOS.

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

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

  • flag (str) –

    • 'r' (по умолчанию): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

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

Объект, возвращаемый 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.

См.также

Модуль shelve

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

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

dbm.sqlite3 — Бэкэнд SQLite для dbm

Added in version 3.13.

Источник: Lib/dbm/sqlite3.py

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

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

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

Параметры:

  • filename (path-like object) – Путь к базе данных, которую необходимо открыть.

  • flag (str) –

    • 'r' (по умолчанию): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode – Режим доступа к файлу Unix (по умолчанию: восьмеричный 0o666), используется только при создании базы данных.

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 (path-like object) – Файл базы данных, который необходимо открыть.

  • flag (str) –

    • 'r' (по умолчанию): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

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

    • 'f': Открыть базу данных в быстром режиме. Записи в базу данных не будут синхронизироваться.

    • 's': Синхронизированный режим. Изменения в базе данных будут немедленно записываться в файл.

    • 'u': Не блокировать базу данных.

    Не все флаги действительны для всех версий GDBM. Список поддерживаемых символов флагов см. в члене open_flags.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

Исключение:

error – Если передан неверный аргумент flag.

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

dbm.gnu.open_flags

Строка символов, которые поддерживает параметр flag в open().

Объекты gdbm ведут себя аналогично mappings, но методы 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.

Added in version 3.13.

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

Источник: Lib/dbm/ndbm.py

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

Примечание

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

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

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

exception dbm.ndbm.error

Возбуждается при dbm.ndbm-специфических ошибках, таких как ошибки ввода-вывода. KeyError вызывается при общих ошибках отображения, например при указании неправильного ключа.

dbm.ndbm.library

Имя используемой библиотеки реализации NDBM.

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

Открывает базу данных NDBM и возвращает объект ndbm.

Параметры:

  • filename (path-like object) – Основное имя файла базы данных (без расширений .dir или .pag).

  • flag (str) –

    • 'r' (по умолчанию): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

Объекты ndbm ведут себя аналогично mappings, но методы items() и values() не поддерживаются. Также предоставляются следующие методы:

Изменено в версии 3.11: Принимает path-like object в качестве имени файла.

ndbm.close()

Закройте базу данных NDBM.

ndbm.clear()

Удалите все элементы из базы данных NDBM.

Added in version 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. Возвращаемый объект базы данных ведет себя аналогично объекту mapping, а также предоставляет методы sync() и close().

Параметры:

  • filename – Основное имя файла базы данных (без расширений). При создании новой базы данных создаются следующие файлы: - filename.dat - filename.dir

  • flag (str) –

    • 'r': Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c' (по умолчанию): Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

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

Возможно аварийное завершение работы интерпретатора Python при загрузке базы данных с достаточно большой/сложной записью из-за ограничений на глубину стека в AST-компиляторе Python.

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

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

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

В дополнение к методам, предоставляемым классом collections.abc.MutableMapping, предоставляются следующие методы:

dumbdbm.sync()

Синхронизация каталога на диске и файлов данных. Этот метод вызывается методом Shelve.sync().

dumbdbm.close()

Закройте базу данных.