11.9. "gdbm" --- GNU による dbm の再実装
****************************************

注釈: "gdbm" モジュールは、Python 3 では "dbm.gnu" にリネームされま
  した。 *2to3* ツールが自動的にソースコードの import を修正します。

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

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

このモジュールでは以下の定数および関数を定義しています:

exception gdbm.error

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

gdbm.open(filename[, flag[, mode]])

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

   オプションの *flag* は:

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

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

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

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

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

辞書型形式のメソッドに加えて、"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" データベースをクローズします。

参考:

  "anydbm" モジュール
     "dbm" スタイルの汎用的なインタフェース

  "whichdb" モジュール
     既存のデータベースがどの形式のデータベースか判定するユーティリテ
     ィモジュール。
