34.3. winreg --- Windows レジストリへのアクセス

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

バージョン 3.3 で変更: このモジュールのいくつかの関数は以前は WindowsError を送出していました。それは今では OSError の別名です。

34.3.1. 関数

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

winreg.CloseKey(hkey)

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

注釈

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

winreg.ConnectRegistry(computer_name, key)

他のコンピュータ上にある事前に定義されたレジストリハンドルとの接続を確立し、 ハンドルオブジェクト を返します。

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

key は、事前に定義された接続先のハンドルです。

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

バージョン 3.3 で変更: 上記 を参照。

winreg.CreateKey(key, sub_key)

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

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

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

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

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

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

バージョン 3.3 で変更: 上記 を参照。

winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)

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

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

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

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

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

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

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

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

バージョン 3.2 で追加.

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteKey(key, sub_key)

指定されたキーを削除します。

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

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

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

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

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)

指定されたキーを削除します。

注釈

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

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

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

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

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

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

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

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

バージョン 3.2 で追加.

バージョン 3.3 で変更: 上記 を参照。

winreg.DeleteValue(key, value)

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

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

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

winreg.EnumKey(key, index)

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

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

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

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

バージョン 3.3 で変更: 上記 を参照。

winreg.EnumValue(key, index)

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

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

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

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

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

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

バージョン 3.3 で変更: 上記 を参照。

winreg.ExpandEnvironmentStrings(str)

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

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'
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, reserved=0, access=KEY_READ)
winreg.OpenKeyEx(key, sub_key, reserved=0, access=KEY_READ)

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

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

sub_key は開くサブキーを指定する文字列です。

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

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

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

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

バージョン 3.2 で変更: 名前付き引数が使用できるようになりました。

バージョン 3.3 で変更: 上記 を参照。

winreg.QueryInfoKey(key)

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

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

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

インデックス 意味
0 このキーが持つサブキーの数を表す整数。
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 は値が関連付けられているサブキーの名前を表す文字列です。

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

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

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 例外を発生させます。

34.3.2. 定数

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

34.3.2.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 以降のバージョンでは利用されていません。

34.3.2.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

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

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

34.3.2.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 のレジストリビュー上で操作する事を示します。

34.3.2.3. 値の型

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

winreg.REG_BINARY

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

winreg.REG_DWORD

32 ビットの数。

winreg.REG_DWORD_LITTLE_ENDIAN

A 32-bit number in little-endian format.

winreg.REG_DWORD_BIG_ENDIAN

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

winreg.REG_EXPAND_SZ

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

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

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

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

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

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

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

ハンドルオブジェクトは __bool__() の意味構成を持ちます - すなわち

if handle:
    print("Yes")

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

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

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

ハンドルオブジェクトから 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 を閉じます。