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

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

`dbm` は DBM データベースのいくつかの種類 ( `dbm.gnu` または `dbm.ndbm` ) に対する汎用的なインタフェースです。これらのモジュールのどれもインストールされていなければ、モジュール `dbm.dumb` に含まれる低速だが単純な実装が使用されます。Oracle Berkeley DB に対する サードパーティのインタフェース があります。

exception `dbm.``error`

  サポートされているモジュールそれぞれによって送出される可能性のある例外を含むタプル。これにはユニークな例外があり、最初の要素として同じく `dbm.error` という名前の例外が含まれます --- `dbm.error` が送出される場合、後者(訳注:タプルの `dbm.error` ではなく例外 `dbm.error`)が使用されます。

`dbm.``whichdb`(filename)

  この関数は、与えられたファイルを開くために、利用可能ないくつかの単純なデータベースモジュール --- `dbm.gnu`, `dbm.ndbm`, `dbm.dumb` --- のどれを使用すべきか推測を試みます。

  次の値のうち１つを返します: ファイルが読み取れないか存在しないために開くことができない場合は `None`; ファイルのフォーマットを推測することができない場合は空文字列 (`''`); それ以外は `'dbm.ndbm'` や `'dbm.gnu'` のような、必要なモジュール名を含む文字列。

`dbm.``open`(file, flag='r', mode=0o666)

  データベースファイル file を開いて対応するオブジェクトを返します。

  データベースファイルが既に存在する場合、その種類を決定するために `whichdb()` 関数が使用され、適切なモジュールが使用されます; データベースファイルが存在しない場合、上記のリストの中でインポート可能な最初のモジュールが使用されます。

  オプションの flag は:

  値 | 意味
  --- | ---
  `'r'` | 既存のデータベースを読み込み専用で開く (デフォルト)
  `'w'` | 既存のデータベースを読み書き用に開く
  `'c'` | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
  `'n'` | 常に新たに読み書き用の新規のデータベースを作成する

  オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の `0o666` です (この値は現在有効な umask で修飾されます)。

`open()` によって返されたオブジェクトは辞書とほとんど同じ機能をサポートします; キーとそれに対応付けられた値を記憶し、取り出し、削除することができ、 `in` 演算子や `keys()` メソッド、また `get()` や `setdefault()` を使うことができます。

バージョン 3.2 で変更: `get()` と `setdefault()` がすべてのデータベースモジュールで利用できるようになりました。

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

キーと値は常に byte 列として格納されます。これは、文字列が使用された場合は格納される前に暗黙的にデフォルトエンコーディングに変換されるということを意味します。

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

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

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

    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.gnu` --- GNU による dbm 拡張

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

このモジュールは `dbm` モジュールによく似ていますが、GNU ライブラリ `gdbm` を使っていくつかの追加機能を提供しています。 `dbm.gnu` と `dbm.ndbm` では生成されるファイル形式に互換性がないので注意してください。

`dbm.gnu` モジュールでは GNU DBM ライブラリへのインタフェースを提供します。 `dbm.gnu.gdbm` オブジェクトはキーと値が必ず保存の前にバイト列に変換されることを除き、マップ型 (辞書型) と同じように動作します。 `gdbm` オブジェクトに対して `print()` を適用してもキーや値を印字することはなく、 `items()` 及び `values()` メソッドはサポートされていません。

exception `dbm.gnu.``error`

  I/O エラーのような `dbm.gnu` 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては `KeyError` が送出されます。

`dbm.gnu.``open`(filename[, flag[, mode]])

  `gdbm` データベースを開いて `gdbm` オブジェクトを返します。 filename 引数はデータベースファイルの名前です。

  オプションの flag は:

  値 | 意味
  --- | ---
  `'r'` | 既存のデータベースを読み込み専用で開く (デフォルト)
  `'w'` | 既存のデータベースを読み書き用に開く
  `'c'` | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
  `'n'` | 常に新たに読み書き用の新規のデータベースを作成する

  以下の追加の文字を flag に追加して、データベースの開きかたを制御することができます:

  値 | 意味
  --- | ---
  `'f'` | データベースを高速モードで開きます。書き込みが同期されません。
  `'s'` | 同期モード。データベースへの変更がすぐにファイルに書き込まれます。
  `'u'` | データベースをロックしません。

  全てのバージョンの `gdbm` で全てのフラグが有効とは限りません。モジュール定数 `open_flags` はサポートされているフラグ文字からなる文字列です。無効なフラグが指定された場合、例外 `error` が送出されます。

  オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の `0o666` です。

  辞書型形式のメソッドに加えて、`gdbm` オブジェクトには以下のメソッドがあります:

  `gdbm.``firstkey`()

    このメソッドと `nextkey()` メソッドを使って、データベースの全てのキーにわたってループ処理を行うことができます。探索は `gdbm` の内部ハッシュ値の順番に行われ、キーの値に順に並んでいるとは限りません。このメソッドは最初のキーを返します。

  `gdbm.``nextkey`(key)

    データベースの順方向探索において、key よりも後に来るキーを返します。以下のコードはデータベース `db` について、キー全てを含むリストをメモリ上に生成することなく全てのキーを出力します:

        k = db.firstkey()
        while k != None:
            print(k)
            k = db.nextkey(k)

  `gdbm.``reorganize`()

    大量の削除を実行した後、`gdbm` ファイルの占めるスペースを削減したい場合、このルーチンはデータベースを再組織化します。この再組織化を使用する方法以外に `gdbm` オブジェクトがデータベースファイルの大きさを短くすることはありません。サイズを縮小しない場合、削除された部分のファイルスペースは保持され、新たな (キー、値の) ペアが追加される際に再利用されます。

  `gdbm.``sync`()

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

  `gdbm.``close`()

    `gdbm` データベースをクローズします。

## `dbm.ndbm` --- ndbm に基づくインタフェース

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

`dbm.ndbm` モジュールはUnixの"(n)dbm"ライブラリのインタフェースを提供します。 dbmオブジェクトは、キーと値が必ずバイト列である以外は辞書オブジェクトのようなふるまいをします。 print関数などで `dbm` オブジェクトを出力してもキーと値は出力されません。また、 `items()` と `values()` メソッドはサポートされません。

このモジュールは、GNU GDBM互換インタフェースを持った "クラシックな" ndbmインタフェースを使うことができます。 Unix上のビルド時に configure スクリプトで適切なヘッダファイルが割り当られます。

exception `dbm.ndbm.``error`

  I/O エラーのような `dbm.ndbm` 特有のエラーで送出されます。誤ったキーの指定のように、一般的なマップ型のエラーに対しては `KeyError` が送出されます。

`dbm.ndbm.``library`

  `ndbm` が使用している実装ライブラリ名です。

`dbm.ndbm.``open`(filename[, flag[, mode]])

  dbmデータベースを開いて `ndbm` オブジェクトを返します。引数 filename はデータベースのファイル名を指定します。 (拡張子 `.dir` や `.pag` は付けません)。

  オプションの flag は以下の値のいずれかです:

  値 | 意味
  --- | ---
  `'r'` | 既存のデータベースを読み込み専用で開く (デフォルト)
  `'w'` | 既存のデータベースを読み書き用に開く
  `'c'` | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
  `'n'` | 常に新たに読み書き用の新規のデータベースを作成する

  オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の `0o666` です (この値は現在有効な umask で修飾されます)。

  辞書型様のメソッドに加えて、`ndbm` オブジェクトには以下のメソッドがあります。

  `ndbm.``close`()

    `ndbm` データベースをクローズします。

## `dbm.dumb` --- 可搬性のある DBM 実装

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

注釈

`dbm.dumb` モジュールは、 `dbm` が頑健なモジュールを他に見つけることができなかった際の最後の手段とされています。 `dbm.dumb` モジュールは速度を重視して書かれているわけではなく、他のデータベースモジュールのように重い使い方をするためのものではありません。

`dbm.dumb` モジュールは永続性辞書に類似したインタフェースを提供し、全て Python で書かれています。 `dbm.gnu` のようなモジュールと異なり、外部ライブラリは必要ありません。他の永続性マップ型のように、キーおよび値は常にバイト列として保存されます。

このモジュールは以下を定義します:

exception `dbm.dumb.``error`

  I/O エラーのような `dbm.dumb` 特有のエラーの際に送出されます。不正なキーを指定したときのような、一般的な対応付けエラーの際には `KeyError` が送出されます。

`dbm.dumb.``open`(filename[, flag[, mode]])

  `dumbdbm` データベースを開き、 dubmdbm オブジェクトを返します。 filename 引数はデータベースファイル名の雛型 (特定の拡張子をもたないもの) です。dumbdbm データベースが生成される際、 `.dat` および `.dir` の拡張子を持ったファイルが生成されます。

  オプションの flag は:

  値 | 意味
  --- | ---
  `'r'` | 既存のデータベースを読み込み専用で開く (デフォルト)
  `'w'` | 既存のデータベースを読み書き用に開く
  `'c'` | データベースを読み書き用に開く。ただし存在しない場合には新たに作成する
  `'n'` | 常に新たに読み書き用の新規のデータベースを作成する

  オプションの mode 引数は、新たにデータベースを作成しなければならない場合に使われる Unix のファイルモードです。標準の値は 8 進数の `0o666` です (この値は現在有効な umask で修飾されます)。

  警告

  十分に大きかったり複雑だったりするエントリーのあるデータベースを読み込んでいるときに、 Python の抽象構文木コンパイラのスタックの深さの限界を越えるせいで、 Python インタプリタをクラッシュさせることができます。

  バージョン 3.5 で変更: フラグに値 `'n'` を与えると、 `open()` が常に新しいデータベースを作成するようになりました。

  バージョン 3.8 で変更: フラグ `'r'` で開いたデータベースは読み出し専用となりました。 データベースが存在していない場合にフラグ `'r'` と `'w'` で開いても、データベースを作成しなくなりました。

  `collections.abc.MutableMapping` クラスによって提供されるメソッドに加えて、 `dumbdbm` オブジェクトは以下のメソッドを提供します:

  `dumbdbm.``sync`()

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

  `dumbdbm.``close`()

    `dumbdbm` データベースをクローズします。