:mod:`dbhash` --- BSD データベースライブラリへの DBM 形式のインタフェース
=========================================================================

.. module:: dbhash
   :synopsis: BSD データベースライブラリへの DBM 形式のインタフェース。
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

.. deprecated:: 2.6
   :mod:`dbhash` モジュールは Python 3.0 では削除されます。


.. index:: module: bsddb

:mod:`dbhash` モジュールでは BSD ``db`` ライブラリを使ってデータベースを開くための関数を提供します。このモジュールは、 DBM 形式
のデータベースへのアクセスを提供する他の Python データベースモジュールのインタフェースをそのまま反映しています。 :mod:`dbhash`
を使うには :mod:`bsddb` モジュールが必要です。

このモジュールでは一つの例外と一つの関数を提供しています:


.. exception:: error

   :exc:`KeyError` 以外のデータベースのエラーで送出されます。 :exc:`bsddb.error` と同じ意味です。


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

   データベース ``db`` を開き、データベースオブジェクトを返します。引数 *path* はデータベースファイルの名前です。

   .. The *flag* argument can be:

   *flag* 引数は、次のいずれかの値になります。

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

   .. For platforms on which the BSD ``db`` library supports locking, an ``'l'``
      can be appended to indicate that locking should be used.

   BSD ``db`` ライブラリがロックをサポートしているプラットフォームでは、
   flag に ``'l'`` を追加して、ロックを利用することを指定できます。

   オプションの *mode* 引数は、新たにデータベースを作成しなければならないときにデータベースファイルに設定すべき Unix ファイル権限
   ビットを表すために使われます; この値はプロセスの現在の umask 値でマスクされます。


.. seealso::

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

   Module :mod:`bsddb`
      BSD ``db`` ライブラリへの低レベルインタフェース。

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


.. _dbhash-objects:

データベースオブジェクト
------------------------

:func:`open` によって返されるデータベースオブジェクトは、全ての DBM 形式データベースやマップ型オブジェクトで共通のメソッドを
提供します。それら標準のメソッドに加え、dbhash では以下のメソッドが利用可能です。


.. method:: dbhash.first()

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


.. method:: dbhash.last()

   データベース探索における最後のキー/値を返します。逆順探索を開始する際に使うことができます; :meth:`previous` を参照してください。


.. method:: dbhash.next()

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

      print db.first()
      for i in xrange(1, len(db)):
          print db.next()


.. method:: dbhash.previous()

   データベースの逆方向探索において、手前に来るキー/値のペアを返します。 :meth:`last` と併せて、逆方向の探索に用いられます。


.. method:: dbhash.sync()

   このメソッドはディスクにまだ書き込まれていないデータを全て書き込ませます。

