# `winreg` – Registro de acesso 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`.

  Novo 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`.

  Novo 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.

  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.

  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()`.

  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.

  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

The following constants are defined for use in many `_winreg` functions.

### 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.

  Novo na versão 3.6.

`winreg.``REG_QWORD_LITTLE_ENDIAN`

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

  Novo 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.

Handle objects provide semantics for `__bool__()` – thus

    if handle:
        print("Yes")

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:
          ...  # work with key

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