Estas funciones exponen la API de registro de Windows a Python. En lugar de utilizar un número entero como identificador de registro, manejar objeto se utiliza para garantizar que los identificadores se cierren correctamente, incluso si el programador se niega a cerrarlos explícitamente.

Modificado en la versión 3.3: Varias funciones de este módulo se utilizan para generar un WindowsError, que ahora es un alias de OSError.

Funciones

Este módulo ofrece las siguientes funciones:

winreg.CloseKey(hkey)

Cierra una clave de registro abierta anteriormente. los hkey argumento especifica una clave previamente abierta.

Nota

Si hkey no se cierra con este método (o mediante hkey.Close()), se cierra cuando el hkey Python destruye el objeto.

winreg.ConnectRegistry(computer_name, key)

Establece una conexión con un identificador de registro predefinido en otra computadora y devuelve un manejar objeto.

nombre del computador es el nombre de la computadora remota, de la forma r"\computername". Si None, se utiliza la computadora local.

llave es el identificador predefinido al que conectarse.

El valor de retorno es el identificador de la llave abierta. Si la función falla, un OSError se plantea una excepción.

Plantea un evento de auditoríawinreg.ConnectRegistry con argumentos computer_name, key.

Modificado en la versión 3.3: Ver encima.

winreg.CreateKey(key, sub_key)

Crea o abre la clave especificada, devolviendo un manejar objeto.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que nombra la clave que este método abre o crea.

Si llave es una de las claves predefinidas, sub-clave quizás None. En ese caso, el identificador devuelto es el mismo identificador de clave que se pasó a la función.

Si la clave ya existe, esta función abre la clave existente.

El valor de retorno es el identificador de la llave abierta. Si la función falla, un OSError se plantea una excepción.

Plantea un evento de auditoríawinreg.CreateKey con argumentos key, sub_key, access.

Plantea un evento de auditoríawinreg.OpenKey/result con argumento key.

Modificado en la versión 3.3: Ver encima.

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

Crea o abre la clave especificada, devolviendo un manejar objeto.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que nombra la clave que este método abre o crea.

reservado es un entero reservado y debe ser cero. El valor predeterminado es cero.

acceso es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_WRITE. Ver Derechos de acceso para otros valores permitidos.

Si llave es una de las claves predefinidas, sub-clave quizás None. En ese caso, el identificador devuelto es el mismo identificador de clave que se pasó a la función.

Si la clave ya existe, esta función abre la clave existente.

El valor de retorno es el identificador de la llave abierta. Si la función falla, un OSError se plantea una excepción.

Plantea un evento de auditoríawinreg.CreateKey con argumentos key, sub_key, access.

Plantea un evento de auditoríawinreg.OpenKey/result con argumento key.

Nuevo en la versión 3.2.

Modificado en la versión 3.3: Ver encima.

winreg.DeleteKey(key, sub_key)

Elimina la clave especificada.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que debe ser una subclave de la clave identificada por el llave parámetro. Este valor no debe ser Noney es posible que la clave no tenga subclaves.

Este método no puede eliminar claves con subclaves.

Si el método tiene éxito, se elimina toda la clave, incluidos todos sus valores. Si el método falla, un OSError se plantea una excepción.

Plantea un evento de auditoríawinreg.DeleteKey con argumentos key, sub_key, access.

Modificado en la versión 3.3: Ver encima.

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

Elimina la clave especificada.

Nota

los DeleteKeyEx() La función se implementa con la función RegDeleteKeyEx de la API de Windows, que es específica de las versiones de Windows de 64 bits. Ver el Documentación de RegDeleteKeyEx.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que debe ser una subclave de la clave identificada por el llave parámetro. Este valor no debe ser Noney es posible que la clave no tenga subclaves.

reservado es un entero reservado y debe ser cero. El valor predeterminado es cero.

acceso es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_WOW64_64KEY. Ver Derechos de acceso para otros valores permitidos.

Este método no puede eliminar claves con subclaves.

Si el método tiene éxito, se elimina toda la clave, incluidos todos sus valores. Si el método falla, un OSError se plantea una excepción.

En versiones de Windows no compatibles, NotImplementedError es elevado.

Plantea un evento de auditoríawinreg.DeleteKey con argumentos key, sub_key, access.

Nuevo en la versión 3.2.

Modificado en la versión 3.3: Ver encima.

winreg.DeleteValue(key, value)

Elimina un valor con nombre de una clave de registro.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

valor es una cadena que identifica el valor a eliminar.

Plantea un evento de auditoríawinreg.DeleteValue con argumentos key, value.

winreg.EnumKey(key, index)

Enumera las subclaves de una clave de registro abierta y devuelve una cadena.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

índice es un número entero que identifica el índice de la clave a recuperar.

La función recupera el nombre de una subclave cada vez que se llama. Por lo general, se llama repetidamente hasta que OSError Se genera una excepción, lo que indica que no hay más valores disponibles.

Plantea un evento de auditoríawinreg.EnumKey con argumentos key, index.

Modificado en la versión 3.3: Ver encima.

winreg.EnumValue(key, index)

Enumera los valores de una clave de registro abierta y devuelve una tupla.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

índice es un número entero que identifica el índice del valor a recuperar.

La función recupera el nombre de una subclave cada vez que se llama. Normalmente se llama repetidamente, hasta que un OSError se genera una excepción, lo que indica que no hay más valores.

El resultado es una tupla de 3 elementos:

Índice

Sentido

0

Una cadena que identifica el nombre del valor.

1

Un objeto que contiene los datos del valor y cuyo tipo depende del tipo de registro subyacente.

2

Un número entero que identifica el tipo de datos de valor (consulte la tabla en los documentos para SetValueEx())

Plantea un evento de auditoríawinreg.EnumValue con argumentos key, index.

Modificado en la versión 3.3: Ver encima.

winreg.ExpandEnvironmentStrings(str)

Expande los marcadores de posición de las variables de entorno %NAME% en cadenas como REG_EXPAND_SZ:

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

Plantea un evento de auditoríawinreg.ExpandEnvironmentStrings con argumento str.

winreg.FlushKey(key)

Escribe todos los atributos de una clave en el registro.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

No es necesario llamar FlushKey() para cambiar una clave. Los cambios en el registro se descargan en el disco mediante el registro mediante su vaciador diferido. Los cambios en el registro también se vacían en el disco cuando se apaga el sistema. diferente a CloseKey(), los FlushKey() El método regresa solo cuando todos los datos se han escrito en el registro. Una aplicación solo debe llamar FlushKey() si requiere absoluta certeza de que los cambios en el registro están en el disco.

Nota

Si no sabe si un FlushKey() se requiere una llamada, probablemente no lo sea.

winreg.LoadKey(key, sub_key, file_name)

Crea una subclave bajo la clave especificada y almacena la información de registro de un archivo especificado en esa subclave.

llave es un identificador devuelto por ConnectRegistry() o una de las constantes HKEY_USERS o HKEY_LOCAL_MACHINE.

sub-clave es una cadena que identifica la subclave a cargar.

nombre del archivo es el nombre del archivo desde el que se cargarán los datos de registro. Este archivo debe haber sido creado con el SaveKey() función. En el sistema de archivos de la tabla de asignación de archivos (FAT), es posible que el nombre del archivo no tenga extensión.

Una llamada a LoadKey() falla si el proceso de llamada no tiene la SE_RESTORE_PRIVILEGE privilegio. Tenga en cuenta que los privilegios son diferentes de los permisos; consulte la Documentación de RegLoadKey para más detalles.

Si llave es un identificador devuelto por ConnectRegistry(), luego la ruta especificada en nombre del archivo es relativo a la computadora remota.

Plantea un evento de auditoríawinreg.LoadKey con 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 la clave especificada, devolviendo un manejar objeto.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que identifica la sub_clave para abrir.

reservado es un entero reservado y debe ser cero. los el valor predeterminado es cero.

acceso es un número entero que especifica una máscara de acceso que describe el acceso de seguridad deseado para la clave. El valor predeterminado es KEY_READ. Ver Derechos de acceso para otros valores permitidos.

El resultado es un nuevo identificador para la clave especificada.

Si la función falla, OSError es elevado.

Plantea un evento de auditoríawinreg.OpenKey con argumentos key, sub_key, access.

Plantea un evento de auditoríawinreg.OpenKey/result con argumento key.

Modificado en la versión 3.2: Permitir el uso de argumentos con nombre.

Modificado en la versión 3.3: Ver encima.

winreg.QueryInfoKey(key)

Devuelve información sobre una clave, como una tupla.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

El resultado es una tupla de 3 elementos:

Índice

Sentido

0

Un número entero que indica el número de subclaves que tiene esta tecla.

1

Un número entero que da el número de valores que tiene esta clave.

2

Un número entero que indica cuándo se modificó por última vez la clave (si está disponible) como cientos de nanosegundos desde el 1 de enero de 1601.

Plantea un evento de auditoríawinreg.QueryInfoKey con argumento key.

winreg.QueryValue(key, sub_key)

Recupera el valor sin nombre de una clave, como una cadena.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que contiene el nombre de la subclave con la que está asociado el valor. Si este parámetro es None o vacío, la función recupera el valor establecido por el SetValue() método para la clave identificada por llave.

Los valores del registro tienen componentes de nombre, tipo y datos. Este método recupera los datos del primer valor de una clave que tiene un NULL nombre. Pero la llamada a la API subyacente no devuelve el tipo, así que siempre use QueryValueEx() si es posible.

Plantea un evento de auditoríawinreg.QueryValue con argumentos key, sub_key, value_name.

winreg.QueryValueEx(key, value_name)

Recupera el tipo y los datos de un nombre de valor especificado asociado con una clave de registro abierta.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

value_name es una cadena que indica el valor a consultar.

El resultado es una tupla de 2 elementos:

Índice

Sentido

0

El valor del elemento de registro.

1

Un número entero que proporciona el tipo de registro para este valor (consulte la tabla en los documentos para SetValueEx())

Plantea un evento de auditoríawinreg.QueryValue con argumentos key, sub_key, value_name.

winreg.SaveKey(key, file_name)

Guarda la clave especificada y todas sus subclaves en el archivo especificado.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

nombre del archivo es el nombre del archivo en el que se guardarán los datos del registro. Este archivo no puede existir. Si este nombre de archivo incluye una extensión, no se puede utilizar en sistemas de archivos de tabla de asignación de archivos (FAT) por el LoadKey() método.

Si llave representa una clave en una computadora remota, la ruta descrita por nombre del archivo es relativo a la computadora remota. La persona que llama de este método debe poseer el SeBackupPrivilege privilegio de seguridad. Tenga en cuenta que los privilegios son diferentes a los permisos; consulte la Conflictos entre la documentación de permisos y derechos de usuario para más detalles.

Esta función pasa NULL por atributos_de_seguridad a la API.

Plantea un evento de auditoríawinreg.SaveKey con argumentos key, file_name.

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

Asocia un valor con una clave especificada.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

sub-clave es una cadena que nombra la subclave con la que está asociado el valor.

escribe es un número entero que especifica el tipo de datos. Actualmente esto debe ser REG_SZ, lo que significa que solo se admiten cadenas. Utilizar el SetValueEx() función para admitir otros tipos de datos.

valor es una cadena que especifica el nuevo valor.

Si la clave especificada por el sub-clave El parámetro no existe, la función SetValue lo crea.

Las longitudes de los valores están limitadas por la memoria disponible. Los valores largos (más de 2048 bytes) deben almacenarse como archivos con los nombres de archivo almacenados en el registro de configuración. Esto ayuda a que el registro funcione de manera eficiente.

La clave identificada por el llave el parámetro debe haber sido abierto con KEY_SET_VALUE acceso.

Plantea un evento de auditoríawinreg.SetValue con argumentos key, sub_key, type, value.

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

Almacena datos en el campo de valor de una clave de registro abierta.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

value_name es una cadena que nombra la subclave con la que está asociado el valor.

reservado puede ser cualquier cosa: cero siempre se pasa a la API.

escribe es un número entero que especifica el tipo de datos. Ver Tipos de valor para los tipos disponibles.

valor es una cadena que especifica el nuevo valor.

Este método también puede establecer un valor adicional e información de tipo para la clave especificada. La llave identificada por el parámetro de llave debe haber sido abierta con KEY_SET_VALUE acceso.

Para abrir la llave, use el CreateKey() o OpenKey() métodos.

Las longitudes de los valores están limitadas por la memoria disponible. Los valores largos (más de 2048 bytes) deben almacenarse como archivos con los nombres de archivo almacenados en el registro de configuración. Esto ayuda a que el registro funcione de manera eficiente.

Plantea un evento de auditoríawinreg.SetValue con argumentos key, sub_key, type, value.

winreg.DisableReflectionKey(key)

Desactiva la reflexión del registro para los procesos de 32 bits que se ejecutan en un sistema operativo de 64 bits.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

Generalmente aumentará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

Si la clave no está en la lista de reflexión, la función tiene éxito pero no tiene ningún efecto. La desactivación de la reflexión de una clave no afecta la reflexión de ninguna subclave.

Plantea un evento de auditoríawinreg.DisableReflectionKey con argumento key.

winreg.EnableReflectionKey(key)

Restaura la reflexión del registro para la clave deshabilitada especificada.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

Generalmente aumentará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

Restaurar la reflexión de una clave no afecta la reflexión de ninguna subclave.

Plantea un evento de auditoríawinreg.EnableReflectionKey con argumento key.

winreg.QueryReflectionKey(key)

Determina el estado de reflexión para la clave especificada.

llave es una clave ya abierta, o una de las predefinidas HKEY_ * constantes.

Devoluciones True si la reflexión está deshabilitada.

Generalmente aumentará NotImplementedError si se ejecuta en un sistema operativo de 32 bits.

Plantea un evento de auditoríawinreg.QueryReflectionKey con argumento key.

Constantes

Las siguientes constantes están definidas para su uso en muchos _winreg funciones.

HKEY_ * Constantes

winreg.HKEY_CLASSES_ROOT

Las entradas de registro subordinadas a esta clave definen tipos (o clases) de documentos y las propiedades asociadas con esos tipos. Las aplicaciones Shell y COM utilizan la información almacenada en esta clave.

winreg.HKEY_CURRENT_USER

Las entradas de registro subordinadas a esta clave definen las preferencias del usuario actual. Estas preferencias incluyen la configuración de variables de entorno, datos sobre grupos de programas, colores, impresoras, conexiones de red y preferencias de la aplicación.

winreg.HKEY_LOCAL_MACHINE

Las entradas de registro subordinadas a esta clave definen el estado físico de la computadora, incluidos los datos sobre el tipo de bus, la memoria del sistema y el hardware y software instalados.

winreg.HKEY_USERS

Las entradas de registro subordinadas a esta clave definen la configuración de usuario predeterminada para nuevos usuarios en la computadora local y la configuración de usuario para el usuario actual.

winreg.HKEY_PERFORMANCE_DATA

Las entradas de registro subordinadas a esta clave le permiten acceder a los datos de rendimiento. Los datos no se almacenan realmente en el registro; las funciones de registro hacen que el sistema recopile los datos de su fuente.

winreg.HKEY_CURRENT_CONFIG

Contiene información sobre el perfil de hardware actual del sistema informático local.

winreg.HKEY_DYN_DATA

Esta clave no se usa en versiones de Windows posteriores a la 98.

Derechos de acceso

Para más información, ver Seguridad y acceso a la clave de registro.

winreg.KEY_ALL_ACCESS

Combina STANDARD_RIGHTS_REQUIRED, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, y KEY_CREATE_LINK derechos de acceso.

winreg.KEY_WRITE

Combina STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, y KEY_CREATE_SUB_KEY derechos de acceso.

winreg.KEY_READ

Combina STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, y KEY_NOTIFY valores.

winreg.KEY_EXECUTE

Equivalente a KEY_READ.

winreg.KEY_QUERY_VALUE

Requerido para consultar los valores de una clave de registro.

winreg.KEY_SET_VALUE

Necesario para crear, eliminar o establecer un valor de registro.

winreg.KEY_CREATE_SUB_KEY

Necesario para crear una subclave de una clave de registro.

winreg.KEY_ENUMERATE_SUB_KEYS

Requerido para enumerar las subclaves de una clave de registro.

winreg.KEY_NOTIFY

Requerido para solicitar notificaciones de cambio para una clave de registro o para subclaves de una clave de registro.

winreg.KEY_CREATE_LINK

Reservado para uso del sistema.

Específico de 64 bits

Para más información, ver Acceder a una vista de registro alternativa.

winreg.KEY_WOW64_64KEY

Indica que una aplicación en Windows de 64 bits debería funcionar en la vista de registro de 64 bits.

winreg.KEY_WOW64_32KEY

Indica que una aplicación en Windows de 64 bits debería funcionar en la vista de registro de 32 bits.

Tipos de valor

Para más información, ver Tipos de valores de registro.

winreg.REG_BINARY

Datos binarios en cualquier forma.

winreg.REG_DWORD

Número de 32 bits.

winreg.REG_DWORD_LITTLE_ENDIAN

Un número de 32 bits en formato little-endian. Equivalente a REG_DWORD.

winreg.REG_DWORD_BIG_ENDIAN

Un número de 32 bits en big-endian formato.

winreg.REG_EXPAND_SZ

Cadena terminada en nulo que contiene referencias a variables de entorno (%PATH%).

winreg.REG_LINK

Un enlace simbólico Unicode.

winreg.REG_MULTI_SZ

Una secuencia de cadenas terminadas en nulo, terminadas por dos caracteres nulos. (Python maneja esta terminación automáticamente).

winreg.REG_NONE

Sin tipo de valor definido.

winreg.REG_QWORD

Un número de 64 bits.

Nuevo en la versión 3.6.

winreg.REG_QWORD_LITTLE_ENDIAN

Un número de 64 bits en formato little-endian. Equivalente a REG_QWORD.

Nuevo en la versión 3.6.

winreg.REG_RESOURCE_LIST

Una lista de recursos de controladores de dispositivo.

winreg.REG_FULL_RESOURCE_DESCRIPTOR

Una configuración de hardware.

winreg.REG_RESOURCE_REQUIREMENTS_LIST

Una lista de recursos de hardware.

winreg.REG_SZ

Una cadena terminada en nulo.

Objetos de control del registro

Este objeto envuelve un objeto HKEY de Windows y lo cierra automáticamente cuando se destruye. Para garantizar la limpieza, puede llamar al Close() método en el objeto, o el CloseKey() función.

Todas las funciones de registro de este módulo devuelven uno de estos objetos.

Todas las funciones de registro de este módulo que aceptan un objeto identificador también aceptan un número entero, sin embargo, se recomienda el uso del objeto identificador.

Los objetos de manejo proporcionan semántica para __bool__() – por lo tanto

if handle:print("Yes")

imprimirá Yes si la manija es válida actualmente (no se ha cerrado o desprendido).

El objeto también admite la semántica de comparación, por lo que los objetos de identificador se compararán con verdadero si ambos hacen referencia al mismo valor de identificador de Windows subyacente.

Los objetos de control se pueden convertir a un número entero (por ejemplo, utilizando el int() función), en cuyo caso se devuelve el valor del identificador de Windows subyacente. También puede utilizar el Detach() para devolver el identificador de entero y también desconectar el identificador de Windows del objeto identificador.

PyHKEY.Close()

Cierra el identificador de Windows subyacente.

Si la manija ya está cerrada, no se genera ningún error.

PyHKEY.Detach()

Separa el identificador de Windows del objeto identificador.

El resultado es un número entero que contiene el valor del identificador antes de que se separe. Si la manija ya está separada o cerrada, esto devolverá cero.

Después de llamar a esta función, el identificador se invalida de manera efectiva, pero el identificador no se cierra. Llamaría a esta función cuando necesite que el identificador Win32 subyacente exista más allá de la vida útil del objeto identificador.

Plantea un evento de auditoríawinreg.PyHKEY.Detach con argumento key.

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

El objeto HKEY implementa __enter__() y __exit__() y por lo tanto soporta el protocolo de contexto para el with declaración:

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

se cerrará automáticamente llave cuando el control deja el with cuadra.