11.11. "bsddb" --- Berkeley DB ライブラリへのインタフェース
***********************************************************

バージョン 2.6 で非推奨: "bsddb" モジュールは、 Python 3 で削除されま
した。

"bsddb" モジュールは Berkeley DB ライブラリへのインタフェースを提供し
ます。ユーザは適当な "open()" 呼び出しを使うことで、ハッシュ、B-Tree、
またはレコードに基づくデータベースファイルを生成することができます。
bsddb オブジェクトは辞書と大体同じように振る舞います。しかし、キー及び
値は文字列でなければならないので、他のオブジェクトをキーとして使ったり
、他の種のオブジェクトを記録したい場合、それらのデータを何らかの方法で
直列化しなければなりません。これには通常 "marshal.dumps()" や
"pickle.dumps()" が使われます。

"bsddb" モジュールは、バージョン 4.0 から 4.7 までの間の Berkeley DB
ライブラリを必要とします。

参考:

  http://www.jcea.es/programacion/pybsddb.htm
     Python Berkeley DBインターフェース "bsddb.db" のドキュメント。イ
     ンターフェースは、Berkeley DB 4.x が提供しているオブジェクト指向
     インターフェースとほぼ同じインターフェースとなっています。

  http://www.oracle.com/database/berkeley-db/
     The Berkeley DB library.

より新しい DB である DBEnv や DBSequence オブジェクトのインターフェー
スも "bsddb.db" モジュールで使用できます。これは、上の URL で説明され
ている Berkeley DB C API によりマッチしています。 "bsddb.db" API が提
供する追加機能には、チューニングやトランザクション、ログ出力、マルチプ
ロセス環境でのデータベースへの同時アクセスなどがあります。

以下では、従来のbsddbモジュールと互換性のある、古いインターフェースを
解説しています。Python 2.5 以降、このインターフェースはマルチスレッド
に対応しています。マルチスレッドを使用する場合は "bsddb.db" API を推奨
します。こちらのほうがスレッドをよりうまく制御できるからです。

"bsddb" モジュールでは、適切な形式の Berkeley DB ファイルにアクセスす
るオブジェクトを生成する以下の関数を定義しています。各関数の最初の二つ
の引数は同じです。可搬性のために、ほとんどのインスタンスでは最初の二つ
の引数だけが使われているはずです。

bsddb.hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])

   *filename* と名づけられたハッシュ形式のファイルを開きます。
   *filename* に "None" を指定することで、ディスクに保存するつもりがな
   いファイルを生成することもできます。オプションの *flag* には、ファ
   イルを開くためのモードを指定します。このモードは "'r'" (読み出し専
   用), "'w'" (読み書き可能)、 "'c'" (読み書き可能 - 必要ならファイル
   を生成…これがデフォルトです) または "'n'" (読み書き可能 - ファイル
   長を 0 に切り詰め)、にすることができます。他の引数はほとんど使われ
   ることはなく、下位レベルの "dbopen()" 関数に渡されるだけです。他の
   引数の使い方およびその解釈については Berkeley DB のドキュメントを読
   んで下さい。

bsddb.btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])

   *filename* と名づけられた B-Tree 形式のファイルを開きます。
   *filename* に "None" を指定することで、ディスクに保存するつもりがな
   いファイルを生成することもできます。オプションの *flag* には、ファ
   イルを開くためのモードを指定します。このモードは "'r'" (読み出し専
   用)、 "'w'" (読み書き可能)、 "'c'" (読み書き可能 - 必要ならファイル
   を生成…これがデフォルトです)、または "'n'" (読み書き可能 - ファイル
   長を 0 に切り詰め)、にすることができます。他の引数はほとんど使われ
   ることはなく、下位レベルの "dbopen()" 関数に渡されるだけです。他の
   引数の使い方およびその解釈については Berkeley DB のドキュメントを読
   んで下さい。

bsddb.rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])

   *filename* と名づけられた DB レコード形式のファイルを開きます、
   *filename* に "None" を指定することで、ディスクに保存するつもりがな
   いファイルを生成することもできます、オプションの *flag* には、ファ
   イルを開くためのモードを指定します、このモードは "'r'" (読み出し専
   用), "'w'" (読み書き可能)、 "'c'" (読み書き可能 - 必要ならファイル
   を生成…これがデフォルトです)、または "'n'" (読み書き可能 - ファイル
   長を 0 に切り詰め)、にすることができます。他の引数はほとんど使われ
   ることはなく、下位レベルの "dbopen()" 関数に渡されるだけです、他の
   引数の使い方およびその解釈については Berkeley DB のドキュメントを読
   んで下さい。

注釈: 2.3 以降の Unix 版 Python には、 "bsddb185" モジュールが存在す
  る場合 があります。このモジュールは古い Berkeley DB 1.85 データベー
  スライブ ラリを持つシステムをサポートするため *だけ* に存在していま
  す。新規に 開発するコードでは、 "bsddb185" を直接使用しないで下さい
  。このモジュ ールは Python 3 で削除されます。必要であれば、PyPI にあ
  るかもしれま せん。

参考:

  "dbhash" モジュール
     "bsddb" への DBM 形式のインタフェース


11.11.1. ハッシュ、BTree、およびレコードオブジェクト
====================================================

インスタンス化したハッシュ、B-Tree, およびレコードオブジェクトは辞書型
と同じメソッドをサポートするようになります。加えて、以下に列挙したメソ
ッドもサポートします。

バージョン 2.3.1 で変更: 辞書型メソッドを追加しました.

bsddbobject.close()

   データベースの背後にあるファイルを閉じます。オブジェクトはアクセス
   できなくなります。これらのオブジェクトには "oepn()" メソッドがない
   ため、再度ファイルを開くためには、新たな "bsddb" モジュールを開く関
   数を呼び出さなくてはなりません。

bsddbobject.keys()

   DB ファイルに収められているキーからなるリストを返します。リスト内の
   キーの順番は決まっておらず、あてにはなりません。特に、異なるファイ
   ル形式の DB 間では返されるリストの順番が異なります。

bsddbobject.has_key(key)

   引数 *key* が DB ファイルにキーとして含まれている場合 "1" を返しま
   す。

bsddbobject.set_location(key)

   カーソルを *key* で示される要素に移動し、キー及び値からなるタプルを
   返します。("bopen()" を使って開かれる) B-Tree データベースでは、
   *key* が実際にはデータベース内に存在しなかった場合、カーソルは並び
   順が *key* の次に来るような要素を指し、その場所のキー及び値が返され
   ます。他のデータベースでは、データベース中に *key* が見つからなかっ
   た場合 "KeyError" が送出されます。

bsddbobject.first()

   カーソルを DB ファイルの最初の要素に設定し、その要素を返します。
   B-Tree データベースの場合を除き、ファイル中のキーの順番は決まってい
   ません。データベースが空の場合、このメソッドは "bsddb.error" を発生
   させます。

bsddbobject.next()

   カーソルを DB ファイルの次の要素に設定し、その要素を返します。
   B-Tree データベースの場合を除き、ファイル中のキーの順番は決まってい
   ません。

bsddbobject.previous()

   カーソルを DB ファイルの直前の要素に設定し、その要素を返します。
   B-Tree データベースの場合を除き、ファイル中のキーの順番は決まってい
   ません。 ("hashopen()" で開かれるような) ハッシュ表データベースでは
   サポートされていません。

bsddbobject.last()

   カーソルを DB ファイルの最後の要素に設定し、その要素を返します。フ
   ァイル中のキーの順番は決まっていません。 ("hashopen()" で開かれるよ
   うな) ハッシュ表データベースではサポートされていません。データベー
   スが空の場合、このメソッドは "bsddb.error" を発生させます。

bsddbobject.sync()

   ディスク上のファイルをデータベースに同期させます。

以下はプログラム例です:

   >>> import bsddb
   >>> db = bsddb.btopen('spam.db', 'c')
   >>> for i in range(10): db['%d'%i] = '%d'% (i*i)
   ...
   >>> db['3']
   '9'
   >>> db.keys()
   ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
   >>> db.first()
   ('0', '0')
   >>> db.next()
   ('1', '1')
   >>> db.last()
   ('9', '81')
   >>> db.set_location('2')
   ('2', '4')
   >>> db.previous()
   ('1', '1')
   >>> for k, v in db.iteritems():
   ...     print k, v
   0 0
   1 1
   2 4
   3 9
   4 16
   5 25
   6 36
   7 49
   8 64
   9 81
   >>> '8' in db
   True
   >>> db.sync()
   0
