dbm.md
1> **Источник:** https://python-all.ru/3.15/library/dbm.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `dbm` – Интерфейсы к Unix-«базам данных»89**Исходный код:** [Lib/dbm/\_\_init\_\_.py](https://python-all.ru/src/3.15/Lib/dbm/__init__.py)1011---1213`dbm` – это универсальный интерфейс к разновидностям базы данных DBM:1415- [`dbm.sqlite3`](https://python-all.ru/3.15/library/dbm.html#module-dbm.sqlite3)16- [`dbm.gnu`](https://python-all.ru/3.15/library/dbm.html#module-dbm.gnu)17- [`dbm.ndbm`](https://python-all.ru/3.15/library/dbm.html#module-dbm.ndbm)1819Если ни один из этих модулей не установлен, будет использована медленная, но простая реализация из модуля [`dbm.dumb`](https://python-all.ru/3.15/library/dbm.html#module-dbm.dumb). Существует [сторонний интерфейс](https://python-all.ru/3.15/library/dbm.html) к Oracle Berkeley DB.2021> **Примечание**22>23> Ни один из базовых модулей не будет автоматически уменьшать дисковое пространство, занимаемое файлом базы данных. Однако [`dbm.sqlite3`](https://python-all.ru/3.15/library/dbm.html#module-dbm.sqlite3), [`dbm.gnu`](https://python-all.ru/3.15/library/dbm.html#module-dbm.gnu) и [`dbm.dumb`](https://python-all.ru/3.15/library/dbm.html#module-dbm.dumb) предоставляют метод `reorganize()`, который можно использовать для этой цели.2425#### `exception dbm.error`2627Кортеж, содержащий исключения, которые могут быть возбуждены каждым из поддерживаемых модулей, причём уникальное исключение с именем [`dbm.error`](https://python-all.ru/3.15/library/dbm.html#dbm.error) является первым элементом – последнее используется, когда возбуждается `dbm.error`.2829#### `dbm.whichdb(filename)`3031Эта функция пытается определить, какой из нескольких доступных простых модулей баз данных – [`dbm.sqlite3`](https://python-all.ru/3.15/library/dbm.html#module-dbm.sqlite3), [`dbm.gnu`](https://python-all.ru/3.15/library/dbm.html#module-dbm.gnu), [`dbm.ndbm`](https://python-all.ru/3.15/library/dbm.html#module-dbm.ndbm) или [`dbm.dumb`](https://python-all.ru/3.15/library/dbm.html#module-dbm.dumb) – следует использовать для открытия данного файла.3233Возвращает одно из следующих значений:3435- `None`, если файл не может быть открыт, так как он нечитаем или не существует36- пустая строка (`''`), если формат файла не удаётся определить37- строка, содержащая имя требуемого модуля, например `'dbm.ndbm'` или `'dbm.gnu'`3839Изменено в версии 3.11: *filename* принимает [path-like object](https://python-all.ru/3.15/glossary.html#term-path-like-object).4041#### `dbm.open(file, flag='r', mode=0o666)`4243Открывает базу данных и возвращает соответствующий объект базы данных.4445**Параметры:**4647- **file** ([объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object)) –4849 Файл базы данных для открытия.5051 Если файл базы данных уже существует, для определения его типа используется функция [`whichdb()`](https://python-all.ru/3.15/library/dbm.html#dbm.whichdb), и применяется соответствующий модуль; если файл не существует, используется первый подмодуль из перечисленных выше, который можно импортировать.52- **flag** ([*str*](https://python-all.ru/3.15/library/stdtypes.html#str)) –5354 - `'r'` (по умолчанию): открывает существующую базу данных только для чтения.55 - `'w'`: Открыть существующую базу данных для чтения и записи.56 - `'c'`: открывает базу данных для чтения и записи, создавая её, если она не существует.57 - `'n'`: Всегда создавать новую пустую базу данных, открытую для чтения и записи.58- **mode** ([*int*](https://python-all.ru/3.15/library/functions.html#int)) – режим доступа к файлу Unix (по умолчанию: восьмеричное `0o666`), используется только при создании базы данных.5960Изменено в версии 3.11: *file* теперь принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object).6162Объект, возвращаемый [`open()`](https://python-all.ru/3.15/library/dbm.html#dbm.open), поддерживает базовую функциональность изменяемых [отображений](https://python-all.ru/3.15/glossary.html#term-mapping); ключи и соответствующие им значения могут сохраняться, извлекаться и удаляться, а также доступны итерация, оператор [`in`](https://python-all.ru/3.15/reference/expressions.html#in) и методы `keys()`, `get()`, `setdefault()` и `clear()`. Метод `keys()` возвращает список, а не объект представления. Метод `setdefault()` требует два аргумента.6364Ключи и значения всегда хранятся как [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes). Это означает, что при использовании строк они неявно преобразуются в кодировку по умолчанию перед сохранением.6566Эти объекты также поддерживают использование в операторе [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with), который автоматически закроет их по завершении.6768Изменено в версии 3.2: `get()` и `setdefault()` методы теперь доступны для всех бэкендов `dbm`.6970Изменено в версии 3.4: Добавлена встроенная поддержка протокола управления контекстом для объектов, возвращаемых [`open()`](https://python-all.ru/3.15/library/dbm.html#dbm.open).7172Изменено в версии 3.8: Удаление ключа из базы данных только для чтения теперь возбуждает исключение, специфичное для модуля базы данных, вместо [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError).7374Изменено в версии 3.13: `clear()` методы теперь доступны для всех `dbm` бэкендов.7576Следующий пример записывает несколько имен хостов и соответствующий заголовок, а затем выводит содержимое базы данных:7778```python79import dbm8081# Открыть базу данных, создав её при необходимости.82with dbm.open('cache', 'c') as db:8384 # Записать несколько значений.85 db[b'hello'] = b'there'86 db['www.python.org'] = 'Python Website'87 db['www.cnn.com'] = 'Cable News Network'8889 # Обратите внимание: теперь ключи считаются байтами.90 assert db[b'www.python.org'] == b'Python Website'91 # Обратите внимание, что теперь значение хранится в байтах.92 assert db['www.cnn.com'] == b'Cable News Network'9394 # Часто используемые методы интерфейса dict также работают.95 print(db.get('python.org', b'not present'))9697 # Сохранение нестрокового ключа или значения вызовет исключение (скорее всего,98 # TypeError).99 db['www.yahoo.com'] = 4100101# db автоматически закрывается при выходе из оператора with.102```103104> **См. также**105>106> **Модуль [`shelve`](https://python-all.ru/3.15/library/shelve.html#module-shelve)**107>108> Модуль персистентности, который хранит нестроковые данные.109110Отдельные подмодули описаны в следующих разделах.111112## `dbm.sqlite3` – SQLite-бэкенд для dbm113114Добавлено в версии 3.13.115116**Исходный код:** [Lib/dbm/sqlite3.py](https://python-all.ru/src/3.15/Lib/dbm/sqlite3.py)117118---119120Этот модуль использует модуль стандартной библиотеки [`sqlite3`](https://python-all.ru/3.15/library/sqlite3.html#module-sqlite3) для предоставления SQLite-бэкенда для модуля `dbm`. Файлы, созданные `dbm.sqlite3`, могут быть открыты в `sqlite3` или любом другом SQLite-браузере, включая SQLite CLI.121122[Доступность](https://python-all.ru/3.15/library/intro.html#availability): не WASI.123124Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.15/library/intro.html#wasm-availability).125126#### `dbm.sqlite3.open(filename, /, flag='r', mode=0o666)`127128Открывает SQLite-базу данных.129130**Параметры:**131132- **filename** ([path-like object](https://python-all.ru/3.15/glossary.html#term-path-like-object)) – путь к открываемой базе данных.133- **flag** ([*str*](https://python-all.ru/3.15/library/stdtypes.html#str)) –134135 - `'r'` (по умолчанию): открывает существующую базу данных только для чтения.136 - `'w'`: Открыть существующую базу данных для чтения и записи.137 - `'c'`: открывает базу данных для чтения и записи, создавая её, если она не существует.138 - `'n'`: Всегда создавать новую пустую базу данных, открытую для чтения и записи.139- **mode** – режим доступа к файлу Unix (по умолчанию: восьмеричное `0o666`), используется только при создании базы данных.140141Возвращаемый объект базы данных ведёт себя подобно изменяемому [mapping](https://python-all.ru/3.15/glossary.html#term-mapping), но метод `keys()` возвращает список, а метод `setdefault()` требует два аргумента. Он также поддерживает контекстный менеджер «closing» с помощью ключевого слова [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with).142143Также предоставляются следующие методы:144145#### `sqlite3.close()`146147Закрывает SQLite-базу данных.148149#### `sqlite3.reorganize()`150151Если вы произвели много удалений и хотите уменьшить занимаемое на диске пространство, этот метод переорганизует базу данных; в противном случае пространство, освобождённое при удалении, будет сохранено и повторно использовано при добавлении новых пар (ключ, значение).152153> **Примечание**154>155> При переорганизации требуется до двух раз больше свободного дискового пространства, чем размер исходной базы данных. Однако учтите, что этот коэффициент меняется для каждого подмодуля `dbm`.156157Добавлено в версии 3.15.158159## `dbm.gnu` – менеджер баз данных GNU160161**Исходный код:** [Lib/dbm/gnu.py](https://python-all.ru/src/3.15/Lib/dbm/gnu.py)162163---164165Модуль `dbm.gnu` предоставляет интерфейс к библиотеке GDBM, аналогичный модулю [`dbm.ndbm`](https://python-all.ru/3.15/library/dbm.html#module-dbm.ndbm), но с дополнительными возможностями, такими как устойчивость к сбоям.166167> **Примечание**168>169> Форматы файлов, созданные с помощью `dbm.gnu` и [`dbm.ndbm`](https://python-all.ru/3.15/library/dbm.html#module-dbm.ndbm), несовместимы и не могут использоваться взаимозаменяемо.170171[Доступность](https://python-all.ru/3.15/library/intro.html#availability): не Android, не iOS, не WASI.172173Этот модуль не поддерживается на [мобильных платформах](https://python-all.ru/3.15/library/intro.html#mobile-availability) или [платформах WebAssembly](https://python-all.ru/3.15/library/intro.html#wasm-availability).174175[Доступность](https://python-all.ru/3.15/library/intro.html#availability): Unix.176177#### `exception dbm.gnu.error`178179Возбуждается при ошибках, специфичных для `dbm.gnu`, таких как ошибки ввода-вывода. [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError) возбуждается для общих ошибок отображения, например, при указании неверного ключа.180181#### `dbm.gnu.open_flags`182183Строка символов, которую поддерживает параметр *flag* функции [`open()`](https://python-all.ru/3.15/library/dbm.html#dbm.gnu.open).184185#### `dbm.gnu.open(filename, flag='r', mode=0o666, /)`186187Открывает базу данных GDBM и возвращает объект `gdbm`.188189**Параметры:**190191- **filename** ([объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object)) – Файл базы данных для открытия.192- **flag** ([*str*](https://python-all.ru/3.15/library/stdtypes.html#str)) –193194 - `'r'` (по умолчанию): открывает существующую базу данных только для чтения.195 - `'w'`: Открыть существующую базу данных для чтения и записи.196 - `'c'`: открывает базу данных для чтения и записи, создавая её, если она не существует.197 - `'n'`: Всегда создавать новую пустую базу данных, открытую для чтения и записи.198199 К строке флага могут быть добавлены следующие дополнительные символы для управления способом открытия базы данных:200201 - `'f'`: Открыть базу данных в быстром режиме. Записи в базу данных не будут синхронизироваться.202 - `'s'`: Синхронизированный режим. Изменения в базе данных будут немедленно записаны в файл.203 - `'u'`: Не блокировать базу данных.204205 Не все флаги допустимы для всех версий GDBM. Список поддерживаемых символов флагов см. в члене [`open_flags`](https://python-all.ru/3.15/library/dbm.html#dbm.gnu.open_flags).206- **mode** ([*int*](https://python-all.ru/3.15/library/functions.html#int)) – режим доступа к файлу Unix (по умолчанию: восьмеричное `0o666`), используется только при создании базы данных.207208**Возбуждает:**209210[**error**](https://python-all.ru/3.15/library/dbm.html#dbm.gnu.error) – Если передан недопустимый аргумент *flag*.211212Изменено в версии 3.11: *filename* принимает [path-like object](https://python-all.ru/3.15/glossary.html#term-path-like-object).213214Объекты `gdbm` ведут себя как изменяемые [отображения](https://python-all.ru/3.15/glossary.html#term-mapping), но методы `items()`, `values()`, `pop()`, `popitem()`, и `update()` не поддерживаются, метод `keys()` возвращает список, а метод `setdefault()` требует два аргумента. Также поддерживается менеджер контекста «закрытие» через ключевое слово [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with).215216Изменено в версии 3.2: Добавлены методы `get()` и `setdefault()`.217218Изменено в версии 3.13: Добавлен метод `clear()`.219220Также предоставляются следующие методы:221222#### `gdbm.close()`223224Закрывает базу данных GDBM.225226#### `gdbm.firstkey()`227228С помощью этого метода и метода [`nextkey()`](https://python-all.ru/3.15/library/dbm.html#dbm.gnu.gdbm.nextkey) можно выполнять цикл по всем ключам базы данных. Обход упорядочен по внутренним хеш-значениям GDBM, а не по значениям ключей. Этот метод возвращает начальный ключ.229230#### `gdbm.nextkey(key)`231232Возвращает ключ, следующий за *key* при обходе. Следующий код выводит все ключи базы данных `db`, не создавая в памяти список, содержащий их все:233234```python235k = db.firstkey()236while k is not None:237 print(k)238 k = db.nextkey(k)239```240241#### `gdbm.reorganize()`242243Если вы выполнили много удалений и хотите уменьшить пространство, занимаемое файлом GDBM, эта процедура переорганизует базу данных. `gdbm` объекты не уменьшат размер файла базы данных иначе, чем с помощью такой переорганизации; в противном случае освобождённое пространство файла будет сохраняться и повторно использоваться при добавлении новых пар (ключ, значение).244245> **Примечание**246>247> При переорганизации требуется свободное дисковое пространство, равное размеру исходной базы данных. Однако учтите, что этот коэффициент меняется для каждого подмодуля `dbm`.248249#### `gdbm.sync()`250251Когда база данных открыта в быстром режиме, этот метод принудительно записывает на диск все незаписанные данные.252253## `dbm.ndbm` – Новый менеджер баз данных254255**Исходный код:** [Lib/dbm/ndbm.py](https://python-all.ru/src/3.15/Lib/dbm/ndbm.py)256257---258259Модуль `dbm.ndbm` предоставляет интерфейс к библиотеке NDBM. Этот модуль можно использовать как с «классическим» интерфейсом NDBM, так и с интерфейсом совместимости GDBM.260261> **Примечание**262>263> Форматы файлов, созданные с помощью [`dbm.gnu`](https://python-all.ru/3.15/library/dbm.html#module-dbm.gnu) и `dbm.ndbm`, несовместимы и не могут использоваться взаимозаменяемо.264265> **Предупреждение**266>267> Библиотека NDBM, поставляемая в составе macOS, имеет недокументированное ограничение на размер значений, что может привести к повреждению файлов базы данных при сохранении значений, превышающих этот лимит. Чтение таких повреждённых файлов может привести к жёсткому сбою (ошибке сегментации).268269[Доступность](https://python-all.ru/3.15/library/intro.html#availability): не Android, не iOS, не WASI.270271Этот модуль не поддерживается на [мобильных платформах](https://python-all.ru/3.15/library/intro.html#mobile-availability) или [платформах WebAssembly](https://python-all.ru/3.15/library/intro.html#wasm-availability).272273[Доступность](https://python-all.ru/3.15/library/intro.html#availability): Unix.274275#### `exception dbm.ndbm.error`276277Возникает при ошибках, специфичных для `dbm.ndbm`, например, при ошибках ввода-вывода. [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError) возникает при общих ошибках отображения, например, при указании неверного ключа.278279#### `dbm.ndbm.library`280281Имя используемой библиотеки реализации NDBM.282283#### `dbm.ndbm.open(filename, flag='r', mode=0o666, /)`284285Открывает базу данных NDBM и возвращает объект `ndbm`.286287**Параметры:**288289- **имя\_файла** ([объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object)) – базовое имя файла базы данных (без расширений `.dir` или `.pag`).290- **flag** ([*str*](https://python-all.ru/3.15/library/stdtypes.html#str)) –291292 - `'r'` (по умолчанию): открывает существующую базу данных только для чтения.293 - `'w'`: Открыть существующую базу данных для чтения и записи.294 - `'c'`: открывает базу данных для чтения и записи, создавая её, если она не существует.295 - `'n'`: Всегда создавать новую пустую базу данных, открытую для чтения и записи.296- **mode** ([*int*](https://python-all.ru/3.15/library/functions.html#int)) – режим доступа к файлу Unix (по умолчанию: восьмеричное `0o666`), используется только при создании базы данных.297298Изменено в версии 3.11: Принимает [объект, подобный пути](https://python-all.ru/3.15/glossary.html#term-path-like-object) для имени файла.299300Объекты `ndbm` ведут себя как изменяемые [отображения](https://python-all.ru/3.15/glossary.html#term-mapping), но методы `items()`, `values()`, `pop()`, `popitem()`, и `update()` не поддерживаются, метод `keys()` возвращает список, а метод `setdefault()` требует два аргумента. Также поддерживается менеджер контекста «закрытие» через ключевое слово [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with).301302Изменено в версии 3.2: Добавлены методы `get()` и `setdefault()`.303304Изменено в версии 3.13: Добавлен метод `clear()`.305306Также предоставляется следующий метод:307308#### `ndbm.close()`309310Закрывает базу данных NDBM.311312## `dbm.dumb` – переносимая реализация DBM313314**Исходный код:** [Lib/dbm/dumb.py](https://python-all.ru/src/3.15/Lib/dbm/dumb.py)315316> **Примечание**317>318> Модуль `dbm.dumb` предназначен в качестве запасного варианта для модуля `dbm`, когда более надёжный модуль недоступен. Модуль `dbm.dumb` не оптимизирован для скорости и используется не так интенсивно, как другие модули баз данных.319320---321322Модуль `dbm.dumb` предоставляет постоянный (persistent) интерфейс, подобный [`dict`](https://python-all.ru/3.15/library/stdtypes.html#dict), полностью написанный на Python. В отличие от других бэкендов `dbm`, таких как [`dbm.gnu`](https://python-all.ru/3.15/library/dbm.html#module-dbm.gnu), не требуется внешняя библиотека.323324Модуль `dbm.dumb` определяет следующее:325326#### `exception dbm.dumb.error`327328Возникает при ошибках, специфичных для `dbm.dumb`, например, при ошибках ввода-вывода. [`KeyError`](https://python-all.ru/3.15/library/exceptions.html#KeyError) возникает при общих ошибках отображения, например, при указании неверного ключа.329330#### `dbm.dumb.open(filename, flag='c', mode=0o666)`331332Открывает базу данных `dbm.dumb`.333334**Параметры:**335336- **filename** –337338 Базовое имя файла базы данных (без расширений). При создании новой базы данных появляются следующие файлы:339340 - `filename.dat`341 - `filename.dir`342- **flag** ([*str*](https://python-all.ru/3.15/library/stdtypes.html#str)) –343344 - `'r'`: Открыть существующую базу данных только для чтения.345 - `'w'`: Открыть существующую базу данных для чтения и записи.346 - `'c'` (по умолчанию): Открыть базу данных для чтения и записи, создавая её, если она не существует.347 - `'n'`: Всегда создавать новую пустую базу данных, открытую для чтения и записи.348- **mode** ([*int*](https://python-all.ru/3.15/library/functions.html#int)) – режим доступа к файлу Unix (по умолчанию: восьмеричное `0o666`), используется только при создании базы данных.349350> **Предупреждение**351>352> Интерпретатор Python может аварийно завершиться при загрузке базы данных со достаточно большой/сложной записью из-за ограничений глубины стека в компиляторе AST Python.353354> **Предупреждение**355>356> `dbm.dumb` не поддерживает одновременный доступ на чтение и запись. (Множественные одновременные чтения безопасны.) Когда программа открыла базу данных для записи, никакая другая программа не должна открывать её ни для чтения, ни для записи.357358Изменено в версии 3.5: `open()` всегда создаёт новую базу данных, когда *flag* равен `'n'`.359360Изменено в версии 3.8: База данных открывается только для чтения, если *flag* равен `'r'`. База данных не создаётся, если она не существует, когда *flag* равен `'r'` или `'w'`.361362Изменено в версии 3.11: *filename* принимает [path-like object](https://python-all.ru/3.15/glossary.html#term-path-like-object).363364Возвращаемый объект базы данных ведёт себя подобно изменяемому [отображению](https://python-all.ru/3.15/glossary.html#term-mapping), но методы `keys()` и `items()` возвращают списки, а метод `setdefault()` требует два аргумента. Он также поддерживает контекстный менеджер «closing» через ключевое слово [`with`](https://python-all.ru/3.15/reference/compound_stmts.html#with).365366Также предоставляются следующие методы:367368#### `dumbdbm.close()`369370Закрыть базу данных.371372#### `dumbdbm.reorganize()`373374Если вы произвели много удалений и хотите уменьшить занимаемое на диске пространство, этот метод переорганизует базу данных; в противном случае пространство, освобождённое при удалении, не будет повторно использовано.375376> **Примечание**377>378> При переорганизации не требуется дополнительного свободного дискового пространства. Однако учтите, что этот коэффициент меняется для каждого подмодуля `dbm`.379380Добавлено в версии 3.15.381382#### `dumbdbm.sync()`383384Синхронизировать каталог на диске и файлы данных. Этот метод вызывается методом [`shelve.Shelf.sync()`](https://python-all.ru/3.15/library/shelve.html#shelve.Shelf.sync).385