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

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

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

"dbm" は DBM データベースの各種実装に対する汎用インターフェースです:

* "dbm.sqlite3"

* "dbm.gnu"

* "dbm.ndbm"

これらのモジュールがどれもインストールされていない場合は、低速ながら単
純な "dbm.dumb" モジュールの実装を使います。 Oracle Berkeley DB には
サードパーティー製インターフェース があります。

注釈:

  内部で使うモジュールはどれも、データベースファイルが使うディスク領域
  を自動では縮小しません。 ただし "dbm.sqlite3"、"dbm.gnu"、"dbm.dumb"
  には、領域の縮小に使える "reorganize()" メソッドがあります。

exception dbm.error

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

dbm.whichdb(filename)

   指定されたファイルを開くために、利用可能な単純なデータベースモジュ
   ール "dbm.sqlite3"、"dbm.gnu"、"dbm.ndbm"、"dbm.dumb" のどれを使う
   べきか推測します。

   次のいずれかの値を返します:

   * ファイルが読み取り不能か存在しないため開けない場合は "None"

   * ファイル形式を推測できない場合は空文字列 ("''")

   * "'dbm.ndbm'" や "'dbm.gnu'" など、必要なモジュール名の文字列

   バージョン 3.11 で変更: *filename* に *path-like object* を渡せるよ
   うになりました。

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

   データベースを開き、対応するデータベースオブジェクトを返します。

   パラメータ:
      * **file** (*path-like object*) -- 開くデータベースファイル。 デ
        ータベースファイルがすでに存在する場合は "whichdb()" 関数で種
        類を判定し、適切なモジュールを使います。 存在しない場合は、上
        に挙げたサブモジュールのうち最初にインポートできたものを使いま
        す。

      * **flag** (*str*) --

        * "'r'" (デフォルト): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   バージョン 3.11 で変更: *file* に *path-like object* を渡せるように
   なりました。

"open()" が返すオブジェクトは、ミュータブルな *マッピング* の基本的な
機能に対応しています。 キーとそれに対応する値の保存、取得、削除に加え
、イテレーション、"in" 演算子、"keys()"、"get()"、"setdefault()"、
"clear()" メソッドを利用できます。 "keys()" メソッドはビューオブジェク
トではなくリストを返します。 "setdefault()" メソッドには引数が 2 つ必
要です。

キーと値は常に "bytes" として保存されます。 そのため文字列を使うと、保
存前にデフォルトのエンコーディングで暗黙に変換されます。 受け付ける型
について詳しくは キーと値の型 を参照してください。

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

バージョン 3.2 で変更: すべての "dbm" バックエンドで "get()" と
"setdefault()" メソッドが使えるようになりました。

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

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

バージョン 3.13 で変更: すべての "dbm" バックエンドで "clear()" メソッ
ドが使えるようになりました。


キーと値の型
============

キーと値として受け付ける型はバックエンドによって異なります。 以下で特
に断らない限り、キーと値は同じように扱われます。

* **従来のバックエンド:**

  * "dbm.gnu" と "dbm.ndbm": "str" と "bytes" オブジェクトを受け付けま
    す。

  * "dbm.dumb": "str" と "bytes" オブジェクトを受け付けます。
    "bytearray" は値として使えますが、キーとしては使えません。

* **SQLite バックエンド** ("dbm.sqlite3"): "str"、"bytes"、"int"、
  "float"、"bool"、"bytearray"、"memoryview"、"array.array" オブジェク
  トを受け付けます。

**保存形式:**

キーと値はすべて "bytes" オブジェクトとしてデータベースに保存されます
。 取得時は、保存したときの型にかかわらず常にバイト列が返されます。

**型変換の例:**

* "db['key'] = 'string'" は "b'string'" として保存されます。

* "db['key'] = bytearray(b'data')" は "b'data'" ("dbm.dumb" と
  "dbm.sqlite3" のみ) として保存されます。

* "db['key'] = 42" は "b'42'" ("dbm.sqlite3" のみ) として保存されます
  。

* "db['key'] = 3.14" は "b'3.14'" ("dbm.sqlite3" のみ) として保存され
  ます。

* "db['key'] = True" は "b'1'" ("dbm.sqlite3" のみ) として保存されます
  。

* "db['key'] = False" は "b'0'" ("dbm.sqlite3" のみ) として保存されま
  す。

* "db['key'] = memoryview(b'data')" は "b'data'" ("dbm.sqlite3" のみ)
  として保存されます。

* "db['key'] = array.array('i', [1, 2, 3])" はバイト列 (例えばリトルエ
  ンディアンでは
  "b'\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'")
  ("dbm.sqlite3" のみ) として保存されます。

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

   import dbm

   # データベースを開きます。必要なら作成します。
   with dbm.open('cache', 'c') as db:

       # 値をいくつか記録します
       db[b'hello'] = b'there'
       db['www.python.org'] = 'Python Website'
       db['www.cnn.com'] = 'Cable News Network'

       # キーはバイト列として扱われます。
       assert db[b'www.python.org'] == b'Python Website'
       # 値もバイト列になっています。
       assert db['www.cnn.com'] == b'Cable News Network'

       # dict インターフェースのよく使うメソッドも利用できます。
       print(db.get('python.org', b'not present'))

       # 文字列以外のキーや値を保存するときの動作はバックエンドによって異なります:
       # - 従来のバックエンド (ndbm, gnu, dumb) は TypeError を送出します
       # - sqlite3 バックエンドは受け付けてバイト列に変換します
       db['www.yahoo.com'] = 4

   # with 文を抜けると db は自動的に閉じられます。

参考:

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

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


"dbm.sqlite3" --- dbm の SQLite バックエンド
============================================

Added in version 3.13.

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

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

このモジュールは標準ライブラリの "sqlite3" モジュールを使い、"dbm" モ
ジュール用の SQLite バックエンドを提供します。 したがって
"dbm.sqlite3" で作成したファイルは "sqlite3" や、SQLite CLI を含む他の
SQLite ブラウザーで開けます。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。

dbm.sqlite3.open(filename, /, flag='r', mode=0o666)

   SQLite データベースを開きます。

   パラメータ:
      * **filename** (*path-like object*) -- 開くデータベースのパス。

      * **flag** (*str*) --

        * "'r'" (デフォルト): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** -- ファイルの Unix アクセスモード (デフォルトは 8 進
        数の "0o666")。 データベースを新規作成する必要がある場合にのみ
        使います。

   返されるデータベースオブジェクトはミュータブルな *mapping* に似てい
   ますが、"keys()" メソッドはリストを返し、"setdefault()" メソッドに
   は引数が 2 つ必要です。 また "with" キーワードによって、終了時にデ
   ータベースを閉じるコンテキストマネージャとして使えます。

   次のメソッドも提供します:

   sqlite3.close()

      SQLite データベースを閉じます。

   sqlite3.reorganize()

      多数の削除を行った後、ディスク上の使用領域を縮小したい場合に、こ
      のメソッドでデータベースを再編成できます。 再編成しない場合、削
      除されたファイル領域はそのまま残り、新しい (key, value) ペアを追
      加したときに再利用されます。

      注釈:

        再編成中は、元のデータベースのサイズの最大 2 倍の空きディスク
        領域が必要です。 ただし、この倍率は "dbm" のサブモジュールごと
        に異なります。

      Added in version 3.15.


"dbm.gnu" --- GNU データベースマネージャ
========================================

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

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

"dbm.gnu" モジュールは GDBM (GNU dbm) ライブラリへのインターフェースを
提供します。 "dbm.ndbm" モジュールに似ていますが、クラッシュへの耐性な
どの機能が追加されています。

注釈:

  "dbm.gnu" と "dbm.ndbm" が作成するファイル形式には互換性がなく、相互
  に利用できません。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォー
ム をサポートしません。

利用可能な環境: Unix.

exception dbm.gnu.error

   I/O エラーなど、"dbm.gnu" 固有のエラーで送出されます。 不正なキーの
   指定など、一般的なマッピングのエラーでは "KeyError" を送出します。

dbm.gnu.open_flags

   "open()" の *flag* パラメーターが受け付ける文字を並べた文字列。

dbm.gnu.open(filename, flag='r', mode=0o666, /)

   GDBM データベースを開き、"gdbm" オブジェクトを返します。

   パラメータ:
      * **filename** (*path-like object*) -- 開くデータベースファイル
        。

      * **flag** (*str*) --

        * "'r'" (デフォルト): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

        次の文字を追加して、データベースを開く方法を制御できます:

        * "'f'": 高速モードでデータベースを開きます。 データベースへの
          書き込みは同期されません。

        * "'s'": 同期モード。 データベースへの変更は直ちにファイルに書
          き込まれます。

        * "'u'": データベースをロックしません。

        すべてのフラグが GDBM のすべてのバージョンで有効とは限りません
        。 サポートするフラグ文字の一覧は "open_flags" メンバーを参照
        してください。

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   例外:
      **error** -- 不正な *flag* 引数が渡された場合。

   バージョン 3.11 で変更: *filename* に *path-like object* を渡せるよ
   うになりました。

   "gdbm" オブジェクトはミュータブルな *マッピング* に似ていますが、
   "items()"、"values()"、"pop()"、"popitem()"、"update()" メソッドは
   サポートしていません。 "keys()" メソッドはリストを返し、
   "setdefault()" メソッドには引数が 2 つ必要です。 また "with" キーワ
   ードによって、終了時にデータベースを閉じるコンテキストマネージャと
   して使えます。

   バージョン 3.2 で変更: "get()" と "setdefault()" メソッドを追加しま
   した。

   バージョン 3.13 で変更: "clear()" メソッドを追加しました。

   次のメソッドも提供します:

   gdbm.close()

      GDBM データベースを閉じます。

   gdbm.firstkey()

      このメソッドと "nextkey()" メソッドを使って、データベースのすべ
      てのキーを順にたどれます。 走査の順序は GDBM 内部のハッシュ値に
      基づき、キーの値の順には並びません。 このメソッドは最初のキーを
      返します。

   gdbm.nextkey(key)

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

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

   gdbm.reorganize()

      多数の削除を行った後、GDBM ファイルの使用領域を縮小したい場合に
      、このルーチンでデータベースを再編成できます。 "gdbm" オブジェク
      トは、この再編成以外の方法ではデータベースファイルの長さを縮めま
      せん。 再編成しない場合、削除されたファイル領域はそのまま残り、
      新しい (key, value) ペアを追加したときに再利用されます。

      注釈:

        再編成中は、元のデータベースと同じサイズの空きディスク領域が必
        要になる場合があります。 ただし、この倍率は "dbm" のサブモジュ
        ールごとに異なります。

   gdbm.sync()

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


"dbm.ndbm" --- New Database Manager
===================================

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

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

"dbm.ndbm" モジュールは NDBM (New Database Manager) ライブラリへのイン
ターフェースを提供します。 このモジュールは「従来の」NDBM インターフェ
ースでも GDBM (GNU dbm) の互換インターフェースでも利用できます。

注釈:

  "dbm.gnu" と "dbm.ndbm" が作成するファイル形式には互換性がなく、相互
  に利用できません。

警告:

  macOS に付属する NDBM ライブラリには、値のサイズに関する文書化されて
  いない制限があります。 この制限より大きな値を保存すると、データベー
  スファイルが破損することがあります。 破損したファイルを読み取ると、
  プログラムがクラッシュ (セグメンテーションフォールト) することがあり
  ます。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォー
ム をサポートしません。

利用可能な環境: Unix.

exception dbm.ndbm.error

   I/O エラーなど、"dbm.ndbm" 固有のエラーで送出されます。 不正なキー
   の指定など、一般的なマッピングのエラーでは "KeyError" を送出します
   。

dbm.ndbm.library

   使用している NDBM 実装ライブラリの名前。

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

   NDBM データベースを開き、"ndbm" オブジェクトを返します。

   パラメータ:
      * **filename** (*path-like object*) -- データベースファイルのベ
        ース名 (".dir" や ".pag" 拡張子は含めません)。

      * **flag** (*str*) --

        * "'r'" (デフォルト): Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'": Open database for reading and writing, creating it if
          it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   バージョン 3.11 で変更: ファイル名として *path-like object* を受け
   付けるようになりました。

   "ndbm" オブジェクトはミュータブルな *マッピング* に似ていますが、
   "items()"、"values()"、"pop()"、"popitem()"、"update()" メソッドは
   サポートしていません。 "keys()" メソッドはリストを返し、
   "setdefault()" メソッドには引数が 2 つ必要です。 また "with" キーワ
   ードによって、終了時にデータベースを閉じるコンテキストマネージャと
   して使えます。

   バージョン 3.2 で変更: "get()" と "setdefault()" メソッドを追加しま
   した。

   バージョン 3.13 で変更: "clear()" メソッドを追加しました。

   次のメソッドを提供しています:

   ndbm.close()

      NDBM データベースを閉じます。


"dbm.dumb" --- 移植性のある DBM 実装
====================================

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

注釈:

  "dbm.dumb" モジュールは、より堅牢なモジュールを利用できないときに
  "dbm" モジュールが最後の手段として使うためのものです。 "dbm.dumb" モ
  ジュールは速度を重視しておらず、他のデータベースモジュールほど広く利
  用されていません。

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

"dbm.dumb" モジュールは、すべて Python で書かれた、永続的な "dict" に
似たインターフェースを提供します。 "dbm.gnu" などの他の "dbm" バックエ
ンドとは異なり、外部ライブラリは不要です。

"dbm.dumb" モジュールは以下を定義しています:

exception dbm.dumb.error

   I/O エラーなど、"dbm.dumb" 固有のエラーで送出されます。 不正なキー
   の指定など、一般的なマッピングのエラーでは "KeyError" を送出します
   。

dbm.dumb.open(filename, flag='c', mode=0o666)

   "dbm.dumb" データベースを開きます。

   パラメータ:
      * **filename** -- データベースファイルのベース名 (拡張子は含めま
        せん)。 新しいデータベースを作ると、次のファイルが作成されます
        :

      * **flag** (*str*) --

        * "'r'": Open existing database for reading only.

        * "'w'": Open existing database for reading and writing.

        * "'c'" (デフォルト): Open database for reading and writing,
          creating it if it doesn't exist.

        * "'n'": Always create a new, empty database, open for reading
          and writing.

      * **mode** (*int*) -- The Unix file access mode of the file
        (default: octal "0o666"), used only when the database has to
        be created.

   警告:

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

   警告:

     "dbm.dumb" は読み書きの同時アクセスをサポートしていません (複数の
     読み取りアクセスを同時に行うのは安全です)。 あるプログラムが書き
     込み用にデータベースを開いている間は、他のプログラムでそのデータ
     ベースを読み取り用にも書き込み用にも開かないでください。

   バージョン 3.5 で変更: *flag* が "'n'" の場合、"open()" は常に新し
   いデータベースを作成するようになりました。

   バージョン 3.8 で変更: *flag* が "'r'" の場合は読み取り専用でデータ
   ベースを開きます。 *flag* が "'r'" または "'w'" でデータベースが存
   在しない場合、新規作成しなくなりました。

   バージョン 3.11 で変更: *filename* に *path-like object* を渡せるよ
   うになりました。

   返されるデータベースオブジェクトはミュータブルな *mapping* に似てい
   ますが、"keys()" と "items()" メソッドはリストを返し、
   "setdefault()" メソッドには引数が 2 つ必要です。 また "with" キーワ
   ードによって、終了時にデータベースを閉じるコンテキストマネージャと
   して使えます。

   次のメソッドも提供します:

   dumbdbm.close()

      データベースを閉じます。

   dumbdbm.reorganize()

      多数の削除を行った後、ディスク上の使用領域を縮小したい場合に、こ
      のメソッドでデータベースを再編成できます。 再編成しない場合、削
      除されたファイル領域は再利用されません。

      注釈:

        再編成中も追加の空きディスク領域は不要です。 ただし、この条件
        は "dbm" のサブモジュールごとに異なります。

      Added in version 3.15.

   dumbdbm.sync()

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