winreg --- Windows レジストリへのアクセス¶
これらの関数は Windows レジストリ API を Python から使えるようにします。プログラマがレジストリハンドルを明示的にクローズするのを忘れた場合でも、確実にハンドルがクローズされるようにするために、レジストリハンドルとして整数値ではなく ハンドルオブジェクト が使われます。
バージョン 3.3 で変更: このモジュールのいくつかの関数は以前は WindowsError を送出していました。それは今では OSError の別名です。
関数¶
このモジュールでは以下の関数を提供します:
- winreg.CloseKey(hkey)¶
以前開かれたレジストリキーを閉じます。hkey 引数は以前開かれたレジストリキーを指定します。
注釈
このメソッドを使って (または
hkey.Close()によって) hkey が閉じられなかった場合、Python が hkey オブジェクトを破壊する際に閉じられます。
- winreg.ConnectRegistry(computer_name, key)¶
他のコンピュータ上にある事前に定義されたレジストリハンドルとの接続を確立し、 ハンドルオブジェクト を返します。
computer_name はリモートコンピュータの名前で、
r"\\computername"の形式をとります。Noneの場合、ローカルのコンピュータが使われます。key は、事前に定義された接続先のハンドルです。
戻り値は開かれたキーのハンドルです。関数が失敗した場合、
OSError例外が送出されます。引数
computer_name,keyを指定して 監査イベントwinreg.ConnectRegistryを送出します。バージョン 3.3 で変更: 上記 を参照。
- winreg.CreateKey(key, sub_key)¶
指定されたキーを生成するか開き、 ハンドルオブジェクト を返します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
sub_key はこのメソッドが開く、または新規作成するキーの名前です。
key が事前に定義されたキーのうちの一つなら、sub_key は
Noneでかまいません。その場合、この関数に渡されるキーハンドルと同じハンドルが返されます。キーがすでに存在する場合、この関数はその既存のキーを開きます。
戻り値は開かれたキーのハンドルです。関数が失敗した場合、
OSError例外が送出されます。引数
key,sub_key,accessを指定して 監査イベントwinreg.CreateKeyを送出します。引数
keyを指定して 監査イベントwinreg.OpenKey/resultを送出します。バージョン 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例外が送出されます。引数
key,sub_key,accessを指定して 監査イベントwinreg.CreateKeyを送出します。引数
keyを指定して 監査イベントwinreg.OpenKey/resultを送出します。Added in version 3.2.
バージョン 3.3 で変更: 上記 を参照。
- winreg.DeleteKey(key, sub_key)¶
指定されたキーを削除します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
sub_key は文字列で、key 引数によって指定されたキーのサブキーでなければなりません。この値は
Noneであってはならず、キーはサブキーを持っていなくてもかまいません。このメソッドはサブキーをもつキーを削除することはできません。
このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、
OSError例外が送出されます。Raises an auditing event
winreg.DeleteKeywith argumentskey,sub_key,access.バージョン 3.3 で変更: 上記 を参照。
- winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)¶
指定されたキーを削除します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
sub_key は key 引数によって指定された key の subkey でなければなりません。この値は
Noneであってはなりません。また、key は subkey を持たないかもしれません。reserved は予約された整数で、 0 でなくてはなりません。デフォルト値は 0 です。
access は、 key に対して想定されるセキュリティアクセスを示すアクセスマスクを指定する整数です。デフォルトは
KEY_WOW64_64KEYです。32 bit Windows では、WOW64 定数は無視されます。その他の利用可能な値については アクセス権 を参照してください。このメソッドはサブキーをもつキーを削除することはできません。
このメソッドの実行が成功すると、キー全体が、その値すべてを含めて削除されます。このメソッドが失敗した場合、
OSError例外が送出されます。サポートされていない Windows バージョンでは、
NotImplementedError例外を発生させます。Raises an auditing event
winreg.DeleteKeywith argumentskey,sub_key,access.Added in version 3.2.
バージョン 3.3 で変更: 上記 を参照。
- winreg.DeleteValue(key, value)¶
レジストリキーから指定された名前つきの値を削除します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
value は削除したい値を指定するための文字列です。
引数
key,valueを指定して 監査イベントwinreg.DeleteValueを送出します。
- winreg.EnumKey(key, index)¶
開かれているレジストリキーのサブキーを列挙し、文字列で返します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
index は整数値で、取得するキーのインデクスを指定します。
この関数は、呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す
OSError例外が送出されるまで繰り返し呼び出されます。引数
key,indexを指定して 監査イベントwinreg.EnumKeyを送出します。バージョン 3.3 で変更: 上記 を参照。
- winreg.EnumValue(key, index)¶
開かれているレジストリキーの値を列挙し、タプルで返します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
index は整数値で、取得する値のインデクスを指定します。
この関数は、呼び出されるたびに一つのサブキーの名前を取得します。この関数は通常、これ以上値がないことを示す
OSError例外が送出されるまで繰り返し呼び出されます。結果は 3 要素のタプルになります:
インデックス
意味
0値の名前を指定する文字列
1値のデータを保持するためのオブジェクトで、その型は背後のレジストリ型に依存します
2値のデータ型を指定する整数です (
SetValueEx()のドキュメント内のテーブルを参照してください)引数
key,indexを指定して 監査イベントwinreg.EnumValueを送出します。バージョン 3.3 で変更: 上記 を参照。
- winreg.ExpandEnvironmentStrings(str)¶
REG_EXPAND_SZのように、環境変数プレースホルダ%NAME%を文字列で展開します:>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
引数
strを指定して 監査イベントwinreg.ExpandEnvironmentStringsを送出します。
- 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) ファイルシステム下では、ファイル名は拡張子を持っていてはなりません。A call to
LoadKey()fails if the calling process does not have theSE_RESTORE_PRIVILEGEprivilege. Note that privileges are different from permissions -- see the RegLoadKey documentation for more details.key が
ConnectRegistry()によって返されたハンドルの場合、 file_name に指定されたパスはリモートコンピュータに対する相対パス名になります。引数
key,sub_key,file_nameを指定して 監査イベントwinreg.LoadKeyを送出します。
- 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が送出されます。引数
key,sub_key,accessを指定して 監査イベントwinreg.OpenKeyを送出します。引数
keyを指定して 監査イベントwinreg.OpenKey/resultを送出します。バージョン 3.2 で変更: 名前付き引数が使用できるようになりました。
バージョン 3.3 で変更: 上記 を参照。
- winreg.QueryInfoKey(key)¶
キーに関する情報をタプルとして返します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
結果は 3 要素のタプルになります:
インデックス
意味
0このキーが持つサブキーの数を表す整数。
1このキーが持つ値の数を表す整数。
2最後のキーの変更が (あれば) いつだったかを表す整数で、1601 年 1 月 1 日からの 100 ナノ秒単位で数えたもの。
引数
keyを指定して 監査イベントwinreg.QueryInfoKeyを送出します。
- winreg.QueryValue(key, sub_key)¶
キーに対する、名前付けられていない値を文字列で取得します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
sub_key は値が関連付けられているサブキーの名前を保持する文字列です。この引数が
Noneまたは空文字列の場合、この関数は key で指定されたキーに対してSetValue()メソッドで設定された値を取得します。レジストリ中の値は名前、型、およびデータから構成されています。このメソッドはあるキーのデータ中で、名前
NULLをもつ最初の値を取得します。しかし背後のAPI 呼び出しは型情報を返しません。なので、可能ならいつでもQueryValueEx()を使うべきです。引数
key,sub_key,value_nameを指定して 監査イベントwinreg.QueryValueを送出します。
- winreg.QueryValueEx(key, value_name)¶
開かれたレジストリキーに関連付けられている、指定した名前の値に対して、型およびデータを取得します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
value_name は要求する値を指定する文字列です。
結果は 2 つの要素からなるタプルです:
インデックス
意味
0レジストリ要素の値。
1この値のレジストリ型を表す整数。 (
SetValueEx()のドキュメント内のテーブルを参照してください。)引数
key,sub_key,value_nameを指定して 監査イベントwinreg.QueryValueを送出します。
- winreg.SaveKey(key, file_name)¶
指定されたキーと、そのサブキー全てを指定したファイルに保存します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
file_name はレジストリデータを保存するファイルの名前です、このファイルはすでに存在していてはいけません。このファイル名が拡張子を含んでいる場合、
LoadKey()メソッドは、FAT ファイルシステムを使うことができません。If key represents a key on a remote computer, the path described by file_name is relative to the remote computer. The caller of this method must possess the SeBackupPrivilege security privilege. Note that privileges are different than permissions -- see the Conflicts Between User Rights and Permissions documentation for more details.
この関数は security_attributes を
NULLにして API に渡します。引数
key,file_nameを指定して 監査イベントwinreg.SaveKeyを送出します。
- winreg.SetValue(key, sub_key, type, value)¶
値を指定したキーに関連付けます。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
sub_key は値が関連付けられているサブキーの名前を表す文字列です。
type はデータの型を指定する整数です。現状では、この値は
REG_SZでなければならず、これは文字列だけがサポートされていることを示します。他のデータ型をサポートするにはSetValueEx()を使ってください。value は新たな値を指定する文字列です。
sub_key 引数で指定されたキーが存在しなければ、SetValue 関数で生成されます。
値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。
key 引数に指定されたキーは
KEY_SET_VALUEアクセスで開かれていなければなりません。引数
key,sub_key,type,valueを指定して 監査イベントwinreg.SetValueを送出します。
- winreg.SetValueEx(key, value_name, reserved, type, value)¶
開かれたレジストリキーの値フィールドにデータを記録します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
value_name は値が関連付けられているサブキーの名前を表す文字列です。
reserved は何もしません - API には常にゼロが渡されます。
type はデータの型を指定する整数です。利用できる型については 値の型 を参照してください。
value は新たな値を指定する文字列です。
このメソッドではまた、指定されたキーに対して、さらに別の値や型情報を設定することができます。 key 引数で指定されたキーは
KEY_SET_VALUEアクセスで開かれていなければなりません。キーを開くには、
CreateKey()またはOpenKey()メソッドを使ってください。値の長さは利用可能なメモリによって制限されます。(2048 バイト以上の) 長い値はファイルに保存して、そのファイル名を設定レジストリに保存するべきです。そうすればレジストリを効率的に動作させる役に立ちます。
引数
key,sub_key,type,valueを指定して 監査イベントwinreg.SetValueを送出します。
- winreg.DisableReflectionKey(key)¶
64ビット OS上で動作している 32bit プロセスに対するレジストリリフレクションを無効にします。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
32bit OS上では一般的に
NotImplementedError例外を発生させます。key がリフレクションリストに無い場合は、この関数は成功しますが効果はありません。あるキーのリフレクションを無効にしても、そのキーのサブキーのリフレクションには全く影響しません。
引数
keyを指定して 監査イベントwinreg.DisableReflectionKeyを送出します。
- winreg.EnableReflectionKey(key)¶
指定された、リフレクションが無効にされたキーのリフレクションを再び有効にします。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
32bit OS上では一般的に
NotImplementedError例外を発生させます。あるキーのリフレクションを再開しても、その全てのサブキーには影響しません。
引数
keyを指定して 監査イベントwinreg.EnableReflectionKeyを送出します。
- winreg.QueryReflectionKey(key)¶
指定されたキーのリフレクション状態を確認します。
key はすでに開かれたキーか、既定の HKEY_* 定数 のうちの一つです。
リフレクションが無効になっている場合、
Trueを返します。32bit OS上では一般的に
NotImplementedError例外を発生させます。引数
keyを指定して 監査イベントwinreg.QueryReflectionKeyを送出します。
定数¶
The following constants are defined for use in many winreg functions.
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 以降のバージョンでは利用されていません。
アクセス権限¶
より詳しい情報については、 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_QUERY_VALUE¶
レジストリキーの値を問い合わせるのに必要。
- winreg.KEY_SET_VALUE¶
レジストリの値を作成、削除、設定するのに必要。
- winreg.KEY_CREATE_SUB_KEY¶
レジストリキーのサブキーを作るのに必要。
- winreg.KEY_ENUMERATE_SUB_KEYS¶
レジストリキーのサブキーを列挙するのに必要。
- winreg.KEY_NOTIFY¶
レジストリキーやそのサブキーに対する変更通知を要求するのに必要。
- winreg.KEY_CREATE_LINK¶
システムでの利用のために予約されている。
64-bit 特有のアクセス権¶
より詳しい情報については、 Accessing an Alternate Registry View を参照してください。
- winreg.KEY_WOW64_64KEY¶
64 bit Windows 上のアプリケーションが、64 bit のレジストリビュー上で操作する事を示します。32 bit Windows では、この定数は無視されます。
- winreg.KEY_WOW64_32KEY¶
64 bit Windows 上のアプリケーションが、32 bit のレジストリビュー上で操作する事を示します。32 bit Windows では、この定数は無視されます。
値の型¶
より詳しい情報については、 Registry Value Types を参照してください。
- winreg.REG_BINARY¶
何らかの形式のバイナリデータ。
- winreg.REG_DWORD¶
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_QWORD¶
64 ビットの数。
Added in version 3.6.
- winreg.REG_RESOURCE_LIST¶
デバイスドライバリソースのリスト。
- winreg.REG_FULL_RESOURCE_DESCRIPTOR¶
ハードウェアセッティング。
- winreg.REG_RESOURCE_REQUIREMENTS_LIST¶
ハードウェアリソースリスト。
- winreg.REG_SZ¶
ヌル文字で終端された文字列。
レジストリハンドルオブジェクト¶
このオブジェクトは Windows の HKEY オブジェクトをラップし、オブジェクトが破壊されたときに自動的にハンドルを閉じます。オブジェクトの Close() メソッドと CloseKey() 関数のどちらも、後始末がきちんと行われることを保証するために呼び出すことができます。
このモジュールのレジストリ関数は全て、これらのハンドルオブジェクトの一つを返します。
このモジュールのレジストリ関数でハンドルオブジェクトを受理するものは全て整数も受理しますが、ハンドルオブジェクトを利用することを推奨します。
Handle objects provide semantics for __bool__() -- thus
if handle:
print("Yes")
は、ハンドルが現在有効な (閉じられたり切り離されたりしていない) 場合には Yes となります。
ハンドルオブジェクトは、比較の意味構成もサポートしています。このため、複数のハンドルオブジェクトが参照している下層の Windows ハンドル値が同じ場合、それらのハンドルオブジェクト同士の比較は真になります。
ハンドルオブジェクトは (例えば組み込みの int() 関数を使って) 整数に変換することができます。この場合、背後の Windows ハンドル値が返されます、また、 Detach() メソッドを使って整数のハンドル値を返させると同時に、ハンドルオブジェクトから Windows ハンドルを切り離すこともできます。
- PyHKEY.Close()¶
背後の Windows ハンドルを閉じます。
ハンドルがすでに閉じられていてもエラーは送出されません。
- PyHKEY.Detach()¶
ハンドルオブジェクトから Windows ハンドルを切り離します。
切り離される以前にそのハンドルを保持していた整数オブジェクトが返されます。ハンドルがすでに切り離されていたり閉じられていたりした場合、ゼロが返されます。
この関数を呼び出した後、ハンドルは確実に無効化されますが、閉じられるわけではありません。背後の Win32 ハンドルがハンドルオブジェクトよりも長く維持される必要がある場合にはこの関数を呼び出すとよいでしょう。
Raises an auditing event
winreg.PyHKEY.Detachwith argumentkey.
- PyHKEY.__enter__()¶
- PyHKEY.__exit__(*exc_info)¶
HKEY オブジェクトは
__enter__(),__exit__()メソッドを実装していて、with文のためのコンテキストプロトコルをサポートしています:with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key: ... # work with key
このコードは、
withブロックから抜けるときに自動的に key を閉じます。