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

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

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

If none of these modules are installed, the slow-but-simple implementation in module dbm.dumb will be used. There is a third party interface to the Oracle Berkeley DB.

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 つ必要です。

Key and values are always stored as bytes. This means that when strings are used they are implicitly converted to the default encoding before being stored. For detailed information about accepted types, see Key and value types.

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

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

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

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

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

Key and value types

The accepted types for keys and values vary by backend. Keys and values are handled the same way, except where noted below:

Storage format:

All keys and values are stored as bytes objects in the database. When retrieving, you'll always get bytes back, regardless of the original type stored.

Type conversion examples:

  • db['key'] = 'string' stored as b'string'

  • db['key'] = bytearray(b'data') stored as b'data' (dbm.dumb and dbm.sqlite3 only)

  • db['key'] = 42 stored as b'42' (dbm.sqlite3 only)

  • db['key'] = 3.14 stored as b'3.14' (dbm.sqlite3 only)

  • db['key'] = True stored as b'1' (dbm.sqlite3 only)

  • db['key'] = False stored as b'0' (dbm.sqlite3 only)

  • db['key'] = memoryview(b'data') stored as b'data' (dbm.sqlite3 only)

  • db['key'] = array.array('i', [1, 2, 3]) stored as bytes (for example, on little-endian: b'\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00') (dbm.sqlite3 only)

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

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 behavior depends on the backend:
    # - Traditional backends (ndbm, gnu, dumb) will raise a TypeError
    # - The sqlite3 backend accepts it and converts to bytes
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

参考

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 データベースを閉じます。

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_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) ペアを追加したときに再利用されます。

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 インタプリタをクラッシュさせることができます。

バージョン 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.sync()

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