dbm --- Unix "データベース" へのインターフェース¶
ソースコード: Lib/dbm/__init__.py
dbm は DBM データベースの各種実装に対する汎用インターフェースです:
これらのモジュールがどれもインストールされていない場合は、低速ながら単純な 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() メソッドが使えるようになりました。
キーと値の型¶
キーと値として受け付ける型はバックエンドによって異なります。 以下で特に断らない限り、キーと値は同じように扱われます。
従来のバックエンド:
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 ライブラリへのインターフェースを提供します。
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(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 ライブラリへのインターフェースを提供します。
このモジュールは「従来の」NDBM インターフェースでも GDBM の互換インターフェースでも利用できます。
注釈
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()メソッドから呼び出されます。