12.5. dbm — Unix “データベース” へのインタフェース

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 — のどれを使用すべきか推測を試みます。

次の値のうち1つを返します: ファイルが読み取れないか存在しないために開くことができない場合は 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 列として格納されます。これは、文字列が使用された場合は格納される前に暗黙的にデフォルトエンコーディングに変換されるということを意味します。

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

import dbm

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

# 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

# Close when done.
db.close()

参考

shelve モジュール

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

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

12.5.1. dbm.gnu — GNU による dbm 拡張

このモジュールは dbm モジュールによく似ていますが、GNU ライブラリ gdbm を使っていくつかの追加機能を提供しています。 dbm.gnudbm.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()

このメソッドと next() メソッドを使って、データベースの全てのキーにわたってループ処理を行うことができます。探索は 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()

Close the gdbm database.

12.5.2. dbm.ndbm — ndbm に基づくインタフェース

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]])

Open a dbm database and return a ndbm object. The filename argument is the name of the database file (without the .dir or .pag extensions).

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

意味

'r'

既存のデータベースを読み込み専用で開く (デフォルト)

'w'

既存のデータベースを読み書き用に開く

'c'

データベースを読み書き用に開く。ただし存在しない場合には新たに作成する

'n'

常に新たに読み書き用の新規のデータベースを作成する

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

In addition to the dictionary-like methods, ndbm objects provide the following method:

ndbm.close()

Close the ndbm database.

12.5.3. dbm.dumb — 可搬性のある DBM 実装

注釈

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 引数は現状では無視されます; データベースは常に更新のために開かれ、存在しない場合には新たに作成されます。

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

In addition to the methods provided by the collections.abc.MutableMapping class, dumbdbm objects provide the following methods:

dumbdbm.sync()

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

dumbdbm.close()

Close the dumbdbm database.