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

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

winreg.KEY_CREATE_LINK

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


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

   32 ビットのリトルエンディアン形式の数。"REG_DWORD" と等価。

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 ビットの数。

   バージョン 3.6 で追加.

winreg.REG_QWORD_LITTLE_ENDIAN

   64 ビットのリトルエンディアン形式の数。"REG_QWORD" と等価。

   バージョン 3.6 で追加.

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* を閉じ
   ます。
