winreg — Windows 레지스트리 접근

이 모듈의 함수들은 Windows 레지스트리 API를 Python에 노출해요. 레지스트리 핸들로 정수를 쓰는 대신 핸들 객체를 사용해, 프로그래머가 명시적으로 닫는 것을 잊어도 핸들이 올바르게 닫히도록 보장합니다.

출처: Python 표준 라이브러리

사용 가능 환경: Windows.

버전 3.3에서 변경: 이 모듈의 여러 함수가 WindowsError를 일으키곤 했는데, 지금은 OSError의 별칭입니다.

본문

함수 (Functions)

이 모듈은 다음 함수를 제공합니다.

winreg.CloseKey(hkey)

이전에 열린 레지스트리 키를 닫습니다. hkey 인자는 이전에 연 키를 지정해요.

참고 — 이 메서드(또는 hkey.Close())로 닫지 않으면 hkey 객체가 Python에 의해 파괴될 때 닫힙니다.

winreg.ConnectRegistry(computer_name, key)

다른 컴퓨터의 미리 정의된 레지스트리 핸들에 연결을 설정하고 핸들 객체를 반환합니다. computer_name은 r"\\computername" 형태의 원격 컴퓨터 이름이에요. None이면 로컬 컴퓨터를 사용합니다. key는 연결할 미리 정의된 핸들이에요. 반환 값은 열린 키의 핸들입니다. 함수가 실패하면 OSError 예외가 발생합니다. 감사 이벤트 winreg.ConnectRegistry를 인자 computer_name, key로 발생시킵니다.

winreg.CreateKey(key, sub_key)

지정한 키를 만들거나 열어 핸들 객체를 반환합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. sub_key는 이 메서드가 열거나 만드는 키의 이름을 나타내는 문자열입니다. key가 미리 정의된 키 중 하나면 sub_key는 None일 수 있으며, 그 경우 반환되는 핸들은 함수에 넘긴 키 핸들과 같아요. 키가 이미 존재하면 이 함수는 기존 키를 엽니다. 반환 값은 열린 키의 핸들이고, 실패 시 OSError 예외가 발생합니다. 감사 이벤트 winreg.CreateKey(인자 key, sub_key, access)와 winreg.OpenKey/result(인자 key)를 발생시킵니다.

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

지정한 키를 만들거나 열어 핸들 객체를 반환합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. sub_key는 키 이름을 나타내는 문자열입니다. reserved는 예약 정수로 0이어야 하며 기본은 0입니다. access는 키에 대한 원하는 보안 접근을 설명하는 접근 마스크를 지정하는 정수이며 기본은 KEY_WRITE예요. key가 미리 정의된 키 중 하나면 sub_key는 None일 수 있습니다. 키가 이미 존재하면 기존 키를 엽니다. 반환 값은 열린 키의 핸들이고, 실패 시 OSError 예외가 발생합니다. 감사 이벤트 winreg.CreateKey(인자 key, sub_key, access)와 winreg.OpenKey/result(인자 key)를 발생시킵니다. (버전 3.2에서 추가)

winreg.DeleteKey(key, sub_key)

지정한 키를 삭제합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. sub_key는 key 매개변수가 식별하는 키의 하위 키여야 하는 문자열입니다. 이 값은 None이면 안 되며, 키는 하위 키를 가질 수 없습니다. 이 메서드는 하위 키가 있는 키를 삭제할 수 없어요. 성공하면 값까지 포함한 키 전체가 제거되고, 실패하면 OSError 예외가 발생합니다. 감사 이벤트 winreg.DeleteKey(인자 key, sub_key, access)를 발생시킵니다.

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

지정한 키를 삭제합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. sub_key는 하위 키여야 하는 문자열이며 None이면 안 되고 키는 하위 키를 가질 수 없습니다. reserved는 예약 정수로 0이어야 하며 기본은 0입니다. access는 원하는 보안 접근을 설명하는 접근 마스크 정수이며 기본은 KEY_WOW64_64KEY예요. 32비트 Windows에서는 WOW64 상수가 무시됩니다. 이 메서드는 하위 키가 있는 키를 삭제할 수 없습니다. 성공하면 키 전체가 제거되고, 실패하면 OSError 예외가 발생합니다. 지원되지 않는 Windows 버전에서는 NotImplementedError가 발생합니다. 감사 이벤트 winreg.DeleteKey를 발생시킵니다. (버전 3.2에서 추가)

winreg.DeleteValue(key, value)

레지스트리 키에서 명명된 값을 제거합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나이고, value는 제거할 값을 식별하는 문자열입니다. 감사 이벤트 winreg.DeleteValue(인자 key, value)를 발생시킵니다.

winreg.EnumKey(key, index)

열린 레지스트리 키의 하위 키를 열거해 문자열을 반환합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나이고, index는 가져올 키의 인덱스를 식별하는 정수입니다. 이 함수는 호출할 때마다 하위 키 하나의 이름을 가져와요. 보통 더 이상 값을 사용할 수 없음을 나타내는 OSError 예외가 발생할 때까지 반복 호출됩니다. 감사 이벤트 winreg.EnumKey(인자 key, index)를 발생시킵니다.

winreg.EnumValue(key, index)

열린 레지스트리 키의 값을 열거해 튜플을 반환합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나이고, index는 가져올 값의 인덱스를 식별하는 정수입니다. 이 함수는 호출할 때마다 값 하나를 가져오며, 보통 더 이상 값이 없음을 나타내는 OSError 예외까지 반복 호출됩니다. 결과는 3개 항목의 튜플입니다.

인덱스	의미
0	값 이름을 식별하는 문자열
1	값 데이터를 담고 그 타입이 기본 레지스트리 타입에 따라 달라지는 객체
2	값 데이터의 타입을 식별하는 정수 (SetValueEx() 문서 표 참고)

감사 이벤트 winreg.EnumValue(인자 key, index)를 발생시킵니다.

winreg.ExpandEnvironmentStrings(str)

REG_EXPAND_SZ 같은 문자열에서 환경 변수 플레이스홀더 %NAME%을 확장합니다.

>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'

감사 이벤트 winreg.ExpandEnvironmentStrings(인자 str)를 발생시킵니다.

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() 호출이 실패합니다. 권한은 허가(permission)와 다르다는 점을 알아 두세요. key가 ConnectRegistry()가 반환한 핸들이면 file_name에 지정된 경로는 원격 컴퓨터 기준입니다. 감사 이벤트 winreg.LoadKey(인자 key, sub_key, 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_READ입니다. 결과는 지정한 키에 대한 새 핸들이에요. 실패하면 OSError가 발생합니다. 감사 이벤트 winreg.OpenKey(인자 key, sub_key, access)와 winreg.OpenKey/result(인자 key)를 발생시킵니다. (버전 3.2에서 변경: 명명된 인자 사용 허용)

winreg.QueryInfoKey(key)

키에 대한 정보를 튜플로 반환합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. 결과는 3개 항목의 튜플입니다.

인덱스	의미
0	이 키가 가진 하위 키 수를 주는 정수
1	이 키가 가진 값 수를 주는 정수
2	키가 마지막으로 수정된 시각(가능할 때)을 1601년 1월 1일부터 100나노초 수로 주는 정수

감사 이벤트 winreg.QueryInfoKey(인자 key)를 발생시킵니다.

winreg.QueryValue(key, sub_key)

키의 이름 없는 값을 문자열로 가져옵니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. sub_key는 값이 연결된 하위 키의 이름을 담은 문자열입니다. 이 매개변수가 None이거나 비어 있으면, 함수는 key가 식별하는 키에 SetValue() 메서드가 설정한 값을 가져옵니다. 레지스트리의 값은 이름, 타입, 데이터 구성 요소를 가져요. 이 메서드는 키의 NULL 이름을 가진 첫 값의 데이터를 가져옵니다. 그러나 기본 API 호출이 타입을 반환하지 않으므로 가능하면 항상 QueryValueEx()를 사용하세요. 감사 이벤트 winreg.QueryValue(인자 key, sub_key, value_name)를 발생시킵니다.

winreg.QueryValueEx(key, value_name)

열린 레지스트리 키와 연결된 지정한 값 이름의 타입과 데이터를 가져옵니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나이고, value_name은 조회할 값을 나타내는 문자열입니다. 결과는 2개 항목의 튜플입니다.

인덱스	의미
0	레지스트리 항목의 값
1	이 값의 레지스트리 타입을 주는 정수 (SetValueEx() 문서 표 참고)

감사 이벤트 winreg.QueryValue(인자 key, sub_key, value_name)를 발생시킵니다.

winreg.SaveKey(key, file_name)

지정한 키와 그 모든 하위 키를 지정한 파일에 저장합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. file_name은 레지스트리 데이터를 저장할 파일의 이름입니다. 이 파일은 이미 존재할 수 없어요. 이 파일 이름에 확장자가 포함되면 파일 할당 테이블(FAT) 파일시스템에서는 LoadKey() 메서드로 사용할 수 없습니다. key가 원격 컴퓨터의 키를 나타내면 file_name이 설명하는 경로는 원격 컴퓨터 기준입니다. 호출자는 SeBackupPrivilege 보안 권한을 가져야 해요. 이 함수는 security_attributes에 NULL을 API에 전달합니다. 감사 이벤트 winreg.SaveKey(인자 key, file_name)를 발생시킵니다.

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.SetValue(인자 key, sub_key, type, value)를 발생시킵니다.

winreg.SetValueEx(key, value_name, reserved, type, value)

열린 레지스트리 키의 값 필드에 데이터를 저장합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. value_name은 값이 연결된 하위 키의 이름을 나타내는 문자열입니다. reserved는 무엇이든 될 수 있으며 0이 항상 API에 전달됩니다. type은 데이터 타입을 지정하는 정수입니다 (사용 가능한 타입은 Value Types 참고). value는 새 값을 지정하는 문자열이에요. 이 메서드는 지정한 키에 대한 추가 값·타입 정보도 설정할 수 있습니다. key가 식별하는 키는 KEY_SET_VALUE 접근으로 열려 있어야 해요. 키를 열려면 CreateKey()나 OpenKey() 메서드를 사용하세요. 값 길이는 사용 가능한 메모리에 의해 제한되며, 긴 값(2048바이트 초과)은 파일로 저장해 파일 이름을 구성 레지스트리에 저장해야 합니다. 감사 이벤트 winreg.SetValue를 발생시킵니다.

winreg.DisableReflectionKey(key)

64비트 운영체제에서 실행되는 32비트 프로세스를 위한 레지스트리 반사(reflection)를 비활성화합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. 32비트 운영체제에서 실행하면 일반적으로 NotImplementedError가 발생합니다. 키가 반사 목록에 없으면 함수는 성공하지만 효과가 없습니다. 키의 반사를 비활성화해도 하위 키의 반사에는 영향이 없습니다. 감사 이벤트 winreg.DisableReflectionKey(인자 key)를 발생시킵니다.

winreg.EnableReflectionKey(key)

지정한 비활성화된 키에 대해 레지스트리 반사를 복원합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. 32비트 운영체제에서 실행하면 일반적으로 NotImplementedError가 발생합니다. 키의 반사 복원은 하위 키의 반사에 영향을 주지 않아요. 감사 이벤트 winreg.EnableReflectionKey(인자 key)를 발생시킵니다.

winreg.QueryReflectionKey(key)

지정한 키의 반사 상태를 결정합니다. key는 이미 열린 키 또는 미리 정의된 HKEY_* 상수 중 하나예요. 반사가 비활성화되어 있으면 True를 반환합니다. 32비트 운영체제에서 실행하면 일반적으로 NotImplementedError가 발생해요. 감사 이벤트 winreg.QueryReflectionKey(인자 key)를 발생시킵니다.

상수 (Constants)

다음 상수는 많은 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 — 이 키는 Windows 98 이후 버전에서는 사용되지 않습니다.

접근 권한 (Access Rights)

자세한 내용은 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비트 특정 (64-bit Specific)

자세한 내용은 Accessing an Alternate Registry View를 참고하세요.

winreg.KEY_WOW64_64KEY — 64비트 Windows의 애플리케이션이 64비트 레지스트리 뷰에서 동작해야 함을 나타냅니다. 32비트 Windows에서는 이 상수가 무시됩니다.
winreg.KEY_WOW64_32KEY — 64비트 Windows의 애플리케이션이 32비트 레지스트리 뷰에서 동작해야 함을 나타냅니다. 32비트 Windows에서는 이 상수가 무시됩니다.

값 타입 (Value Types)

자세한 내용은 Registry Value Types를 참고하세요.

winreg.REG_BINARY — 어떤 형태든 바이너리 데이터.
winreg.REG_DWORD — 32비트 숫자.
winreg.REG_DWORD_LITTLE_ENDIAN — little-endian 형식의 32비트 숫자. REG_DWORD와 동등.
winreg.REG_DWORD_BIG_ENDIAN — big-endian 형식의 32비트 숫자.
winreg.REG_EXPAND_SZ — 환경 변수(%PATH%)에 대한 참조를 담는 null 종료 문자열.
winreg.REG_LINK — Unicode 심볼릭 링크.
winreg.REG_MULTI_SZ — 두 개의 null 문자로 끝나는 null 종료 문자열 시퀀스. (Python이 이 종료를 자동으로 처리합니다)
winreg.REG_NONE — 정의된 값 타입 없음.
winreg.REG_QWORD — 64비트 숫자. (버전 3.6에서 추가)
winreg.REG_QWORD_LITTLE_ENDIAN — little-endian 형식의 64비트 숫자. REG_QWORD와 동등. (버전 3.6에서 추가)
winreg.REG_RESOURCE_LIST — 디바이스 드라이버 리소스 목록.
winreg.REG_FULL_RESOURCE_DESCRIPTOR — 하드웨어 설정.
winreg.REG_RESOURCE_REQUIREMENTS_LIST — 하드웨어 리소스 목록.
winreg.REG_SZ — null 종료 문자열.

레지스트리 핸들 객체 (Registry Handle Objects)

이 객체는 Windows HKEY 객체를 감싸며, 객체가 파괴될 때 자동으로 닫습니다. 정리를 보장하려면 객체의 Close() 메서드나 CloseKey() 함수를 호출하면 돼요.

이 모듈의 모든 레지스트리 함수는 이 객체 중 하나를 반환합니다. 이 모듈에서 핸들 객체를 받는 모든 레지스트리 함수는 정수도 받지만, 핸들 객체 사용을 권장해요.

핸들 객체는 __bool__() 의미를 제공합니다. 그래서 다음은 핸들이 현재 유효하면(닫히거나 분리되지 않았으면) Yes를 출력해요.

if handle:
    print("Yes")

핸들 객체는 정수로 변환할 수 있는데(예: 내장 int() 함수 사용), 그 경우 기본 Windows 핸들 값이 반환됩니다. Detach() 메서드로 정수 핸들을 반환하면서 Windows 핸들에서 핸들 객체를 분리할 수도 있어요.

PyHKEY.Close()

기본 Windows 핸들을 닫습니다. 핸들이 이미 닫혀 있으면 오류가 발생하지 않습니다.

PyHKEY.Detach()

핸들 객체에서 Windows 핸들을 분리합니다. 결과는 분리되기 전 핸들의 값을 담은 정수예요. 핸들이 이미 분리되었거나 닫혀 있으면 0을 반환합니다. 이 함수를 호출한 뒤 핸들은 실질적으로 무효화되지만 닫히지는 않습니다. 기본 Win32 핸들이 핸들 객체의 수명을 넘어 존재해야 할 때 이 함수를 호출해요. 감사 이벤트 winreg.PyHKEY.Detach(인자 key)를 발생시킵니다.

PyHKEY.enter()

PyHKEY.exit(*exc_info)

HKEY 객체는 __enter__()와 __exit__()를 구현하므로 with 문의 콘텍스트 프로토콜을 지원합니다.

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

는 제어가 with 블록을 떠날 때 key를 자동으로 닫습니다.