プラットフォーム: Windows
ノート
_winreg モジュールは Python 3.0 では winreg にリネームされました。 ソースコードを3.0用に変換するときは、 2to3 ツールが自動的に import を修正します。
バージョン 2.0 で追加.
これらの関数は Windows レジストリ API を Python で使えるようにします。プログラマがレジストリハンドルのクローズを失念した場合でも、確実に ハンドルがクローズされるようにするために、整数値をレジストリハンドルとして使う代わりにハンドルオブジェクトが使われます。
このモジュールは Windows レジストリ操作のための非常に低レベルのインタフェースを使えるようにします; 将来、より高レベルのレジストリ API インタフェースを提供するような、新たな winreg モジュールが作られるよう期待します。
このモジュールでは以下の関数を提供します:
以前開かれたレジストリキーを閉じます。 hkey 引数には以前開かれたレジストリキーを特定します。
このメソッドを使って (または handle.Close() によって) hkey が閉じられなかった場合、Python が hkey オブジェクトを破壊する際に閉じられるので注意してください。
他の計算機上にある既定のレジストリハンドル接続を確立し、 ハンドルオブジェクト (handle object) を返します。
computer_name はリモートコンピュータの名前で、 r"\\computername" の形式をとります。 None の場合、ローカルの計算機が使われます。
key は接続したい既定のハンドルです。
戻り値は開かれたキーのハンドルです。関数が失敗した場合、 WindowsError 例外が送出されます。
特定のキーを生成するか開き、 ハンドルオブジェクト を返します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key はこのメソッドが開く、または新規作成するキーの名前です。
key が既定のキーの一つなら、 sub_key は None でかまいません。この場合、返されるハンドルは関数に渡されたのと 同じキーハンドルです。
キーがすでに存在する場合、この関数は既に存在するキーを開きます。
戻り値は開かれたキーのハンドルです。この関数が失敗した場合、 WindowsError 例外が送出されます。
特定のキーを削除します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key は文字列で、 key パラメタによって特定されたキーのサブキーでなければなりません。この値は None で あってはならず、キーはサブキーを持っていてはなりません。
このメソッドはサブキーをもつキーを削除することはできません。
このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、 WindowsError 例外が送出されます。
レジストリキーから指定された名前つきの値を削除します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つでなければなりません。
value は削除したい値を指定するための文字列です。
開かれているレジストリキーのサブキーを列挙し、文字列で返します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つでなければなりません。
index は整数値で、取得するキーのインデクスを特定します。
この関数は呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上サブキーがないことを示す WindowsError 例外が送出されるまで繰り返し呼び出されます。
開かれているレジストリキーの値を列挙し、タプルで返します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つでなければなりません。
index は整数値で、取得する値のインデクスを特定します。
この関数は呼び出されるたびに一つの値の名前を取得します。この関数は通常、これ以上値がないことを示す WindowsError 例外が送出されるまで繰り返し呼び出されます。
結果は 3 要素のタプルになります:
Index | Meaning |
---|---|
0 | 値の名前を特定する文字列 |
1 | 値のデータを保持するためのオブジェクトで、その型は背後のレジストリ型に依存します |
2 | 値のデータ型を特定する整数です |
const:REG_EXPAND_SZ のような、%NAME% を環境変数で置き換えます。
>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"
バージョン 2.6 で追加.
キーのすべての属性をレジストリに書き込みます。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つでなければなりません。
キーを変更するために RegFlushKey() を呼ぶ必要はありません。レジストリの変更は怠惰なフラッシュ機構 (lazy flusher) を使って フラッシュされます。また、システムの遮断時にもディスクにフラッシュされます。 CloseKey() と違って、 FlushKey() メソッドはレジストリに全てのデータを書き終えたときにのみ返ります。アプリケーションは、レジストリへの変更を絶対に確実にディスク上に 反映させる必要がある場合にのみ、 FlushKey() を呼ぶべきです。
ノート
FlushKey() を呼び出す必要があるかどうか分からない場合、おそらくその必要はありません。
指定されたキーの下にサブキーを生成し、サブキーに指定されたファイルのレジストリ情報を記録します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key は記録先のサブキーを指定する文字列です。
file_name はレジストリデータを読み出すためのファイル名です。このファイルは SaveKey() 関数で生成されたファイルでなくては なりません。ファイル割り当てテーブル (FAT) ファイルシステム下では、ファイル名は拡張子を持っていてはなりません。
この関数を呼び出しているプロセスが SE_RESTORE_PRIVILEGE 特権を持たない場合には LoadKey() は失敗します。 この特権はファイル許可とは違うので注意してください - 詳細は Win32 ドキュメンテーションを参照してください。
key が ConnectRegistry() によって返されたハンドルの場合、 fileName に指定されたパスは遠隔計算機に対する相対パス名になります。
Win32 ドキュメンテーションでは、 key は HKEY_USER または HKEY_LOCAL_MACHINE ツリー内になければならないとされています。これは正しいかもしれないし、そうでないかもしれません。
指定されたキーを開き、 handle object を返します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key は開きたいサブキーを特定する文字列です。
res 予約されている整数値で、ゼロでなくてはなりません。標準の値はゼロです。
sam は必要なキーへのセキュリティアクセスを記述する、アクセスマスクを指定する整数です。標準の値は KEY_READ です。
指定されたキーへの新しいハンドルが返されます。
この関数が失敗すると、 WindowsError が送出されます。
OpenKeyEx() の機能は OpenKey() を標準の引数で使うことで提供されています。
キーに関数情報をタプルとして返します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
結果は以下の 3 要素からなるタプルです:
インデクス | 意味 |
---|---|
0 | このキーが持つサブキーの数を表す整数。 |
1 | このキーが持つ値の数を表す整数。 |
2 | 最後のキーの変更が (あれば) いつだったかを表す長整数で、 1600 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。 |
キーに対する、名前付けられていない値を文字列で取得します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key は値が関連付けられているサブキーの名前を保持する文字列です。この引数が None または空文字列の場合、この関数は key で特定されるキーに対して SetValue() メソッドで設定された値を取得します。
レジストリ中の値は名前、型、およびデータから構成されています。 このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。 しかし背後のAPI 呼び出しは型情報を返しません。 なので、可能ならいつでも QueryValueEx() を使うべきです。
開かれたレジストリキーに関連付けられている、指定した名前の値に対して、型およびデータを取得します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
value_name は要求する値を指定する文字列です。
結果は 2 つの要素からなるタプルです:
インデクス | 意味 |
---|---|
0 | レジストリ要素の名前。 |
1 | この値のレジストリ型を表す整数。 |
指定されたキーと、そのサブキー全てを指定したファイルに保存します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
file_name はレジストリデータを保存するファイルの名前です、このファイルはすでに存在していてはいけません。このファイル名が 拡張子を含んでいる場合、 LoadKey() 、 ReplaceKey() または RestoreKey() メソッドは、ファイル割り当てテーブル (FAT) 型ファイルシステムを使うことができません。
key が遠隔の計算機上にあるキーを表す場合、 file_name で記述されているパスは遠隔の計算機に対して相対的なパスになります。 このメソッドの呼び出し側は SeBackupPrivilege セキュリティ特権を保有していなければなりません。この特権は ファイルパーミッションとは異なります - 詳細は Win32 ドキュメンテーションを参照してください。
この関数は security_attributes を NULL にして API に渡します。
値を指定したキーに関連付けます。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
sub_key は値が関連付けられているサブキーの名前を表す文字列です。
type はデータの型を指定する整数です。現状では、この値は REG_SZ でなければならず、これは文字列だけが サポートされていることを示します。他のデータ型をサポートするには SetValueEx() を使ってください。
value は新たな値を指定する文字列です。
sub_key 引数で指定されたキーが存在しなければ、 SetValue 関数で生成されます。
値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。
key 引数に指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。
開かれたレジストリキーの値フィールドにデータを記録します。
key はすでに開かれたキーか、既定の HKEY_* 定数のうちの一つです。
value_name は値が関連付けられているサブキーの名前を表す文字列です。
type はデータの型を指定する整数です。値はこのモジュールで定義されている以下の定数のうちの一つでなければなりません:
定数 | 意味 |
---|---|
REG_BINARY | 何らかの形式のバイナリデータ。 |
REG_DWORD | 32 ビットの数。 |
REG_DWORD_LITTLE_ENDIAN | 32 ビットのリトルエンディアン形式の数。 |
REG_DWORD_BIG_ENDIAN | 32 ビットのビッグエンディアン形式の数。 |
REG_EXPAND_SZ | 環境変数を参照している、ヌル文字で終端された文字列。 (%PATH%)。 |
REG_LINK | Unicode のシンボリックリンク。 |
REG_MULTI_SZ | ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている配列 (Python はこの終端の処理を自動的に行います)。 |
REG_NONE | 定義されていない値の形式。 |
REG_RESOURCE_LIST | デバイスドライバリソースのリスト。 |
REG_SZ | ヌルで終端された文字列。 |
reserved は何もしません - API には常にゼロが渡されます。
value は新たな値を指定する文字列です。
このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を設定することができます。 key 引数で指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。
キーを開くには、 CreateKeyEx() または OpenKey() メソッドを使ってください。
値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存 するべきです。そうすればレジストリを効率的に動作させる役に立ちます。
このオブジェクトは Windows の HKEY オブジェクトをラップし、オブジェクトが破壊されたときに自動的にハンドルを閉じます。オブジェクトの Close() メソッドと CloseKey() 関数のどちらも、後始末がきちんと行われることを保証するために呼び出す ことができます。
このモジュールのレジストリ関数は全て、これらのハンドルオブジェクトの一つを返します。
このモジュールのレジストリ関数でハンドルオブジェクトを受理するものは全て整数も受理しますが、ハンドルオブジェクトを利用することを推奨します。
ハンドルオブジェクトは __nonzero__() の意味構成を持ちます - すなわち、
if handle:
print "Yes"
は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合には Yes となります。
ハンドルオブジェクトはまた、比較の意味構成もサポートしています。このため、背後の Windows ハンドル値が同じものを複数のハンドルオブジェクト が参照している場合、それらの比較は真になります。
ハンドルオブジェクトは (例えば組み込みの int() 関数を使って) 整数に変換することができます。この場合、背後の Windows ハンドル値が返されます、また、 Detach() メソッドを使って整数のハンドル値を返させると同時に、ハンドルオブジェクトから Windows ハンドルを切り離すこともできます。
背後の Windows ハンドルを閉じます。
ハンドルがすでに閉じられていてもエラーは送出されません。
ハンドルオブジェクトから Windows ハンドルを切り離します。
切り離される以前にそのハンドルを保持していた整数 (または 64 ビット Windows の場合には長整数) オブジェクトが返されます。 ハンドルがすでに切り離されていたり閉じられていたりした場合、ゼロが返されます。
この関数を呼び出した後、ハンドルは確実に無効化されますが、閉じられるわけではありません。背後の Win32 ハンドルがハンドル オブジェクトよりも長く維持される必要がある場合にはこの関数を呼び出すとよいでしょう。
HKEY オブジェクトは __enter__(), __exit__() メソッドを実装していて、 with 文のためのコンテキストプロトコルをサポートしています。
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
# ... key を使った処理 ...
このコードは、 with ブロックから抜けるときに自動的に key を閉じます。
バージョン 2.6 で追加.