12.5. 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() がすべてのデータベースモジュールで利用できるようになりました。

キーと値は常に 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 モジュール
非文字列データを記録する永続化モジュール。

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

12.5.1. 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 データベースをクローズします。

12.5.2. 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 データベースをクローズします。

12.5.3. 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 引数は値 'c' と値 'n' のセマンティクスのみをサポートしています。他の値を指定すると、デフォルトの常に更新のために開かれたデータベースになり、存在しない場合には新たに作成されます。

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

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

バージョン 3.6 で非推奨、バージョン 3.8 で削除予定: 'r' と 'w' モードでデータベースの作成。 'r' モードでデータベースを変更。

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

dumbdbm.sync()

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

dumbdbm.close()

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