
:mod:`bsddb` --- Berkeley DB ライブラリへのインタフェース
=========================================================

.. module:: bsddb
   :synopsis: Berkeley DB ライブラリへのインタフェース
.. sectionauthor:: Skip Montanaro <skip@pobox.com>

.. deprecated:: 2.6
   :mod:`bsddb` モジュールは、 Python 3.0 では削除されるので、非推奨です。


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

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


.. seealso::

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

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

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

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

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


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

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


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

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


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

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

.. note::

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


.. seealso::

   Module :mod:`dbhash`
      :mod:`bsddb` への DBM 形式のインタフェース


.. _bsddb-objects:

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

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

.. versionchanged:: 2.3.1
   辞書型メソッドを追加しました.


.. method:: bsddbobject.close()

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


.. method:: bsddbobject.keys()

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


.. method:: bsddbobject.has_key(key)

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


.. method:: bsddbobject.set_location(key)

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


.. method:: bsddbobject.first()

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


.. method:: bsddbobject.next()

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


.. method:: bsddbobject.previous()

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


.. method:: bsddbobject.last()

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


.. method:: bsddbobject.sync()

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

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

   >>> import bsddb
   >>> db = bsddb.btopen('/tmp/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

