# `winreg` --- Windows レジストリへのアクセス

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

Availability: Windows.

バージョン 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.DeleteKey` with arguments `key`, `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.DeleteKey` with arguments `key`, `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 the `SE_RESTORE_PRIVILEGE` privilege. 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_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

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

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

  Added in version 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

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

  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` となります。

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

PyHKEY.Close()

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

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

PyHKEY.Detach()

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

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

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

  Raises an auditing event `winreg.PyHKEY.Detach` with argument `key`.

PyHKEY.__enter__()
PyHKEY.__exit__(*exc_info)

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

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

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