"dbm" --- Unix "データベース" へのインタフェース
************************************************

**ソースコード:** Lib/dbm/__init__.py

======================================================================

"dbm" は DBM データベースのいくつかの種類 ( "dbm.gnu" または
"dbm.ndbm" ) に対する汎用的なインタフェースです。これらのモジュールの
どれもインストールされていなければ、モジュール "dbm.dumb" に含まれる低
速だが単純な実装が使用されます。Oracle Berkeley DB に対する サードパー
ティのインタフェース があります。

exception dbm.error

   サポートされているモジュールそれぞれによって送出される可能性のある
   例外を含むタプル。これにはユニークな例外があり、最初の要素として同
   じく "dbm.error" という名前の例外が含まれます --- "dbm.error" が送
   出される場合、後者(訳注:タプルの "dbm.error" ではなく例外
   "dbm.error")が使用されます。

dbm.whichdb(filename)

   この関数は、与えられたファイルを開くために、利用可能ないくつかの単
   純なデータベースモジュール --- "dbm.gnu", "dbm.ndbm", "dbm.dumb"
   --- のどれを使用すべきか推測を試みます。

   次の値のうち１つを返します: ファイルが読み取れないか存在しないため
   に開くことができない場合は "None"; ファイルのフォーマットを推測する
   ことができない場合は空文字列 ("''"); それ以外は "'dbm.ndbm'" や
   "'dbm.gnu'" のような、必要なモジュール名を含む文字列。

dbm.open(file, flag='r', mode=0o666)

   データベースファイル *file* を開いて対応するオブジェクトを返します
   。

   データベースファイルが既に存在する場合、その種類を決定するために
   "whichdb()" 関数が使用され、適切なモジュールが使用されます; データ
   ベースファイルが存在しない場合、上記のリストの中でインポート可能な
   最初のモジュールが使用されます。

   オプションの *flag* は:

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

   オプションの *mode* 引数は、新たにデータベースを作成しなければなら
   ない場合に使われる Unix のファイルモードです。標準の値は 8 進数の
   "0o666" です (この値は現在有効な umask で修飾されます)。

"open()" によって返されたオブジェクトは辞書とほとんど同じ機能をサポー
トします; キーとそれに対応付けられた値を記憶し、取り出し、削除すること
ができ、 "in" 演算子や "keys()" メソッド、また "get()" や
"setdefault()" を使うことができます。

バージョン 3.2 で変更: "get()" と "setdefault()" がすべてのデータベー
スモジュールで利用できるようになりました。

バージョン 3.8 で変更: 読み出し専用のデータベースからキーを削除しよう
とすると、 "KeyError" ではなくデータベースモジュール専用のエラーが送出
されるようになりました。

キーと値は常に byte 列として格納されます。これは、文字列が使用された場
合は格納される前に暗黙的にデフォルトエンコーディングに変換されるという
ことを意味します。

これらのオブジェクトは、 "with" 文での使用にも対応しています。with 文
を使用した場合、終了時に自動的に閉じられます。

バージョン 3.4 で変更: "open()" が返すオブジェクトに対するコンテキスト
管理のプロトコルがネイティブにサポートされました。

以下の例ではホスト名と対応するタイトルをいくつか記録し、データベースの
内容を出力します:

   import dbm

   # Open database, creating it if necessary.
   with dbm.open('cache', 'c') as db:

       # Record some values
       db[b'hello'] = b'there'
       db['www.python.org'] = 'Python Website'
       db['www.cnn.com'] = 'Cable News Network'

       # Note that the keys are considered bytes now.
       assert db[b'www.python.org'] == b'Python Website'
       # Notice how the value is now in bytes.
       assert db['www.cnn.com'] == b'Cable News Network'

       # Often-used methods of the dict interface work too.
       print(db.get('python.org', b'not present'))

       # Storing a non-string key or value will raise an exception (most
       # likely a TypeError).
       db['www.yahoo.com'] = 4

   # db is automatically closed when leaving the with statement.

参考:

  "shelve" モジュール
     非文字列データを記録する永続化モジュール。

個々のサブモジュールは以降の節で説明されます。


"dbm.gnu" --- GNU による dbm 拡張
=================================

**ソースコード:** Lib/dbm/gnu.py

======================================================================

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

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

exception dbm.gnu.error

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

dbm.gnu.open(filename[, flag[, mode]])

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

   オプションの *flag* は:

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

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

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

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

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

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


"dbm.ndbm" --- ndbm に基づくインタフェース
==========================================

**ソースコード:** Lib/dbm/ndbm.py

======================================================================

"dbm.ndbm" モジュールはUnixの"(n)dbm"ライブラリのインタフェースを提供
します。 dbmオブジェクトは、キーと値が必ずバイト列である以外は辞書オブ
ジェクトのようなふるまいをします。 print関数などで "dbm" オブジェクト
を出力してもキーと値は出力されません。また、 "items()" と "values()"
メソッドはサポートされません。

このモジュールは、GNU GDBM互換インタフェースを持った "クラシックな"
ndbmインタフェースを使うことができます。 Unix上のビルド時に
**configure** スクリプトで適切なヘッダファイルが割り当られます。

exception dbm.ndbm.error

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

dbm.ndbm.library

   "ndbm" が使用している実装ライブラリ名です。

dbm.ndbm.open(filename[, flag[, mode]])

   dbmデータベースを開いて "ndbm" オブジェクトを返します。引数
   *filename* はデータベースのファイル名を指定します。 (拡張子 ".dir"
   や ".pag" は付けません)。

   オプションの *flag* は以下の値のいずれかです:

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

   オプションの *mode* 引数は、新たにデータベースを作成しなければなら
   ない場合に使われる Unix のファイルモードです。標準の値は 8 進数の
   "0o666" です (この値は現在有効な umask で修飾されます)。

   辞書型様のメソッドに加えて、"ndbm" オブジェクトには以下のメソッドが
   あります。

   ndbm.close()

      "ndbm" データベースをクローズします。


"dbm.dumb" --- 可搬性のある DBM 実装
====================================

**ソースコード:** Lib/dbm/dumb.py

注釈:

  "dbm.dumb" モジュールは、 "dbm" が頑健なモジュールを他に見つけること
  ができなかった際の最後の手段とされています。 "dbm.dumb" モジュールは
  速度を重視して書かれているわけではなく、他のデータベースモジュールの
  ように重い使い方をするためのものではありません。

======================================================================

"dbm.dumb" モジュールは永続性辞書に類似したインタフェースを提供し、全
て Python で書かれています。 "dbm.gnu" のようなモジュールと異なり、外
部ライブラリは必要ありません。他の永続性マップ型のように、キーおよび値
は常にバイト列として保存されます。

このモジュールは以下を定義します:

exception dbm.dumb.error

   I/O エラーのような "dbm.dumb" 特有のエラーの際に送出されます。不正
   なキーを指定したときのような、一般的な対応付けエラーの際には
   "KeyError" が送出されます。

dbm.dumb.open(filename[, flag[, mode]])

   "dumbdbm" データベースを開き、 dubmdbm オブジェクトを返します。
   *filename* 引数はデータベースファイル名の雛型 (特定の拡張子をもたな
   いもの) です。dumbdbm データベースが生成される際、 ".dat" および
   ".dir" の拡張子を持ったファイルが生成されます。

   オプションの *flag* は:

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

   オプションの *mode* 引数は、新たにデータベースを作成しなければなら
   ない場合に使われる Unix のファイルモードです。標準の値は 8 進数の
   "0o666" です (この値は現在有効な umask で修飾されます)。

   警告:

     十分に大きかったり複雑だったりするエントリーのあるデータベースを
     読み込んでいるときに、 Python の抽象構文木コンパイラのスタックの
     深さの限界を越えるせいで、 Python インタプリタをクラッシュさせる
     ことができます。

   バージョン 3.5 で変更: フラグに値 "'n'" を与えると、 "open()" が常
   に新しいデータベースを作成するようになりました。

   バージョン 3.8 で変更: フラグ "'r'" で開いたデータベースは読み出し
   専用となりました。 データベースが存在していない場合にフラグ "'r'"
   と "'w'" で開いても、データベースを作成しなくなりました。

   "collections.abc.MutableMapping" クラスによって提供されるメソッドに
   加えて、 "dumbdbm" オブジェクトは以下のメソッドを提供します:

   dumbdbm.sync()

      ディスク上の辞書とデータファイルを同期します。このメソッドは
      "Shelve.sync()"  メソッドから呼び出されます。

   dumbdbm.close()

      "dumbdbm" データベースをクローズします。
