winreg — Tillgång till Windows-registret

Dessa funktioner exponerar Windows register API för Python. Istället för att använda ett heltal som registerhandtag används ett handle object för att säkerställa att handtagen stängs korrekt, även om programmeraren struntar i att uttryckligen stänga dem.

Ändrad i version 3.3: Flera funktioner i den här modulen gav tidigare upphov till WindowsError, som nu är ett alias för OSError.

Funktioner

Denna modul erbjuder följande funktioner:

winreg.CloseKey(hkey)

Stänger en tidigare öppnad registernyckel. Argumentet hkey anger en tidigare öppnad nyckel.

Anteckning

Om hkey inte stängs med denna metod (eller via hkey.Close()), stängs det när hkey-objektet förstörs av Python.

winreg.ConnectRegistry(computer_name, key)

Upprättar en anslutning till ett fördefinierat registerhandtag på en annan dator och returnerar ett handle-objekt.

computer_name är namnet på fjärrdatorn, av formen r"\\computername". Om None används den lokala datorn.

key är det fördefinierade handtaget att ansluta till.

Returvärdet är handtaget för den öppnade nyckeln. Om funktionen misslyckas genereras ett OSError undantag.

Utlöser en auditing event winreg.ConnectRegistry med argumenten computer_name, key.

Ändrad i version 3.3: Se ovanför.

winreg.CreateKey(key, sub_key)

Skapar eller öppnar den angivna nyckeln och returnerar ett handle-objekt.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som namnger den nyckel som den här metoden öppnar eller skapar.

Om key är en av de fördefinierade nycklarna kan sub_key vara None. I så fall är det handtag som returneras samma nyckelhandtag som skickas till funktionen.

Om nyckeln redan finns, öppnar denna funktion den befintliga nyckeln.

Returvärdet är handtaget för den öppnade nyckeln. Om funktionen misslyckas genereras ett OSError undantag.

Utlöser en auditing event winreg.CreateKey med argumenten key, sub_key, access.

Utlöser en auditing event winreg.OpenKey/result med argumentet key.

Ändrad i version 3.3: Se ovanför.

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

Skapar eller öppnar den angivna nyckeln och returnerar ett handle-objekt.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som namnger den nyckel som den här metoden öppnar eller skapar.

reserved är ett reserverat heltal och måste vara noll. Standardvärdet är noll.

access är ett heltal som anger en accessmask som beskriver den önskade säkerhetsåtkomsten för nyckeln. Standardvärdet är KEY_WRITE. Se Access Rights för andra tillåtna värden.

Om key är en av de fördefinierade nycklarna kan sub_key vara None. I så fall är det handtag som returneras samma nyckelhandtag som skickas till funktionen.

Om nyckeln redan finns, öppnar denna funktion den befintliga nyckeln.

Returvärdet är handtaget för den öppnade nyckeln. Om funktionen misslyckas genereras ett OSError undantag.

Utlöser en auditing event winreg.CreateKey med argumenten key, sub_key, access.

Utlöser en auditing event winreg.OpenKey/result med argumentet key.

Tillagd i version 3.2.

Ändrad i version 3.3: Se ovanför.

winreg.DeleteKey(key, sub_key)

Raderar den angivna nyckeln.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som måste vara en undernyckel till den nyckel som identifieras av parametern key. Detta värde får inte vara None, och nyckeln får inte ha undernycklar.

Den här metoden kan inte radera nycklar med undernycklar.

Om metoden lyckas tas hela nyckeln bort, inklusive alla dess värden. Om metoden misslyckas, uppstår ett OSError undantag.

Utlöser en auditing event winreg.DeleteKey med argumenten key, sub_key, access.

Ändrad i version 3.3: Se ovanför.

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

Raderar den angivna nyckeln.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som måste vara en undernyckel till den nyckel som identifieras av parametern key. Detta värde får inte vara None, och nyckeln får inte ha undernycklar.

reserved är ett reserverat heltal och måste vara noll. Standardvärdet är noll.

access är ett heltal som anger en accessmask som beskriver den önskade säkerhetsaccessen för nyckeln. Standardvärdet är KEY_WOW64_64KEY. I 32-bitars Windows ignoreras WOW64-konstanter. Se Access Rights för andra tillåtna värden.

Den här metoden kan inte radera nycklar med undernycklar.

Om metoden lyckas tas hela nyckeln bort, inklusive alla dess värden. Om metoden misslyckas, uppstår ett OSError undantag.

På Windows-versioner som inte stöds genereras NotImplementedError.

Utlöser en auditing event winreg.DeleteKey med argumenten key, sub_key, access.

Tillagd i version 3.2.

Ändrad i version 3.3: Se ovanför.

winreg.DeleteValue(key, value)

Tar bort ett namngivet värde från en registernyckel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

value är en sträng som identifierar det värde som ska tas bort.

Utlöser en auditing event winreg.DeleteValue med argumenten key, value.

winreg.EnumKey(key, index)

Räknar upp undernycklar till en öppen registernyckel och returnerar en sträng.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

index är ett heltal som identifierar indexet för den nyckel som ska hämtas.

Funktionen hämtar namnet på en undernyckel varje gång den anropas. Den anropas vanligtvis upprepade gånger tills ett OSError-undantag uppstår, vilket indikerar att inga fler värden finns tillgängliga.

Utlöser en auditing event winreg.EnumKey med argumenten key, index.

Ändrad i version 3.3: Se ovanför.

winreg.EnumValue(key, index)

Räknar upp värden för en öppen registernyckel och returnerar en tupel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

index är ett heltal som identifierar indexet för det värde som ska hämtas.

Funktionen hämtar namnet på en undernyckel varje gång den anropas. Den anropas vanligtvis upprepade gånger tills ett OSError-undantag uppstår, vilket indikerar att det inte finns fler värden.

Resultatet är en tupel med 3 objekt:

Index

Betydelse

0

En sträng som identifierar värdets namn

1

Ett objekt som innehåller värdedata och vars typ beror på den underliggande registertypen

2

Ett heltal som identifierar typen av värdedata (se tabell i dokumentationen för SetValueEx())

Utlöser en auditing event winreg.EnumValue med argumenten key, index.

Ändrad i version 3.3: Se ovanför.

winreg.ExpandEnvironmentStrings(str)

Expanderar platshållare för miljövariabler %NAME% i strängar som REG_EXPAND_SZ:

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

Utlöser en auditing event winreg.ExpandEnvironmentStrings med argumentet str.

winreg.FlushKey(key)

Skriver alla attribut för en nyckel till registret.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

Det är inte nödvändigt att anropa FlushKey() för att ändra en nyckel. Registerändringar spolas till disken av registret med hjälp av dess lazy flusher. Registerändringar spolas också till disken när systemet stängs av. Till skillnad från CloseKey() returnerar metoden FlushKey() endast när alla data har skrivits till registret. En applikation bör endast anropa FlushKey() om den kräver absolut säkerhet om att registerändringar finns på disk.

Anteckning

Om du inte vet om ett anrop av FlushKey() krävs, så gör det förmodligen inte det.

winreg.LoadKey(key, sub_key, file_name)

Skapar en undernyckel under den angivna nyckeln och lagrar registreringsinformation från en angiven fil i den undernyckeln.

key är ett handle som returneras av ConnectRegistry() eller en av konstanterna HKEY_USERS eller HKEY_LOCAL_MACHINE.

sub_key är en sträng som identifierar den undernyckel som ska laddas.

file_name är namnet på den fil som registerdata ska laddas från. Filen måste ha skapats med funktionen SaveKey(). I filsystemet FAT (File Allocation Table) får filnamnet inte ha något tillägg.

Ett anrop till LoadKey() misslyckas om den anropande processen inte har privilegiet SE_RESTORE_PRIVILEGE. Observera att privilegier skiljer sig från behörigheter - se dokumentationen för RegLoadKey för mer information.

Om key är ett handtag som returneras av ConnectRegistry(), är sökvägen som anges i file_name relativ till fjärrdatorn.

Utlöser en auditing event winreg.LoadKey med argumenten 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)

Öppnar den angivna nyckeln och returnerar ett handle-objekt.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som identifierar den sub_key som ska öppnas.

reserved är ett reserverat heltal och måste vara noll. Standardvärdet är noll.

access är ett heltal som anger en accessmask som beskriver den önskade säkerhetsåtkomsten för nyckeln. Standardvärdet är KEY_READ. Se Access Rights för andra tillåtna värden.

Resultatet är ett nytt handtag till den angivna nyckeln.

Om funktionen misslyckas genereras OSError.

Utlöser en auditing event winreg.OpenKey med argumenten key, sub_key, access.

Utlöser en auditing event winreg.OpenKey/result med argumentet key.

Ändrad i version 3.2: Tillåt användning av namngivna argument.

Ändrad i version 3.3: Se ovanför.

winreg.QueryInfoKey(key)

Returnerar information om en nyckel, som en tupel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

Resultatet är en tupel med 3 objekt:

Index

Betydelse

0

Ett heltal som anger antalet undernycklar som denna nyckel har.

1

Ett heltal som anger antalet värden som denna nyckel har.

2

Ett heltal som anger när nyckeln senast ändrades (om tillgängligt) i 100-tals nanosekunder sedan den 1 januari 1601.

Utlöser en auditing event winreg.QueryInfoKey med argumentet key.

winreg.QueryValue(key, sub_key)

Hämtar det icke namngivna värdet för en nyckel, som en sträng.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som innehåller namnet på den undernyckel som värdet är associerat med. Om denna parameter är None eller tom, hämtar funktionen det värde som ställts in med metoden SetValue() för den nyckel som identifieras av key.

Värden i registret har namn-, typ- och datakomponenter. Den här metoden hämtar data för en nyckels första värde som har ett NULL-namn. Men det underliggande API-anropet returnerar inte typen, så använd alltid QueryValueEx() om det är möjligt.

Utlöser en auditing event winreg.QueryValue med argumenten key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)

Hämtar typ och data för ett angivet värdenamn som är kopplat till en öppen registernyckel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

value_name är en sträng som anger det värde som ska efterfrågas.

Resultatet är en tupel med 2 objekt:

Index

Betydelse

0

Värdet på registerposten.

1

Ett heltal som anger registertypen för detta värde (se tabell i dokumentationen för SetValueEx())

Utlöser en auditing event winreg.QueryValue med argumenten key, sub_key, value_name.

winreg.SaveKey(key, file_name)

Sparar den angivna nyckeln och alla dess undernycklar i den angivna filen.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

file_name är namnet på den fil som registerdata ska sparas i. Filen får inte redan existera. Om filnamnet innehåller ett tillägg kan det inte användas i FAT-filsystem (File Allocation Table) med metoden LoadKey().

Om key representerar en nyckel på en fjärrdator är sökvägen som beskrivs av file_name relativ till fjärrdatorn. Den som anropar den här metoden måste ha säkerhetsprivilegiet SeBackupPrivilege. Observera att privilegier inte är samma sak som behörigheter - se dokumentationen Konflikter mellan användarrättigheter och behörigheter för mer information.

Denna funktion skickar NULL för security_attributes till API:et.

Utlöser en auditing event winreg.SaveKey med argumenten key, file_name.

winreg.SetValue(key, sub_key, type, value)

Kopplar ett värde till en angiven nyckel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

sub_key är en sträng som namnger den undernyckel som värdet är associerat med.

type är ett heltal som anger typen av data. För närvarande måste detta vara REG_SZ, vilket innebär att endast strängar stöds. Använd funktionen SetValueEx() för att få stöd för andra datatyper.

value är en sträng som anger det nya värdet.

Om den nyckel som anges i parametern sub_key inte finns, skapas den av funktionen SetValue.

Värdenas längd begränsas av tillgängligt minne. Långa värden (mer än 2048 byte) bör lagras som filer med filnamnen lagrade i konfigurationsregistret. Detta bidrar till att registret fungerar effektivt.

Den nyckel som identifieras av parametern key måste ha öppnats med KEY_SET_VALUE-åtkomst.

Utlöser en auditing-händelse winreg.SetValue med argumenten key, sub_key, type, value.

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

Lagrar data i värdefältet i en öppen registernyckel.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

value_name är en sträng som namnger den undernyckel som värdet är associerat med.

reserved kan vara vad som helst - noll skickas alltid till API:et.

type är ett heltal som anger typen av data. Se Value Types för tillgängliga typer.

value är en sträng som anger det nya värdet.

Denna metod kan också ange ytterligare värde- och typinformation för den angivna nyckeln. Den nyckel som identifieras av nyckelparametern måste ha öppnats med KEY_SET_VALUE-åtkomst.

För att öppna nyckeln, använd metoderna CreateKey() eller OpenKey().

Värdenas längd begränsas av tillgängligt minne. Långa värden (mer än 2048 byte) bör lagras som filer med filnamnen lagrade i konfigurationsregistret. Detta bidrar till att registret fungerar effektivt.

Utlöser en auditing-händelse winreg.SetValue med argumenten key, sub_key, type, value.

winreg.DisableReflectionKey(key)

Inaktiverar registerreflektion för 32-bitars processer som körs på ett 64-bitars operativsystem.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

Kommer i allmänhet att ge upphov till NotImplementedError om den körs på ett 32-bitars operativsystem.

Om nyckeln inte finns med i reflektionslistan lyckas funktionen, men den har ingen effekt. Att inaktivera reflektion för en nyckel påverkar inte reflektion för eventuella undernycklar.

Utlöser en auditing event winreg.DisableReflectionKey med argumentet key.

winreg.EnableReflectionKey(key)

Återställer registerreflektionen för den angivna inaktiverade nyckeln.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

Kommer i allmänhet att ge upphov till NotImplementedError om den körs på ett 32-bitars operativsystem.

Återställning av reflektion för en nyckel påverkar inte reflektion för eventuella undernycklar.

Utlöser en auditing event winreg.EnableReflectionKey med argumentet key.

winreg.QueryReflectionKey(key)

Fastställer reflektionsstatus för den angivna tangenten.

key är en redan öppen nyckel, eller en av de fördefinierade HKEY_*-konstanterna.

Returnerar True om reflektion är inaktiverat.

Kommer i allmänhet att ge upphov till NotImplementedError om den körs på ett 32-bitars operativsystem.

Utlöser en auditing event winreg.QueryReflectionKey med argumentet key.

Konstanter

Följande konstanter är definierade för att användas i många winreg-funktioner.

HKEY_* Konstanter

winreg.HKEY_CLASSES_ROOT

Registerposter som är underordnade denna nyckel definierar dokumenttyper (eller klasser) och de egenskaper som är associerade med dessa typer. Shell- och COM-program använder den information som lagras under den här nyckeln.

winreg.HKEY_CURRENT_USER

Registerposter som är underordnade denna nyckel definierar den aktuella användarens preferenser. Dessa inställningar omfattar inställningar av miljövariabler, data om programgrupper, färger, skrivare, nätverksanslutningar och programinställningar.

winreg.HKEY_LOCAL_MACHINE

Registerposter som är underordnade denna nyckel definierar datorns fysiska status, inklusive data om busstyp, systemminne samt installerad maskin- och programvara.

winreg.HKEY_USERS

Registerposter som är underordnade denna nyckel definierar standardanvändarkonfigurationen för nya användare på den lokala datorn och användarkonfigurationen för den aktuella användaren.

winreg.HKEY_PERFORMANCE_DATA

Med registerposter som är underordnade denna nyckel kan du få tillgång till prestandadata. Uppgifterna lagras inte i registret, utan registerfunktionerna gör att systemet hämtar uppgifterna från källan.

winreg.HKEY_CURRENT_CONFIG

Innehåller information om den aktuella maskinvaruprofilen för det lokala datorsystemet.

winreg.HKEY_DYN_DATA

Denna nyckel används inte i Windows-versioner efter 98.

Tillgångsrättigheter

Mer information finns i Registry Key Security and Access.

winreg.KEY_ALL_ACCESS

Kombinerar behörigheterna STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY och KEY_CREATE_LINK.

winreg.KEY_WRITE

Kombinerar behörigheterna STANDARD_RIGHTS_WRITE, KEY_SET_VALUE och KEY_CREATE_SUB_KEY.

winreg.KEY_READ

Kombinerar värdena STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS och KEY_NOTIFY.

winreg.KEY_EXECUTE

Motsvarar KEY_READ.

winreg.KEY_QUERY_VALUE

Krävs för att fråga efter värdena i en registernyckel.

winreg.KEY_SET_VALUE

Krävs för att skapa, ta bort eller ange ett registervärde.

winreg.KEY_CREATE_SUB_KEY

Krävs för att skapa en undernyckel till en registernyckel.

winreg.KEY_ENUMERATE_SUB_KEYS

Krävs för att räkna upp undernycklarna i en registernyckel.

winreg.KEY_NOTIFY

Krävs för att begära ändringsmeddelanden för en registernyckel eller för undernycklar till en registernyckel.

Reserverad för systemanvändning.

64-bitarsspecifik

Mer information finns i avsnittet Åtkomst till en alternativ registervy.

winreg.KEY_WOW64_64KEY

Indikerar att ett program i 64-bitars Windows ska arbeta med 64-bitars registervy. I 32-bitars Windows ignoreras denna konstant.

winreg.KEY_WOW64_32KEY

Indikerar att ett program i 64-bitars Windows ska arbeta med 32-bitars registervyn. I 32-bitars Windows ignoreras denna konstant.

Värdetyper

Mer information finns i Registry Value Types.

winreg.REG_BINARY

Binärdata i alla former.

winreg.REG_DWORD

32-bitars nummer.

winreg.REG_DWORD_LITTLE_ENDIAN

Ett 32-bitars tal i little-endian-format. Motsvarar REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

Ett 32-bitars tal i big-endian-format.

winreg.REG_EXPAND_SZ

Sträng med nollavgränsning som innehåller referenser till miljövariabler (%PATH%).

En symbolisk länk i Unicode.

winreg.REG_MULTI_SZ

En sekvens av nollavslutade strängar, avslutade med två nolltecken. (Python hanterar denna avslutning automatiskt.)

winreg.REG_NONE

Ingen definierad värdetyp.

winreg.REG_QWORD

Ett 64-bitars tal.

Tillagd i version 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

Ett 64-bitars tal i little-endian-format. Motsvarar REG_QWORD.

Tillagd i version 3.6.

winreg.REG_RESOURCE_LIST

En resurslista för enhet-drivrutin.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

En hårdvaruinställning.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

En resurslista för hårdvara.

winreg.REG_SZ

En sträng med nollavgränsning.

Registerhanteringsobjekt

Detta objekt omsluter ett Windows HKEY-objekt och stänger det automatiskt när objektet förstörs. För att garantera upprensning kan du anropa antingen metoden Close() på objektet eller funktionen CloseKey().

Alla registerfunktioner i denna modul returnerar ett av dessa objekt.

Alla registerfunktioner i denna modul som accepterar ett handle-objekt accepterar också ett heltal, men användning av handle-objektet uppmuntras.

Handle-objekt ger semantik för __bool__() – alltså

om handtag:
    print("Ja")

skriver ut Yes om handtaget för närvarande är giltigt (inte har stängts eller avskilts).

Objektet stöder också jämförelsesemantik, så att handle-objekt kommer att jämföra sant om de båda refererar till samma underliggande Windows handle-värde.

Handle-objekt kan konverteras till ett heltal (t.ex. med hjälp av den inbyggda funktionen int()), varvid det underliggande värdet för Windows-handlet returneras. Du kan också använda metoden Detach() för att returnera heltalshandtaget och även koppla bort Windows-handtaget från handle-objektet.

PyHKEY.Close()

Stänger det underliggande Windows-handtaget.

Om handtaget redan är stängt utlöses inget fel.

PyHKEY.Detach()

Kopplar bort Windows-handtaget från handle-objektet.

Resultatet är ett heltal som innehåller handtagets värde innan det kopplas bort. Om handtaget redan är bortkopplat eller stängt blir resultatet noll.

När du har anropat den här funktionen ogiltigförklaras handtaget, men det stängs inte. Du anropar den här funktionen när du vill att det underliggande Win32-handtaget ska finnas kvar efter handle-objektets livstid.

Utlöser en auditing event winreg.PyHKEY.Detach med argumentet key.

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

HKEY-objektet implementerar __enter__() och __exit__() och stöder därmed kontextprotokollet för with-satsen:

med OpenKey(HKEY_LOCAL_MACHINE, "foo") som nyckel:
    ...  # arbeta med nyckel

stänger automatiskt nyckeln när kontrollen lämnar with-blocket.