winreg — Acesso aos registros do Windows

---

Essas funções expõem a API de registro do Windows ao Python. Em vez de usar um inteiro como identificador de registro, um objeto identificador é usado para garantir que os identificadores sejam fechados corretamente, mesmo que o programador não os feche explicitamente.

Alterado na versão 3.3: Várias funções neste módulo costumavam levantar um WindowsError , que agora é um apelido de OSError.

Funções

Este módulo oferece as seguintes funções:

winreg.CloseKey(hkey)

Fecha uma chave de registro aberta anteriormente. O argumento hkey especifica uma chave aberta anteriormente.

Nota

Se hkey não for fechado usando este método (ou via hkey.Close()), ele será fechado quando o objeto hkey for destruído pelo Python.

winreg.ConnectRegistry(computer_name, key)

Estabelece uma conexão com um identificador de registro predefinido em outro computador e retorna um objeto identificador.

computer_name é o nome do computador remoto, no formato r"\\computername". Se None, o computador local será usado.

key é o identificador predefinido para conexão.

O valor de retorno é o identificador da chave aberta. Se a função falhar, uma exceção OSError será levantada.

Levanta um evento de auditoria winreg.ConnectRegistry com os argumentos computer_name, key.

Alterado na versão 3.3: Veja acima.

winreg.CreateKey(key, sub_key)

Cria ou abre a chave especificada, retornando um objeto identificador.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que nomeia a chave que este método abre ou cria.

Se key for uma das chaves predefinidas, sub_key poderá ser None. Nesse caso, o identificador retornado será o mesmo identificador de chave passado para a função.

Se a chave já existir, esta função abre a chave existente.

O valor de retorno é o identificador da chave aberta. Se a função falhar, uma exceção OSError será levantada.

Levanta um evento de auditoria winreg.CreateKey com os argumentos key, sub_key, access.

Levanta um evento de auditoria winreg.OpenKey/result com o argumento key.

Alterado na versão 3.3: Veja acima.

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

Cria ou abre a chave especificada, retornando um objeto identificador.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que nomeia a chave que este método abre ou cria.

reserved é um inteiro reservado e deve ser zero. O padrão é zero.

access é um inteiro que especifica uma máscara de acesso que descreve o acesso de segurança desejado para a chave. O padrão é KEY_WRITE. Consulte Direitos de acesso para outros valores permitidos.

Se key for uma das chaves predefinidas, sub_key poderá ser None. Nesse caso, o identificador retornado será o mesmo identificador de chave passado para a função.

Se a chave já existir, esta função abre a chave existente.

O valor de retorno é o identificador da chave aberta. Se a função falhar, uma exceção OSError será levantada.

Levanta um evento de auditoria winreg.CreateKey com os argumentos key, sub_key, access.

Levanta um evento de auditoria winreg.OpenKey/result com o argumento key.

Adicionado na versão 3.2.

Alterado na versão 3.3: Veja acima.

winreg.DeleteKey(key, sub_key)

Exclui a chave especificada.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que deve ser uma subchave da chave identificada pelo parâmetro key. Este valor não pode ser None, e a chave não pode ter subchaves.

Este método não pode excluir chaves com subchaves.

Se o método for bem-sucedido, a chave inteira, incluindo todos os seus valores, será removida. Se o método falhar, uma exceção OSError será levantada.

Levanta um evento de auditoria winreg.DeleteKey com os argumentos key, sub_key, access.

Alterado na versão 3.3: Veja acima.

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

Exclui a chave especificada.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que deve ser uma subchave da chave identificada pelo parâmetro key. Este valor não pode ser None, e a chave não pode ter subchaves.

reserved é um inteiro reservado e deve ser zero. O padrão é zero.

access é um inteiro que especifica uma máscara de acesso que descreve o acesso de segurança desejado para a chave. O padrão é KEY_WOW64_64KEY. No Windows de 32 bits, as constantes WOW64 são ignoradas. Consulte Direitos de acesso para outros valores permitidos.

Este método não pode excluir chaves com subchaves.

Se o método for bem-sucedido, a chave inteira, incluindo todos os seus valores, será removida. Se o método falhar, uma exceção OSError será levantada.

Em versões do Windows sem suporte, NotImplementedError é levantada.

Levanta um evento de auditoria winreg.DeleteKey com os argumentos key, sub_key, access.

Adicionado na versão 3.2.

Alterado na versão 3.3: Veja acima.

winreg.DeleteValue(key, value)

Remove um valor nomeado de uma chave de registro.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

value é uma string que identifica o valor a ser removido.

Levanta um evento de auditoria winreg.DeleteValue com os argumentos key, value.

winreg.EnumKey(key, index)

Enumera subchaves de uma chave de registro aberta, retornando uma string.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

index é um inteiro que identifica o índice da chave a ser recuperada.

A função recupera o nome de uma subchave cada vez que é chamada. Normalmente, ela é chamada repetidamente até que uma exceção OSError seja levantada, indicando que não há mais valores disponíveis.

Levanta um evento de auditoria winreg.EnumKey com os argumentos key, index.

Alterado na versão 3.3: Veja acima.

winreg.EnumValue(key, index)

Enumera valores de uma chave de registro aberta, retornando uma tupla.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

index é um inteiro que identifica o índice do valor a ser recuperado.

A função recupera o nome de uma subchave cada vez que é chamada. Normalmente, ela é chamada repetidamente, até que uma exceção OSError seja levantada, indicando que não há mais valores.

O resultado é uma tupla de 3 itens:

Índice	Significado
0	Uma string que identifica o nome do valor
1	Um objeto que contém os dados de valor e cujo tipo depende do tipo de registro subjacente
2	Um inteiro que identifica o tipo dos dados do valor (veja a tabela na documentação para SetValueEx())

Levanta um evento de auditoria winreg.EnumValue com os argumentos key, index.

Alterado na versão 3.3: Veja acima.

winreg.ExpandEnvironmentStrings(str)

Expande os espaços reservados de posição de variáveis de ambiente %NAME% em strings como REG_EXPAND_SZ:

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

Levanta um evento de auditoria winreg.ExpandEnvironmentStrings com o argumento str.

winreg.FlushKey(key)

Grava todos os atributos de uma chave no registro.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

Não é necessário chamar FlushKey() para alterar uma chave. As alterações do registro são descarregadas no disco pelo registro usando seu limpador lento. As alterações do registro também são descarregadas no disco no desligamento do sistema. Ao contrário de CloseKey(), o método FlushKey() retorna somente quando todos os dados foram gravados no registro. Uma aplicação só deve chamar FlushKey() se precisar de certeza absoluta de que as alterações do registro estão no disco.

Nota

Se você não sabe se uma chamada FlushKey() é necessária, provavelmente não é.

winreg.LoadKey(key, sub_key, file_name)

Cria uma subchave sob a chave especificada e armazena informações de registro de um arquivo especificado nessa subchave.

key é um identificador retornado por ConnectRegistry() ou uma das constantes HKEY_USERS ou HKEY_LOCAL_MACHINE.

sub_key é uma string que identifica a subchave a ser carregada.

file_name é o nome do arquivo do qual serão carregados os dados do registro. Este arquivo deve ter sido criado com a função SaveKey(). No sistema de arquivos da tabela de alocação de arquivos (FAT), o nome do arquivo não pode ter extensão.

Uma chamada para LoadKey() falhará se o processo de chamada não tiver o privilégio SE_RESTORE_PRIVILEGE. Observe que privilégios são diferentes de permissões — consulte a documentação do RegLoadKey para mais detalhes.

Se key for um identificador retornado por ConnectRegistry(), então o caminho especificado em file_name será relativo ao computador remoto.

Levanta um evento de auditoria winreg.LoadKey com os argumentos 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)

Abre a chave especificada, retornando um objeto identificador.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que identifica a sub_key a ser aberta.

reserved é um inteiro reservado e deve ser zero. O padrão é zero.

access é um inteiro que especifica uma máscara de acesso que descreve o acesso de segurança desejado para a chave. O padrão é KEY_READ. Consulte Direitos de acesso para outros valores permitidos.

O resultado é um novo identificador para a chave especificada.

Se a função falhar, OSError será levantada.

Levanta um evento de auditoria winreg.OpenKey com os argumentos key, sub_key, access.

Levanta um evento de auditoria winreg.OpenKey/result com o argumento key.

Alterado na versão 3.2: Permite o uso de argumentos nomeados.

Alterado na versão 3.3: Veja acima.

winreg.QueryInfoKey(key)

Retorna informações sobre uma chave, como uma tupla.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

O resultado é uma tupla de 3 itens:

Índice	Significado
0	Um inteiro que fornece o número de subchaves que esta chave possui.
1	Um inteiro que fornece o número de valores que esta chave possui.
2	Um número inteiro que indica quando a chave foi modificada pela última vez (se disponível) em centenas de nanossegundos desde 1º de janeiro de 1601.

Levanta um evento de auditoria winreg.QueryInfoKey com o argumento key.

winreg.QueryValue(key, sub_key)

Recupera o valor sem nome de uma chave, como uma string.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que contém o nome da subchave à qual o valor está associado. Se este parâmetro for None ou estiver vazio, a função recupera o valor definido pelo método SetValue() para a chave identificada por key.

Os valores no registro têm componentes de nome, tipo e dados. Este método recupera os dados do primeiro valor de uma chave que possui um nome NULL. Mas a chamada de API subjacente não retorna o tipo, portanto, sempre use QueryValueEx() se possível.

Levanta um evento de auditoria winreg.QueryValue com os argumentos key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)

Recupera o tipo e os dados de um nome de valor especificado associado a uma chave de registro aberta.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

value_name é uma string que indica o valor a ser consultado.

O resultado é uma tupla de 2 itens:

Índice	Significado
0	O valor do item do registro.
1	Um inteiro que fornece o tipo de registro para este valor (veja a tabela na documentação para SetValueEx())

Levanta um evento de auditoria winreg.QueryValue com os argumentos key, sub_key, value_name.

winreg.SaveKey(key, file_name)

Salva a chave especificada e todas as suas subchaves no arquivo especificado.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

file_name é o nome do arquivo para salvar os dados do registro. Este arquivo não pode existir. Se este nome de arquivo incluir uma extensão, ele não poderá ser usado em sistemas de arquivos FAT (tabela de alocação de arquivos) pelo método LoadKey().

Se key representa uma chave em um computador remoto, o caminho descrito por file_name é relativo ao computador remoto. O chamador deste método deve possuir o privilégio de segurança SeBackupPrivilege. Observe que privilégios são diferentes de permissões — consulte a documentação Conflitos entre Direitos e Permissões do Usuário para obter mais detalhes.

Esta função passa NULL para security_attributes para a API.

Levanta um evento de auditoria winreg.SaveKey com os argumentos key, file_name.

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

Associa um valor a uma chave especificada.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

sub_key é uma string que nomeia a subchave à qual o valor está associado.

type é um inteiro que especifica o tipo dos dados. Atualmente, deve ser REG_SZ, o que significa que apenas strings são suportadas. Use a função SetValueEx() para suporte a outros tipos de dados.

valor é uma string que especifica o novo valor.

Se a chave especificada pelo parâmetro sub_key não existir, a função SetValue a criará.

O comprimento dos valores é limitado pela memória disponível. Valores longos (mais de 2048 bytes) devem ser armazenados como arquivos com os nomes dos arquivos armazenados no registro de configuração. Isso ajuda o registro a funcionar com eficiência.

A chave identificada pelo parâmetro key deve ter sido aberta com acesso KEY_SET_VALUE.

Levanta um evento de auditoria winreg.SetValue com os argumentos key, sub_key, type, value.

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

Armazena dados no campo de valor de uma chave de registro aberta.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

value_name é uma string que nomeia a subchave à qual o valor está associado.

reserved pode ser qualquer coisa – zero é sempre passado para a API.

type é um inteiro que especifica o tipo dos dados. Consulte Tipos de valor para os tipos disponíveis.

valor é uma string que especifica o novo valor.

Este método também pode definir informações adicionais de valor e tipo para a chave especificada. A chave identificada pelo parâmetro key deve ter sido aberta com o acesso KEY_SET_VALUE.

Para abrir a chave, use os métodos CreateKey() ou OpenKey().

O comprimento dos valores é limitado pela memória disponível. Valores longos (mais de 2048 bytes) devem ser armazenados como arquivos com os nomes dos arquivos armazenados no registro de configuração. Isso ajuda o registro a funcionar com eficiência.

Levanta um evento de auditoria winreg.SetValue com os argumentos key, sub_key, type, value.

winreg.DisableReflectionKey(key)

Desabilita a reflexão do registro para processos de 32 bits em execução em um sistema operacional de 64 bits.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

Geralmente levantará NotImplementedError se executado em um sistema operacional de 32 bits.

Se a chave não estiver na lista de reflexão, a função será bem-sucedida, mas não terá efeito. Desabilitar a reflexão para uma chave não afeta a reflexão de nenhuma subchave.

Levanta um evento de auditoria winreg.DisableReflectionKey com o argumento key.

winreg.EnableReflectionKey(key)

Restaura a reflexão do registro para a chave desabilitada especificada.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

Geralmente levantará NotImplementedError se executado em um sistema operacional de 32 bits.

Restaura a reflexão de uma chave não afeta a reflexão de nenhuma subchave.

Levanta um evento de auditoria winreg.EnableReflectionKey com o argumento key.

winreg.QueryReflectionKey(key)

Determina o estado de reflexão para a chave especificada.

key é uma chave já aberta, ou uma das constantes predefinidas HKEY_*.

Retorna True se a reflexão estiver desabilitada.

Geralmente levantará NotImplementedError se executado em um sistema operacional de 32 bits.

Levanta um evento de auditoria winreg.QueryReflectionKey com o argumento key.

Constantes

As seguintes constantes são definidas para uso em muitas funções winreg.

Constantes HKEY_*

winreg.HKEY_CLASSES_ROOT

Entradas de registro subordinadas a esta chave definem tipos (ou classes) de documentos e as propriedades associadas a esses tipos. Aplicações Shell e COM utilizam as informações armazenadas sob esta chave.

winreg.HKEY_CURRENT_USER

As entradas de registro subordinadas a esta chave definem as preferências do usuário atual. Essas preferências incluem as configurações de variáveis de ambiente, dados sobre grupos de programas, cores, impressoras, conexões de rede e preferências de aplicações.

winreg.HKEY_LOCAL_MACHINE

As entradas de registro subordinadas a esta chave definem o estado físico do computador, incluindo dados sobre o tipo de barramento, memória do sistema e hardware e software instalados.

winreg.HKEY_USERS

As entradas de registro subordinadas a esta chave definem a configuração de usuário padrão para novos usuários no computador local e a configuração de usuário para o usuário atual.

winreg.HKEY_PERFORMANCE_DATA

Entradas de registro subordinadas a esta chave permitem que você acesse dados de desempenho. Os dados não são armazenados no registro; as funções de registro fazem com que o sistema colete os dados de sua fonte.

winreg.HKEY_CURRENT_CONFIG

Contém informações sobre o perfil de hardware atual do sistema de computador local.

winreg.HKEY_DYN_DATA

Esta chave não é usada em versões do Windows posteriores à 98.

Direitos de acesso

Para obter mais informações, consulte Segurança e acesso a chaves do registro.

winreg.KEY_ALL_ACCESS

Combina os direitos de acesso STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY e KEY_CREATE_LINK.

winreg.KEY_WRITE

Combina os direitos de acesso STANDARD_RIGHTS_WRITE, KEY_SET_VALUE e KEY_CREATE_SUB_KEY.

winreg.KEY_READ

Combina os valores STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS e KEY_NOTIFY.

winreg.KEY_EXECUTE

Equivalente a KEY_READ.

winreg.KEY_QUERY_VALUE

Necessário para consultar os valores de uma chave de registro.

winreg.KEY_SET_VALUE

Necessário para criar, excluir ou definir um valor de registro.

winreg.KEY_CREATE_SUB_KEY

Necessário para criar uma subchave de uma chave de registro.

winreg.KEY_ENUMERATE_SUB_KEYS

Necessário para enumerar as subchaves de uma chave de registro.

winreg.KEY_NOTIFY

Necessário para solicitar notificações de alteração para uma chave de registro ou para subchaves de uma chave de registro.

winreg.KEY_CREATE_LINK

Reservado para uso pelo sistema.

Específico de 64 bits

Para obter mais informações, consulte Acessando uma exibição alternativa do Registro.

winreg.KEY_WOW64_64KEY

Indica que uma aplicação no Windows 64 bits deve operar na visualização de registro de 64 bits. No Windows de 32 bits, esta constante é ignorada.

winreg.KEY_WOW64_32KEY

Indica que uma aplicação no Windows 64 bits deve operar na visualização de registro de 32 bits. No Windows de 32 bits, esta constante é ignorada.

Tipos de valores

Para obter mais informações, consulte Tipos de valor do Registro.

winreg.REG_BINARY

Dados binários em qualquer formato.

winreg.REG_DWORD

Número de 32 bits.

winreg.REG_DWORD_LITTLE_ENDIAN

Um número de 32 bits no formato little-endian. Equivalente a REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

Um número de 32 bits no formato big-endian.

winreg.REG_EXPAND_SZ

String terminada em nulo contendo referências a variáveis de ambiente (%PATH%).

winreg.REG_LINK

Um link simbólico Unicode.

winreg.REG_MULTI_SZ

Uma sequência de strings terminadas em nulo, terminadas por dois caracteres nulos. (O Python lida com essa terminação automaticamente.)

winreg.REG_NONE

Nenhum tipo de valor definido.

winreg.REG_QWORD

Um número de 64 bits.

Adicionado na versão 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

Um número de 64 bits no formato little-endian. Equivalente a REG_QWORD.

Adicionado na versão 3.6.

winreg.REG_RESOURCE_LIST

Uma lista de recursos de driver de dispositivo.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

Uma configuração de hardware.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

Uma lista de recursos de hardware.

winreg.REG_SZ

Uma string terminada em nulo.

Objetos identificador de registro

Este objeto encapsula um objeto HKEY do Windows, fechando-o automaticamente quando o objeto é destruído. Para garantir a limpeza, você pode chamar o método Close() no objeto ou a função CloseKey().

Todas as funções de registro neste módulo retornam um destes objetos.

Todas as funções de registro neste módulo que aceitam um objeto identificador também aceitam um inteiro; no entanto, o uso do objeto identificador é incentivado.

Objetos identificador fornecem semântica para __bool__() – portanto

if handle:
    print("Sim")

vai exibir Sim se o identificador for válido no momento (não foi fechado ou desanexado).

O objeto também oferece suporte à semântica de comparação, portanto, os objetos identificador serão comparados como verdadeiros se ambos fizerem referência ao mesmo valor de identificador subjacente do Windows.

Objetos identificador podem ser convertidos em um inteiro (por exemplo, usando a função embutida int()), caso em que o valor do identificador do Windows subjacente é retornado. Você também pode usar o método Detach() para retornar o identificador inteiro e também desconectar o identificador do Windows do objeto identificador.

PyHKEY.Close()

Fecha o identificador subjacente do Windows.

Se o identificador já estiver fechado, nenhum erro será levantado.

PyHKEY.Detach()

Separa o identificador do Windows do objeto identificador.

O resultado é um inteiro que contém o valor do identificador antes de ser destacado. Se o identificador já estiver destacado ou fechado, isso retornará zero.

Após chamar esta função, o identificador é efetivamente invalidado, mas não é fechado. Você chamaria esta função quando precisasse que o identificador subjacente de Win32 existisse além do tempo de vida do objeto identificador.

Levanta um evento de auditoria winreg.PyHKEY.Detach com o argumento key.

PyHKEY.__enter__()

PyHKEY.__exit__(*exc_info)

O objeto HKEY implementa __enter__() e __exit__() e, portanto, oferece suporte ao protocolo de contexto para a instrução with:

with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # trabalha com a chave "key"

vai fechar automaticamente key quando o controle sair do bloco with.