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

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

---

dbm is a generic interface to variants of the DBM database:

• dbm.sqlite3

• dbm.gnu

• dbm.ndbm

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 を渡せるようになりました。

The object returned by open() supports the basic functionality of mutable mappings; keys and their corresponding values can be stored, retrieved, and deleted, and iteration, the in operator and methods keys(), get(), setdefault() and clear() are available. The keys() method returns a list instead of a view object. The setdefault() method requires two arguments.

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.

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

バージョン 3.2 で変更: get() and setdefault() methods are now available for all dbm backends.

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

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

バージョン 3.13 で変更: clear() methods are now available for all dbm backends.

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

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 モジュール

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

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

dbm.sqlite3 --- SQLite backend for dbm

Added in version 3.13.

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

---

This module uses the standard library sqlite3 module to provide an SQLite backend for the dbm module. The files created by dbm.sqlite3 can thus be opened by sqlite3, or any other SQLite browser, including the SQLite CLI.

利用可能な環境: not WASI.

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

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

Open an SQLite database.

パラメータ:

• 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)。 データベースを新規作成する必要がある場合にのみ使います。

The returned database object behaves similar to a mutable mapping, but the keys() method returns a list, and the setdefault() method requires two arguments. It also supports a "closing" context manager via the with keyword.

The following method is also provided:

sqlite3.close()

Close the SQLite database.

dbm.gnu --- GNU database manager

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

---

The dbm.gnu module provides an interface to the GDBM library, similar to the dbm.ndbm module, but with additional functionality like crash tolerance.

注釈

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

利用可能な環境: 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 objects behave similar to mutable mappings, but methods items(), values(), pop(), popitem(), and update() are not supported, the keys() method returns a list, and the setdefault() method requires two arguments. It also supports a "closing" context manager via the with keyword.

バージョン 3.2 で変更: Added the get() and setdefault() methods.

バージョン 3.13 で変更: Added the clear() method.

The following methods are also provided:

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

---

The dbm.ndbm module provides an interface to the NDBM library. This module can be used with the "classic" NDBM interface or the GDBM compatibility interface.

注釈

The file formats created by dbm.gnu and dbm.ndbm are incompatible and can not be used interchangeably.

警告

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 objects behave similar to mutable mappings, but methods items(), values(), pop(), popitem(), and update() are not supported, the keys() method returns a list, and the setdefault() method requires two arguments. It also supports a "closing" context manager via the with keyword.

バージョン 3.2 で変更: Added the get() and setdefault() methods.

バージョン 3.13 で変更: Added the clear() method.

The following method is also provided:

ndbm.close()

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

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

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

注釈

dbm.dumb モジュールは、 dbm が頑健なモジュールを他に見つけることができなかった際の最後の手段とされています。 dbm.dumb モジュールは速度を重視して書かれているわけではなく、他のデータベースモジュールのように重い使い方をするためのものではありません。

---

The dbm.dumb module provides a persistent dict-like interface which is written entirely in Python. Unlike other dbm backends, such as dbm.gnu, no external library is required.

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

exception dbm.dumb.error

I/O エラーのような dbm.dumb 特有のエラーの際に送出されます。不正なキーを指定したときのような、一般的な対応付けエラーの際には KeyError が送出されます。

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

Open a dbm.dumb database.

パラメータ:

• 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 を渡せるようになりました。

The returned database object behaves similar to a mutable mapping, but the keys() and items() methods return lists, and the setdefault() method requires two arguments. It also supports a "closing" context manager via the with keyword.

The following methods are also provided:

dumbdbm.close()

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

dumbdbm.sync()

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