winreg —Windowsレジストリアクセス
これらの関数は、WindowsレジストリAPIをPythonに公開します。 レジストリハンドルとして整数を使用する代わりに、ハンドルオブジェクトを使用して、プログラマーがハンドルを明示的に閉じることを怠った場合でも、ハンドルが正しく閉じられるようにします。
バージョン3.3で変更:このモジュールのいくつかの関数は、 WindowsError を発生させるために使用されていました。これは、 OSError のエイリアスになりました。
関数
このモジュールは、次の機能を提供します。
- winreg.CloseKey(hkey)
以前に開いたレジストリキーを閉じます。 hkey 引数は、以前に開いたキーを指定します。
ノート
hkey がこのメソッドを使用して(または hkey.Close()を介して)閉じられていない場合、 hkey オブジェクトがPythonによって破棄されたときに閉じられます。
- winreg.ConnectRegistry(computer_name, key)
別のコンピューター上の事前定義されたレジストリハンドルへの接続を確立し、ハンドルオブジェクトを返します。
computer_name は、
r"\\computername"
の形式のリモートコンピューターの名前です。None
の場合、ローカルコンピューターが使用されます。key は、接続するための事前定義されたハンドルです。
戻り値は、開いたキーのハンドルです。 関数が失敗すると、 OSError 例外が発生します。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.CreateKey(key, sub_key)
指定されたキーを作成または開き、ハンドルオブジェクトを返します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
sub_key は、このメソッドが開くまたは作成するキーに名前を付ける文字列です。
key が事前定義されたキーの1つである場合、 sub_key は
None
である可能性があります。 その場合、返されるハンドルは、関数に渡されたものと同じキーハンドルです。キーがすでに存在する場合、この関数は既存のキーを開きます。
戻り値は、開いたキーのハンドルです。 関数が失敗すると、 OSError 例外が発生します。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.CreateKeyEx(key, sub_key, reserved=0, access=KEY_WRITE)
指定されたキーを作成または開き、ハンドルオブジェクトを返します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
sub_key は、このメソッドが開くまたは作成するキーに名前を付ける文字列です。
reserved は予約済みの整数であり、ゼロでなければなりません。 デフォルトはゼロです。
access は、キーに必要なセキュリティアクセスを説明するアクセスマスクを指定する整数です。 デフォルトは KEY_WRITE です。 その他の許可される値については、アクセス権を参照してください。
key が事前定義されたキーの1つである場合、 sub_key は
None
である可能性があります。 その場合、返されるハンドルは、関数に渡されたものと同じキーハンドルです。キーがすでに存在する場合、この関数は既存のキーを開きます。
戻り値は、開いたキーのハンドルです。 関数が失敗すると、 OSError 例外が発生します。
バージョン3.2の新機能。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.DeleteKey(key, sub_key)
指定されたキーを削除します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
sub_key は、 key パラメーターで識別されるキーのサブキーでなければならない文字列です。 この値は
None
であってはならず、キーにサブキーを含めることはできません。このメソッドは、サブキーを持つキーを削除できません。
メソッドが成功すると、すべての値を含むキー全体が削除されます。 メソッドが失敗すると、 OSError 例外が発生します。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.DeleteKeyEx(key, sub_key, access=KEY_WOW64_64KEY, reserved=0)
指定されたキーを削除します。
ノート
DeleteKeyEx()関数は、64ビットバージョンのWindowsに固有のRegDeleteKeyEx WindowsAPI関数で実装されます。 RegDeleteKeyExのドキュメントを参照してください。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
sub_key は、 key パラメーターで識別されるキーのサブキーでなければならない文字列です。 この値は
None
であってはならず、キーにサブキーを含めることはできません。reserved は予約済みの整数であり、ゼロでなければなりません。 デフォルトはゼロです。
access は、キーに必要なセキュリティアクセスを説明するアクセスマスクを指定する整数です。 デフォルトは KEY_WOW64_64KEY です。 その他の許可される値については、アクセス権を参照してください。
このメソッドは、サブキーを持つキーを削除できません。
メソッドが成功すると、すべての値を含むキー全体が削除されます。 メソッドが失敗すると、 OSError 例外が発生します。
サポートされていないWindowsバージョンでは、 NotImplementedError が発生します。
バージョン3.2の新機能。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.DeleteValue(key, value)
レジストリキーから名前付きの値を削除します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
value は、削除する値を識別する文字列です。
- winreg.EnumKey(key, index)
開いているレジストリキーのサブキーを列挙し、文字列を返します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
index は、取得するキーのインデックスを識別する整数です。
この関数は、呼び出されるたびに1つのサブキーの名前を取得します。 通常、 OSError 例外が発生して、使用可能な値がなくなるまで繰り返し呼び出されます。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.EnumValue(key, index)
開いているレジストリキーの値を列挙し、タプルを返します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
index は、取得する値のインデックスを識別する整数です。
この関数は、呼び出されるたびに1つのサブキーの名前を取得します。 これは通常、 OSError 例外が発生して値がなくなるまで、繰り返し呼び出されます。
結果は、3つのアイテムのタプルになります。
索引
意味
0
値の名前を識別する文字列
1
値データを保持し、そのタイプが基になるレジストリタイプに依存するオブジェクト
2
値データのタイプを識別する整数( SetValueEx()についてはドキュメントの表を参照してください)
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.ExpandEnvironmentStrings(str)
REG_EXPAND_SZ のような文字列で環境変数プレースホルダー
%NAME%
を展開します。>>> ExpandEnvironmentStrings('%windir%') 'C:\\Windows'
- winreg.FlushKey(key)
キーのすべての属性をレジストリに書き込みます。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
キーを変更するために FlushKey()を呼び出す必要はありません。 レジストリの変更は、レイジーフラッシャーを使用してレジストリによってディスクにフラッシュされます。 レジストリの変更も、システムのシャットダウン時にディスクにフラッシュされます。 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のドキュメントを参照してください。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_ *定数の1つです。
sub_key は、開くsub_keyを識別する文字列です。
reserved は予約済みの整数であり、ゼロでなければなりません。 デフォルトはゼロです。
access は、キーに必要なセキュリティアクセスを説明するアクセスマスクを指定する整数です。 デフォルトは KEY_READ です。 その他の許可される値については、アクセス権を参照してください。
結果は、指定されたキーへの新しいハンドルです。
関数が失敗すると、 OSError が発生します。
バージョン3.2で変更:名前付き引数の使用を許可します。
バージョン3.3で変更:上記の [[#exception-changed|]] を参照してください。
- winreg.QueryInfoKey(key)
キーに関する情報をタプルとして返します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
結果は、3つのアイテムのタプルになります。
索引
意味
0
このキーが持つサブキーの数を示す整数。
1
このキーが持つ値の数を示す整数。
2
1601年1月1日以降、キーが最後に変更された日時(使用可能な場合)を数百ナノ秒として示す整数。
- winreg.QueryValue(key, sub_key)
キーの名前のない値を文字列として取得します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
sub_key は、値が関連付けられているサブキーの名前を保持する文字列です。 このパラメーターが
None
または空の場合、関数は key で識別されるキーの SetValue()メソッドで設定された値を取得します。レジストリの値には、名前、タイプ、およびデータコンポーネントがあります。 このメソッドは、
NULL
名を持つキーの最初の値のデータを取得します。 ただし、基になるAPI呼び出しは型を返さないため、可能であれば常に QueryValueEx()を使用してください。
- winreg.QueryValueEx(key, value_name)
開いているレジストリキーに関連付けられている指定された値の名前のタイプとデータを取得します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
value_name は、照会する値を示す文字列です。
結果は2つのアイテムのタプルになります。
索引
意味
0
レジストリ項目の値。
1
この値のレジストリタイプを示す整数( SetValueEx()についてはドキュメントの表を参照してください)
- winreg.SaveKey(key, file_name)
指定されたキーとそのすべてのサブキーを指定されたファイルに保存します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
file_name は、レジストリデータを保存するファイルの名前です。 このファイルはまだ存在できません。 このファイル名に拡張子が含まれている場合、 LoadKey()メソッドによるファイルアロケーションテーブル(FAT)ファイルシステムでは使用できません。
key がリモートコンピューター上のキーを表す場合、 file_name で記述されたパスはリモートコンピューターを基準にしています。 このメソッドの呼び出し元は、
SeBackupPrivilege
セキュリティ特権を持っている必要があります。 権限は権限とは異なることに注意してください。詳細については、ユーザー権限と権限の競合に関するドキュメントを参照してください。この関数は、 security_attributes の
NULL
をAPIに渡します。
- winreg.SetValue(key, sub_key, type, value)
値を指定されたキーに関連付けます。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
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_ *定数の1つです。
value_name は、値が関連付けられているサブキーに名前を付ける文字列です。
reserved は何でもかまいません–常にゼロがAPIに渡されます。
type は、データのタイプを指定する整数です。 使用可能なタイプについては、値タイプを参照してください。
value は、新しい値を指定する文字列です。
このメソッドは、指定されたキーの追加の値とタイプ情報を設定することもできます。 keyパラメーターで識別されるキーは、 KEY_SET_VALUE アクセスで開かれている必要があります。
キーを開くには、 CreateKey()または OpenKey()メソッドを使用します。
値の長さは、使用可能なメモリによって制限されます。 長い値(2048バイトを超える)は、構成レジストリに保存されているファイル名とともにファイルとして保存する必要があります。 これにより、レジストリが効率的に実行されます。
- winreg.DisableReflectionKey(key)
64ビットオペレーティングシステムで実行されている32ビットプロセスのレジストリリフレクションを無効にします。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
32ビットオペレーティングシステムで実行すると、通常 NotImplementedError が発生します。
キーがリフレクションリストにない場合、関数は成功しますが効果はありません。 キーのリフレクションを無効にしても、サブキーのリフレクションには影響しません。
- winreg.EnableReflectionKey(key)
指定された無効なキーのレジストリリフレクションを復元します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
32ビットオペレーティングシステムで実行すると、通常 NotImplementedError が発生します。
キーのリフレクションを復元しても、サブキーのリフレクションには影響しません。
- winreg.QueryReflectionKey(key)
指定されたキーの反射状態を決定します。
key は、すでに開いているキー、または事前定義された HKEY_ *定数の1つです。
リフレクションが無効になっている場合は、
True
を返します。32ビットオペレーティングシステムで実行すると、通常 NotImplementedError が発生します。
定数
次の定数は、多くの_winreg
関数で使用するために定義されています。
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
- このキーは、98以降のバージョンのWindowsでは使用されません。
アクセス権
詳細については、レジストリキーのセキュリティとアクセスを参照してください。
- winreg.KEY_ALL_ACCESS
- STANDARD_RIGHTS_REQUIRED、 KEY_QUERY_VALUE 、 KEY_SET_VALUE 、 KEY_CREATE_SUB_KEY 、 KEY_ENUMERATE_SUB_KEYS 、 KEY X195X]アクセス権。
- 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ビット固有
詳細については、代替レジストリビューへのアクセスを参照してください。
- winreg.KEY_WOW64_64KEY
- 64ビットWindows上のアプリケーションが64ビットレジストリビューで動作する必要があることを示します。
- winreg.KEY_WOW64_32KEY
- 64ビットWindows上のアプリケーションが32ビットレジストリビューで動作する必要があることを示します。
値型
詳細については、レジストリ値の種類を参照してください。
- 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
- 2つのヌル文字で終了するヌル終了文字列のシーケンス。 (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
- ヌル終了文字列。
レジストリハンドルオブジェクト
このオブジェクトは、Windows HKEYオブジェクトをラップし、オブジェクトが破棄されると自動的に閉じます。 クリーンアップを保証するには、オブジェクトの Close()メソッド、または CloseKey()関数のいずれかを呼び出すことができます。
このモジュールのすべてのレジストリ関数は、これらのオブジェクトの1つを返します。
ハンドルオブジェクトを受け入れるこのモジュールのすべてのレジストリ関数は整数も受け入れますが、ハンドルオブジェクトの使用をお勧めします。
ハンドルオブジェクトは__bool__()
のセマンティクスを提供します–したがって
if handle:
print("Yes")
ハンドルが現在有効である(閉じられていない、または切り離されていない)場合、Yes
を出力します。
オブジェクトは比較セマンティクスもサポートしているため、ハンドルオブジェクトが両方とも同じ基になるWindowsハンドル値を参照している場合、ハンドルオブジェクトはtrueと比較されます。
ハンドルオブジェクトは整数に変換できます(たとえば、組み込みの 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 ブロックを離れると、キーが自動的に閉じます。