35.3. _winreg — Windows レジストリへのアクセス

注釈

_winreg モジュールは、Python 3 では winreg にリネームされました。 2to3 ツールが自動的にソースコードの import を修正します。

バージョン 2.0 で追加.

これらの関数は Windows レジストリ API を Python から使えるようにします。プログラマがレジストリハンドルのクローズを失念した場合でも、確実にハンドルがクローズされるようにするために、整数値をレジストリハンドルとして使う代わりに ハンドルオブジェクト が使われます。

このモジュールでは以下の関数を提供します:

_winreg.CloseKey(hkey)

以前開かれたレジストリキーを閉じます。hkey 引数には以前開かれたレジストリキーを特定します。

注釈

このメソッドを使って (または hkey.Close() によって) hkey が閉じられなかった場合、Python が hkey オブジェクトを破壊する際に閉じられます。

_winreg.ConnectRegistry(computer_name, key)

他の計算機上にある既定のレジストリハンドル接続を確立し、 ハンドルオブジェクト を返します。

computer_name はリモートコンピュータの名前で、r"\\computername" の形式をとります。None の場合、ローカルの計算機が使われます。

key は接続したい既定のハンドルです。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 WindowsError 例外が送出されます。

_winreg.CreateKey(key, sub_key)

特定のキーを生成するか開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key はこのメソッドが開く、または新規作成するキーの名前です。

key が既定のキーの一つなら、sub_key は None でかまいません。この場合、返されるハンドルは関数に渡されたのと同じキーハンドルです。

キーがすでに存在する場合、この関数は既に存在するキーを開きます。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 WindowsError 例外が送出されます。

_winreg.CreateKeyEx(key, sub_key[, res[, sam]])

特定のキーを生成するか開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key はこのメソッドが開く、または新規作成するキーの名前です。

res は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。

sam は、 key に対して想定するセキュリティアクセスを示すアクセスマスクを指定します。デフォルトは KEY_ALL_ACCESS です。利用可能な値については アクセス権 を参照してください。

key が既定のキーの一つなら、sub_key は None でかまいません。この場合、返されるハンドルは関数に渡されたのと同じキーハンドルです。

キーがすでに存在する場合、この関数は既に存在するキーを開きます。

戻り値は開かれたキーのハンドルです。関数が失敗した場合、 WindowsError 例外が送出されます。

バージョン 2.7 で追加.

_winreg.DeleteKey(key, sub_key)

特定のキーを削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は文字列で、key パラメタによって特定されたキーのサブキーでなければなりません。この値は None であってはならず、キーはサブキーを持っていなくてもかまいません。

このメソッドはサブキーをもつキーを削除することはできません。

このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、 WindowsError 例外が送出されます。

_winreg.DeleteKeyEx(key, sub_key[, sam[, res]])

特定のキーを削除します。

注釈

The DeleteKeyEx() 関数は、RegDeleteKeyEx Windows API 関数で実装されています。これは Windows の 64-bit バージョンに特有です。 RegDeleteKeyEx documentation を参照してください。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は key 引数によって指定された key の subkey でなければなりません。この値は None であってはなりません。また、key は subkey を持たないかもしれません。

res は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。

sam は、 key に対して想定するセキュリティアクセスを示すアクセスマスクを指定します。デフォルトは KEY_WOW64_64KEY です。利用可能な値については アクセス権 を参照してください。

このメソッドはサブキーをもつキーを削除することはできません。

このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、 WindowsError 例外が送出されます。

サポートされていない Windows バージョンでは、 NotImplementedError 例外を発生させます。

バージョン 2.7 で追加.

_winreg.DeleteValue(key, value)

レジストリキーから指定された名前つきの値を削除します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value は削除したい値を指定するための文字列です。

_winreg.EnumKey(key, index)

開かれているレジストリキーのサブキーを列挙し、文字列で返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

index は整数値で、取得するキーのインデクスを特定します。

この関数は呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す WindowsError 例外が送出されるまで繰り返し呼び出されます。

_winreg.EnumValue(key, index)

開かれているレジストリキーの値を列挙し、タプルで返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

index は整数値で、取得する値のインデクスを特定します。

この関数は呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す WindowsError 例外が送出されるまで繰り返し呼び出されます。

結果は 3 要素のタプルになります:

インデックス	意味
0	値の名前を特定する文字列
1	値のデータを保持するためのオブジェクトで、その型は背後のレジストリ型に依存します
2	値のデータ型を特定する整数です (SetValueEx() のドキュメント内のテーブルを参照してください)

_winreg.ExpandEnvironmentStrings(unicode)

REG_EXPAND_SZ のように、環境変数プレースホルダ %NAME% を Unicode 文字列で展開します:

>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"

バージョン 2.6 で追加.

_winreg.FlushKey(key)

キーのすべての属性をレジストリに書き込みます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

キーを変更するために FlushKey() を呼ぶ必要はありません。レジストリの変更は怠惰なフラッシュ機構 (lazy flusher) を使ってフラッシュされます。また、システムの遮断時にもディスクにフラッシュされます。 CloseKey() と違って、 FlushKey() メソッドはレジストリに全てのデータを書き終えたときにのみ返ります。アプリケーションは、レジストリへの変更を絶対に確実にディスク上に反映させる必要がある場合にのみ、 FlushKey() を呼ぶべきです。

注釈

FlushKey() を呼び出す必要があるかどうか分からない場合、おそらくその必要はありません。

_winreg.LoadKey(key, sub_key, file_name)

指定されたキーの下にサブキーを生成し、サブキーに指定されたファイルのレジストリ情報を記録します。

key は ConnectRegistry() が返したハンドルか、定数 HKEY_USERS と HKEY_LOCAL_MACHINE のどちらかです。

sub_key は記録先のサブキーを指定する文字列です。

file_name はレジストリデータを読み出すためのファイル名です。このファイルは SaveKey() 関数で生成されたファイルでなくてはなりません。ファイル割り当てテーブル (FAT) ファイルシステム下では、ファイル名は拡張子を持っていてはなりません。

この関数を呼び出しているプロセスが SE_RESTORE_PRIVILEGE 特権を持たない場合には LoadKey() は失敗します。この特権はファイル許可とは違うので注意してください - 詳細は RegLoadKey documentation を参照してください。

key が ConnectRegistry() によって返されたハンドルの場合、 file_name に指定されたパスは遠隔計算機に対する相対パス名になります。

_winreg.OpenKey(key, sub_key[, res[, sam]])

指定されたキーを開き、 ハンドルオブジェクト を返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は開きたいサブキーを特定する文字列です。

res は予約されている整数値で、ゼロでなくてはなりません。デフォルトはゼロです。

sam は必要なキーへのセキュリティアクセスを記述する、アクセスマスクを指定する整数です。標準の値は KEY_READ です。その他の利用できる値については アクセス権限 を参照してください。

指定されたキーへの新しいハンドルが返されます。

この関数が失敗すると、 WindowsError が送出されます。

_winreg.OpenKeyEx()

OpenKeyEx() の機能は OpenKey() を標準の引数で使うことで提供されています。

_winreg.QueryInfoKey(key)

キーに関数情報をタプルとして返します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

結果は 3 要素のタプルになります:

インデックス	意味
0	結果は以下の 3 要素からなるタプルです。
1	このキーが持つサブキーの数を表す整数。
2	最後のキーの変更が (あれば) いつだったかを表す長整数で、1601 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。

_winreg.QueryValue(key, sub_key)

キーに対する、名前付けられていない値を文字列で取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を保持する文字列です。この引数が None または空文字列の場合、この関数は key で特定されるキーに対して SetValue() メソッドで設定された値を取得します。

レジストリ中の値は名前、型、およびデータから構成されています。このメソッドはあるキーのデータ中で、名前 NULL をもつ最初の値を取得します。しかし背後のAPI 呼び出しは型情報を返しません。なので、可能ならいつでも QueryValueEx() を使うべきです。

_winreg.QueryValueEx(key, value_name)

開かれたレジストリキーに関連付けられている、指定した名前の値に対して、型およびデータを取得します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value_name は要求する値を指定する文字列です。

結果は 2 つの要素からなるタプルです:

インデックス	意味
0	レジストリ要素の値。
1	この値のレジストリ型を表す整数。 (SetValueEx() のドキュメント内のテーブルを参照してください。)

_winreg.SaveKey(key, file_name)

指定されたキーと、そのサブキー全てを指定したファイルに保存します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

file_name はレジストリデータを保存するファイルの名前です、このファイルはすでに存在していてはいけません。このファイル名が拡張子を含んでいる場合、 LoadKey() メソッドは、FAT ファイルシステムを使うことができません。

key が遠隔の計算機上にあるキーを表す場合、 file_name で記述されているパスは遠隔の計算機に対して相対的なパスになります。このメソッドの呼び出し側は SeBackupPrivilege セキュリティ特権を保有していなければなりません。この特権はファイルパーミッションとは異なります - 詳細は Conflicts Between User Rights and Permissions documentation を参照してください。

この関数は security_attributes を NULL にして API に渡します。

_winreg.SetValue(key, sub_key, type, value)

値を指定したキーに関連付けます。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

sub_key は値が関連付けられているサブキーの名前を表す文字列です。

type はデータの型を指定する整数です。現状では、この値は REG_SZ でなければならず、これは文字列だけがサポートされていることを示します。他のデータ型をサポートするには SetValueEx() を使ってください。

value は新たな値を指定する文字列です。

sub_key 引数で指定されたキーが存在しなければ、SetValue 関数で生成されます。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

key 引数に指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

_winreg.SetValueEx(key, value_name, reserved, type, value)

開かれたレジストリキーの値フィールドにデータを記録します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

value_name は値が関連付けられているサブキーの名前を表す文字列です。

type はデータの型を指定する整数です。利用できる型については 値の型 を参照してください。

reserved は何もしません - API には常にゼロが渡されます。

value は新たな値を指定する文字列です。

このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を設定することができます。 key 引数で指定されたキーは KEY_SET_VALUE アクセスで開かれていなければなりません。

キーを開くには、 CreateKey() または OpenKey() メソッドを使ってください。

値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。

_winreg.DisableReflectionKey(key)

64ビット OS上で動作している 32bit プロセスに対するレジストリリフレクションを無効にします。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

32bit OS上では一般的に NotImplemented 例外を発生させます。

key がリフレクションリストに無い場合は、この関数は成功しますが効果はありません。あるキーのリフレクションを無効にしても、その全てのサブキーのリフレクションには影響しません。

_winreg.EnableReflectionKey(key)

指定された、リフレクションが無効にされたキーのリフレクションを再び有効にします。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

32bit OS上では一般的に NotImplemented 例外を発生させます。

あるキーのリフレクションを再開しても、その全てのサブキーには影響しません。

_winreg.QueryReflectionKey(key)

指定されたキーのリフレクション状態を確認します。

key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。

リフレクションが無効になっている場合、True を返します。

32bit OS上では一般的に NotImplemented 例外を発生させます。

35.3.1. 定数

_winreg の多くの関数で利用するために以下の定数が定義されています。

35.3.1.1. HKEY_* 定数

_winreg.HKEY_CLASSES_ROOT

このキー以下のレジストリエントリは、ドキュメントのタイプ（またはクラス）や、それに関連付けられたプロパティを定義しています。シェルと COM アプリケーションがこの情報を利用します。

_winreg.HKEY_CURRENT_USER

このキー以下のレジストリエントリは、現在のユーザーの設定を定義します。この設定には、環境変数、プログラムグループに関するデータ、カラー、プリンター、ネットワーク接続、アプリケーション設定などが含まれます。

_winreg.HKEY_LOCAL_MACHINE

このキー以下のレジストリエントリは、コンピュータの物理的な状態を定義します。これには、バスタイプ、システムメモリ、インストールされているソフトウェアやハードウェアが含まれます。

_winreg.HKEY_USERS

このキー以下のレジストリエントリは、ローカルコンピュータの新規ユーザーのためのデフォルト設定や、現在のユーザーの設定を定義しています。

_winreg.HKEY_PERFORMANCE_DATA

このキー以下のレジストリエントリは、パフォーマンスデータへのアクセスを可能にしています。実際にはデータはレジストリには格納されていません。レジストリ関数がシステムにソースからデータを集めさせます。

_winreg.HKEY_CURRENT_CONFIG

ローカルコンピュータシステムの現在のハードウェアプロファイルに関する情報を含みます。

_winreg.HKEY_DYN_DATA

このキーは Windows の 98 以降のバージョンでは利用されていません。

35.3.1.2. アクセス権限

より詳しい情報については、Registry Key Security and Access を参照してください。

_winreg.KEY_ALL_ACCESS

STANDARD_RIGHTS_REQUIRED (KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_LINK) アクセス権限の組み合わせ。

_winreg.KEY_WRITE

STANDARD_RIGHTS_WRITE (KEY_SET_VALUE, KEY_CREATE_SUB_KEY) アクセス権限の組み合わせ。

_winreg.KEY_READ

STANDARD_RIGHTS_READ (KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY) アクセス権限の組み合わせ。

_winreg.KEY_EXECUTE

KEY_READ と同じ。

_winreg.KEY_QUERY_VALUE

レジストリキーの値を問い合わせるのに必要。

_winreg.KEY_SET_VALUE

レジストリの値を作成、削除、設定するのに必要。

_winreg.KEY_CREATE_SUB_KEY

レジストリキーのサブキーを作るのに必要。

_winreg.KEY_ENUMERATE_SUB_KEYS

レジストリキーのサブキーを列挙するのに必要。

_winreg.KEY_NOTIFY

レジストリキーやそのサブキーに対する変更通知を要求するのに必要。

_winreg.KEY_CREATE_LINK

システムでの利用のために予約されている。

35.3.1.2.1. 64-bit 特有のアクセス権

より詳しい情報については、Accessing an Alternate Registry View を参照してください。

_winreg.KEY_WOW64_64KEY

64 bit Windows 上のアプリケーションが、64 bit のレジストリビュー上で操作する事を示します。

_winreg.KEY_WOW64_32KEY

64 bit Windows 上のアプリケーションが、32 bit のレジストリビュー上で操作する事を示します。

35.3.1.3. 値の型

より詳しい情報は、Registry Value Types を参照してください。

_winreg.REG_BINARY

何らかの形式のバイナリデータ。

_winreg.REG_DWORD

32 ビットの数。

_winreg.REG_DWORD_LITTLE_ENDIAN

32 ビットのリトルエンディアン形式の数。

_winreg.REG_DWORD_BIG_ENDIAN

32 ビットのビッグエンディアン形式の数。

_winreg.REG_EXPAND_SZ

環境変数を参照している、ヌル文字で終端された文字列。(%PATH%)。

_winreg.REG_LINK

Unicode のシンボリックリンク。

_winreg.REG_MULTI_SZ

ヌル文字で終端された文字列からなり、二つのヌル文字で終端されている配列。 (Python はこの終端の処理を自動的に行います。)

_winreg.REG_NONE

定義されていない値の形式。

_winreg.REG_RESOURCE_LIST

デバイスドライバリソースのリスト。

_winreg.REG_FULL_RESOURCE_DESCRIPTOR

ハードウェアセッティング。

_winreg.REG_RESOURCE_REQUIREMENTS_LIST

ハードウェアリソースリスト。

_winreg.REG_SZ

ヌル文字で終端された文字列。

35.3.2. レジストリハンドルオブジェクト

このオブジェクトは Windows の HKEY オブジェクトをラップし、オブジェクトが破壊されたときに自動的にハンドルを閉じます。オブジェクトの Close() メソッドと CloseKey() 関数のどちらも、後始末がきちんと行われることを保証するために呼び出すことができます。

このモジュールのレジストリ関数は全て、これらのハンドルオブジェクトの一つを返します。

このモジュールのレジストリ関数でハンドルオブジェクトを受理するものは全て整数も受理しますが、ハンドルオブジェクトを利用することを推奨します。

ハンドルオブジェクトは __nonzero__() のセマンティクスを持ちます - すなわち

if handle:
    print "Yes"

は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合には Yes となります。

ハンドルオブジェクトはまた、比較の意味構成もサポートしています。このため、背後の Windows ハンドル値が同じものを複数のハンドルオブジェクトが参照している場合、それらの比較は真になります。

ハンドルオブジェクトは (例えば組み込みの int() 関数を使って) 整数に変換することができます。この場合、背後の Windows ハンドル値が返されます、また、 Detach() メソッドを使って整数のハンドル値を返させると同時に、ハンドルオブジェクトから Windows ハンドルを切り離すこともできます。

PyHKEY.Close()

背後の Windows ハンドルを閉じます。

ハンドルがすでに閉じられていてもエラーは送出されません。

PyHKEY.Detach()

ハンドルオブジェクトから Windows ハンドルを切り離します。

切り離される以前にそのハンドルを保持していた整数 (または、64 ビット Windows では長整数) オブジェクトが返されます。ハンドルがすでに切り離されていたり閉じられていたりした場合、ゼロが返されます。

この関数を呼び出した後、ハンドルは確実に無効化されますが、閉じられるわけではありません。背後の Win32 ハンドルがハンドルオブジェクトよりも長く維持される必要がある場合にはこの関数を呼び出すとよいでしょう。

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

HKEY オブジェクトは __enter__(), __exit__() メソッドを実装していて、 with 文のためのコンテキストプロトコルをサポートしています:

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key

このコードは、 with ブロックから抜けるときに自動的に key を閉じます。

バージョン 2.6 で追加.