dbm --- Unix "データベース" へのインターフェース

ソースコード: Lib/dbm/__init__.py

---

dbm は DBM データベースの各種実装に対する汎用インターフェースです:

• dbm.sqlite3

• dbm.gnu

• dbm.ndbm

これらのモジュールがどれもインストールされていない場合は、低速ながら単純な dbm.dumb モジュールの実装を使います。 Oracle Berkeley DB には サードパーティー製インターフェース があります。

注釈

内部で使うモジュールはどれも、データベースファイルが使うディスク領域を自動では縮小しません。 ただし dbm.sqlite3、dbm.gnu、dbm.dumb には、領域の縮小に使える reorganize() メソッドがあります。

exception dbm.error

サポートされているモジュールそれぞれによって送出される可能性のある例外を含むタプル。これにはユニークな例外があり、最初の要素として同じく dbm.error という名前の例外が含まれます --- 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() が返すオブジェクトは、ミュータブルな マッピング の基本的な機能に対応しています。 キーとそれに対応する値の保存、取得、削除に加え、イテレーション、in 演算子、keys()、get()、setdefault()、clear() メソッドを利用できます。 keys() メソッドはビューオブジェクトではなくリストを返します。 setdefault() メソッドには引数が 2 つ必要です。

キーと値は常に bytes として保存されます。 そのため文字列を使うと、保存前にデフォルトのエンコーディングで暗黙に変換されます。 受け付ける型について詳しくは キーと値の型 を参照してください。

これらのオブジェクトは、 with 文での使用にも対応しています。with 文を使用した場合、終了時に自動的に閉じられます。

バージョン 3.2 で変更: すべての dbm バックエンドで get() と setdefault() メソッドが使えるようになりました。

バージョン 3.4 で変更: open() が返すオブジェクトに、コンテキスト管理プロトコルのネイティブサポートを追加しました。

バージョン 3.8 で変更: 読み取り専用データベースからキーを削除すると、KeyError ではなくデータベースモジュール固有の例外を送出するようになりました。

バージョン 3.13 で変更: すべての dbm バックエンドで clear() メソッドが使えるようになりました。

キーと値の型

キーと値として受け付ける型はバックエンドによって異なります。 以下で特に断らない限り、キーと値は同じように扱われます。

• 従来のバックエンド:

  • dbm.gnu と dbm.ndbm: str と bytes オブジェクトを受け付けます。

  • dbm.dumb: str と bytes オブジェクトを受け付けます。 bytearray は値として使えますが、キーとしては使えません。

• SQLite バックエンド (dbm.sqlite3): str、bytes、int、float、bool、bytearray、memoryview、array.array オブジェクトを受け付けます。

保存形式:

キーと値はすべて bytes オブジェクトとしてデータベースに保存されます。 取得時は、保存したときの型にかかわらず常にバイト列が返されます。

型変換の例:

• db['key'] = 'string' は b'string' として保存されます。

• db['key'] = bytearray(b'data') は b'data' (dbm.dumb と dbm.sqlite3 のみ) として保存されます。

• db['key'] = 42 は b'42' (dbm.sqlite3 のみ) として保存されます。

• db['key'] = 3.14 は b'3.14' (dbm.sqlite3 のみ) として保存されます。

• db['key'] = True は b'1' (dbm.sqlite3 のみ) として保存されます。

• db['key'] = False は b'0' (dbm.sqlite3 のみ) として保存されます。

• db['key'] = memoryview(b'data') は b'data' (dbm.sqlite3 のみ) として保存されます。

• db['key'] = array.array('i', [1, 2, 3]) はバイト列 (例えばリトルエンディアンでは b'\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00') (dbm.sqlite3 のみ) として保存されます。

以下の例ではホスト名と対応するタイトルをいくつか記録し、データベースの内容を出力します:

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'))

    # 文字列以外のキーや値を保存するときの動作はバックエンドによって異なります:
    # - 従来のバックエンド (ndbm, gnu, dumb) は TypeError を送出します
    # - sqlite3 バックエンドは受け付けてバイト列に変換します
    db['www.yahoo.com'] = 4

# with 文を抜けると db は自動的に閉じられます。

参考

shelve モジュール

非文字列データを記録する永続化モジュール。

個々のサブモジュールは以降の節で説明されます。

dbm.sqlite3 --- dbm の SQLite バックエンド

Added in version 3.13.

ソースコード: Lib/dbm/sqlite3.py

---

このモジュールは標準ライブラリの sqlite3 モジュールを使い、dbm モジュール用の SQLite バックエンドを提供します。 したがって dbm.sqlite3 で作成したファイルは sqlite3 や、SQLite CLI を含む他の SQLite ブラウザーで開けます。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォーム を見てください。

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

SQLite データベースを開きます。

パラメータ:

• 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 アクセスモード (デフォルトは 8 進数の 0o666)。 データベースを新規作成する必要がある場合にのみ使います。

返されるデータベースオブジェクトはミュータブルな mapping に似ていますが、keys() メソッドはリストを返し、setdefault() メソッドには引数が 2 つ必要です。 また with キーワードによって、終了時にデータベースを閉じるコンテキストマネージャとして使えます。

次のメソッドも提供します:

sqlite3.close()

SQLite データベースを閉じます。

sqlite3.reorganize()

多数の削除を行った後、ディスク上の使用領域を縮小したい場合に、このメソッドでデータベースを再編成できます。 再編成しない場合、削除されたファイル領域はそのまま残り、新しい (key, value) ペアを追加したときに再利用されます。

注釈

再編成中は、元のデータベースのサイズの最大 2 倍の空きディスク領域が必要です。 ただし、この倍率は dbm のサブモジュールごとに異なります。

Added in version 3.15.

dbm.gnu --- GNU データベースマネージャ

ソースコード: Lib/dbm/gnu.py

---

dbm.gnu モジュールは GDBM ライブラリへのインターフェースを提供します。 dbm.ndbm モジュールに似ていますが、クラッシュへの耐性などの機能が追加されています。

注釈

dbm.gnu と dbm.ndbm が作成するファイル形式には互換性がなく、相互に利用できません。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォーム をサポートしません。

利用可能な環境: Unix.

exception dbm.gnu.error

I/O エラーなど、dbm.gnu 固有のエラーで送出されます。 不正なキーの指定など、一般的なマッピングのエラーでは KeyError を送出します。

dbm.gnu.open_flags

open() の flag パラメーターが受け付ける文字を並べた文字列。

dbm.gnu.GDBM_VERSION_INFO

A named tuple containing the three components of the GDBM library version that was used for building the module: major, minor, and patch. All values are integers. The components can also be accessed by name, so dbm.gnu.GDBM_VERSION_INFO[0] is equivalent to dbm.gnu.GDBM_VERSION_INFO.major and so on. This may be different from the GDBM library actually used at runtime, which is available as gdbm_version_info.

Added in version 3.16.

dbm.gnu.gdbm_version_info

A named tuple containing the version of the GDBM library actually loaded by the interpreter, with the same fields as GDBM_VERSION_INFO.

Added in version 3.16.

dbm.gnu.gdbm_version

The release string of the GDBM library actually loaded by the interpreter, like 'GDBM version 1.26. 30/07/2025'.

Added in version 3.16.

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 を渡せるようになりました。

gdbm オブジェクトはミュータブルな マッピング に似ていますが、items()、values()、pop()、popitem()、update() メソッドはサポートしていません。 keys() メソッドはリストを返し、setdefault() メソッドには引数が 2 つ必要です。 また 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 オブジェクトは、この再編成以外の方法ではデータベースファイルの長さを縮めません。 再編成しない場合、削除されたファイル領域はそのまま残り、新しい (key, value) ペアを追加したときに再利用されます。

注釈

再編成中は、元のデータベースと同じサイズの空きディスク領域が必要になる場合があります。 ただし、この倍率は dbm のサブモジュールごとに異なります。

gdbm.sync()

データベースが高速モードで開かれていた場合、このメソッドはディスクにまだ書き込まれていないデータを全て書き込ませます。

dbm.ndbm --- New Database Manager

ソースコード: Lib/dbm/ndbm.py

---

dbm.ndbm モジュールは NDBM ライブラリへのインターフェースを提供します。 このモジュールは「従来の」NDBM インターフェースでも GDBM の互換インターフェースでも利用できます。

注釈

dbm.gnu と dbm.ndbm が作成するファイル形式には互換性がなく、相互に利用できません。

警告

macOS に付属する NDBM ライブラリには、値のサイズに関する文書化されていない制限があります。 この制限より大きな値を保存すると、データベースファイルが破損することがあります。 破損したファイルを読み取ると、プログラムがクラッシュ (セグメンテーションフォールト) することがあります。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォーム をサポートしません。

利用可能な環境: Unix.

exception dbm.ndbm.error

I/O エラーなど、dbm.ndbm 固有のエラーで送出されます。 不正なキーの指定など、一般的なマッピングのエラーでは KeyError を送出します。

dbm.ndbm.library

Name of the NDBM implementation library used: 'GNU gdbm', 'Berkeley DB' or 'ndbm'.

バージョン 3.16 で変更: The value is 'ndbm' for a classic NDBM library. It was 'GNU gdbm' before.

dbm.ndbm.GDBM_VERSION_INFO

dbm.ndbm.gdbm_version_info

dbm.ndbm.gdbm_version

Information about the GDBM library in use, with the same meaning as the constants of the same names in dbm.gnu. Only available if library is 'GNU gdbm'.

Added in version 3.16.

dbm.ndbm.BDB_VERSION

The version string of the Berkeley DB library that was used for building the module, like 'Berkeley DB 5.3.28: (September  9, 2013)'. This may be different from the Berkeley DB library actually used at runtime, which is available as bdb_version. Only available if library is 'Berkeley DB'.

Added in version 3.16.

dbm.ndbm.bdb_version

The version string of the Berkeley DB library actually loaded by the interpreter. Only available if library is 'Berkeley DB'.

Added in version 3.16.

dbm.ndbm.BDB_VERSION_INFO

A named tuple containing the three components of the Berkeley DB library version that was used for building the module: major, minor, and patch. All values are integers. The components can also be accessed by name, so dbm.ndbm.BDB_VERSION_INFO[0] is equivalent to dbm.ndbm.BDB_VERSION_INFO.major and so on. This may be different from the Berkeley DB library actually used at runtime, which is available as bdb_version_info. Only available if library is 'Berkeley DB'.

Added in version 3.16.

dbm.ndbm.bdb_version_info

A named tuple containing the version of the Berkeley DB library actually loaded by the interpreter, with the same fields as BDB_VERSION_INFO. Only available if library is 'Berkeley DB'.

Added in version 3.16.

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.

バージョン 3.11 で変更: ファイル名として path-like object を受け付けるようになりました。

ndbm オブジェクトはミュータブルな マッピング に似ていますが、items()、values()、pop()、popitem()、update() メソッドはサポートしていません。 keys() メソッドはリストを返し、setdefault() メソッドには引数が 2 つ必要です。 また 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 モジュールは、すべて Python で書かれた、永続的な dict に似たインターフェースを提供します。 dbm.gnu などの他の dbm バックエンドとは異なり、外部ライブラリは不要です。

dbm.dumb モジュールは以下を定義しています:

exception dbm.dumb.error

I/O エラーなど、dbm.dumb 固有のエラーで送出されます。 不正なキーの指定など、一般的なマッピングのエラーでは KeyError を送出します。

dbm.dumb.open(filename, flag='c', mode=0o666)

dbm.dumb データベースを開きます。

パラメータ:

• filename -- データベースファイルのベース名 (拡張子は含めません)。 新しいデータベースを作ると、次のファイルが作成されます:

• 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 の抽象構文木コンパイラのスタックの深さの限界を越えるせいで、 Python インタプリタをクラッシュさせることができます。

警告

dbm.dumb は読み書きの同時アクセスをサポートしていません (複数の読み取りアクセスを同時に行うのは安全です)。 あるプログラムが書き込み用にデータベースを開いている間は、他のプログラムでそのデータベースを読み取り用にも書き込み用にも開かないでください。

バージョン 3.5 で変更: flag が 'n' の場合、open() は常に新しいデータベースを作成するようになりました。

バージョン 3.8 で変更: flag が 'r' の場合は読み取り専用でデータベースを開きます。 flag が 'r' または 'w' でデータベースが存在しない場合、新規作成しなくなりました。

バージョン 3.11 で変更: filename に path-like object を渡せるようになりました。

返されるデータベースオブジェクトはミュータブルな mapping に似ていますが、keys() と items() メソッドはリストを返し、setdefault() メソッドには引数が 2 つ必要です。 また with キーワードによって、終了時にデータベースを閉じるコンテキストマネージャとして使えます。

次のメソッドも提供します:

dumbdbm.close()

データベースを閉じます。

dumbdbm.reorganize()

多数の削除を行った後、ディスク上の使用領域を縮小したい場合に、このメソッドでデータベースを再編成できます。 再編成しない場合、削除されたファイル領域は再利用されません。

注釈

再編成中も追加の空きディスク領域は不要です。 ただし、この条件は dbm のサブモジュールごとに異なります。

Added in version 3.15.

dumbdbm.sync()

ディスク上のディレクトリファイルとデータファイルを同期します。 このメソッドは shelve.Shelf.sync() メソッドから呼び出されます。