:mod:`gdbm` --- GNU による dbm の再実装
=======================================

.. module:: gdbm
   :platform: Unix
   :synopsis: GNU による dbm の再実装。

.. note::
   .. The :mod:`gdbm` module has been renamed to :mod:`dbm.gnu` in Python 3.0.  The
      :term:`2to3` tool will automatically adapt imports when converting your
      sources to 3.0.

   :mod:`gdbm` モジュールはPython 3.0で :mod:`dbm.gnu` にリネームされました。
   :term:`2to3` ツールがimportを自動的に修正します。


.. index:: module: dbm

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

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

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


.. exception:: error

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


.. function:: open(filename, [flag, [mode]])

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

   オプションの *flag* は、

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

   .. The following additional characters may be appended to the flag to control
      how the database is opened:

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

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

   .. Not all flags are valid for all versions of ``gdbm``.  The module constant
      :const:`open_flags` is a string of supported flag characters.  The exception
      :exc:`error` is raised if an invalid flag is specified.

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

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

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


.. function:: firstkey()

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


.. function:: nextkey(key)

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

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


.. function:: reorganize()

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


.. function:: sync()

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


.. seealso::

   Module :mod:`anydbm`
      ``dbm`` 形式のデータベースへの汎用インタフェース。

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

