Source code for spack.util.windows_registry

# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
# Spack Project Developers. See the top-level COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)

"""
Utility module for dealing with Windows Registry.
"""

import os
import re
import sys
from contextlib import contextmanager

from llnl.util import tty

if sys.platform == "win32":
    import winreg


[docs] class RegistryValue: """ Class defining a Windows registry entry """ def __init__(self, name, value, parent_key): self.path = name self.value = value self.key = parent_key
[docs] class RegistryKey: """ Class wrapping a Windows registry key """ def __init__(self, name, handle): self.path = name self.name = os.path.split(name)[-1] self._handle = handle self._keys = [] self._values = {} @property def values(self): """Returns all subvalues of this key as RegistryValue objects in dictionary of value name : RegistryValue object """ self._gather_value_info() return self._values @property def subkeys(self): """Returns list of all subkeys of this key as RegistryKey objects""" self._gather_subkey_info() return self._keys @property def hkey(self): return self._handle
[docs] @contextmanager def winreg_error_handler(self, name, *args, **kwargs): try: yield except OSError as err: # Expected errors that occur on occasion, these are easily # debug-able and have sufficiently verbose reporting and obvious cause # [WinError 2]: the system cannot find the file specified - lookup item does # not exist # [WinError 5]: Access is denied - user not in key's ACL if hasattr(err, "winerror") and err.winerror in (5, 2): raise err # Other OS errors are more difficult to diagnose, so we wrap them in some extra # reporting raise InvalidRegistryOperation(name, err, *args, **kwargs) from err
[docs] def OpenKeyEx(self, subname, **kwargs): """Convenience wrapper around winreg.OpenKeyEx""" tty.debug( f"[WINREG ACCESS] Accessing Reg Key {self.path}/{subname} with" f" {kwargs.get('access', 'default')} access" ) with self.winreg_error_handler("OpenKeyEx", subname, **kwargs): return winreg.OpenKeyEx(self.hkey, subname, **kwargs)
[docs] def QueryInfoKey(self): """Convenience wrapper around winreg.QueryInfoKey""" tty.debug(f"[WINREG ACCESS] Obtaining key,value information from key {self.path}") with self.winreg_error_handler("QueryInfoKey"): return winreg.QueryInfoKey(self.hkey)
[docs] def EnumKey(self, index): """Convenience wrapper around winreg.EnumKey""" tty.debug( "[WINREG ACCESS] Obtaining name of subkey at index " f"{index} from registry key {self.path}" ) with self.winreg_error_handler("EnumKey", index): return winreg.EnumKey(self.hkey, index)
[docs] def EnumValue(self, index): """Convenience wrapper around winreg.EnumValue""" tty.debug( f"[WINREG ACCESS] Obtaining value at index {index} from registry key {self.path}" ) with self.winreg_error_handler("EnumValue", index): return winreg.EnumValue(self.hkey, index)
[docs] def QueryValueEx(self, name, **kwargs): """Convenience wrapper around winreg.QueryValueEx""" tty.debug(f"[WINREG ACCESS] Obtaining value {name} from registry key {self.path}") with self.winreg_error_handler("QueryValueEx", name, **kwargs): return winreg.QueryValueEx(self.hkey, name, **kwargs)
def __str__(self): return self.name def _gather_subkey_info(self): """Composes all subkeys into a list for access""" if self._keys: return sub_keys, _, _ = self.QueryInfoKey() for i in range(sub_keys): sub_name = self.EnumKey(i) try: sub_handle = self.OpenKeyEx(sub_name, access=winreg.KEY_READ) self._keys.append(RegistryKey(os.path.join(self.path, sub_name), sub_handle)) except OSError as e: if hasattr(e, "winerror") and e.winerror == 5: # This is a permission error, we can't read this key # move on pass else: raise def _gather_value_info(self): """Compose all values for this key into a dict of form value name: RegistryValue Object""" if self._values: return _, values, _ = self.QueryInfoKey() for i in range(values): value_name, value_data, _ = self.EnumValue(i) self._values[value_name] = RegistryValue(value_name, value_data, self)
[docs] def get_subkey(self, sub_key): """Returns subkey of name sub_key in a RegistryKey objects""" return RegistryKey( os.path.join(self.path, sub_key), self.OpenKeyEx(sub_key, access=winreg.KEY_READ) )
[docs] def get_value(self, val_name): """Returns value associated with this key in RegistryValue object""" return RegistryValue(val_name, self.QueryValueEx(val_name)[0], self)
class _HKEY_CONSTANT(RegistryKey): """Subclass of RegistryKey to represent the prebaked, always open registry HKEY constants""" def __init__(self, hkey_constant): hkey_name = hkey_constant # This class is instantiated at module import time # on non Windows platforms, winreg would not have been # imported. For this reason we can't reference winreg yet, # so handle is none for now to avoid invalid references to a module. # _handle provides a workaround to prevent null references to self.handle # when coupled with the handle property. super(_HKEY_CONSTANT, self).__init__(hkey_name, None) def _get_hkey(self, key): return getattr(winreg, key) @property def hkey(self): if not self._handle: self._handle = self._get_hkey(self.path) return self._handle
[docs] class HKEY: """ Predefined, open registry HKEYs From the Microsoft docs: An application must open a key before it can read data from the registry. To open a key, an application must supply a handle to another key in the registry that is already open. The system defines predefined keys that are always open. Predefined keys help an application navigate in the registry.""" HKEY_CLASSES_ROOT = _HKEY_CONSTANT("HKEY_CLASSES_ROOT") HKEY_CURRENT_USER = _HKEY_CONSTANT("HKEY_CURRENT_USER") HKEY_USERS = _HKEY_CONSTANT("HKEY_USERS") HKEY_LOCAL_MACHINE = _HKEY_CONSTANT("HKEY_LOCAL_MACHINE") HKEY_CURRENT_CONFIG = _HKEY_CONSTANT("HKEY_CURRENT_CONFIG") HKEY_PERFORMANCE_DATA = _HKEY_CONSTANT("HKEY_PERFORMANCE_DATA")
[docs] class WindowsRegistryView: """ Interface to provide access, querying, and searching to Windows registry entries. This class represents a single key entrypoint into the Windows registry and provides an interface to this key's values, its subkeys, and those subkey's values. This class cannot be used to move freely about the registry, only subkeys/values of the root key used to instantiate this class. """ def __init__(self, key, root_key=HKEY.HKEY_CURRENT_USER): """Constructs a Windows Registry entrypoint to key provided root_key should be an already open root key or an hkey constant if provided Args: key (str): registry key to provide root for registry key for this clas root_key: Already open registry key or HKEY constant to provide access into the Windows registry. Registry access requires an already open key to get an entrypoint, the HKEY constants are always open, or an already open key can be used instead. """ if sys.platform != "win32": raise RuntimeError( "Cannot instantiate Windows Registry class on non Windows platforms" ) self.key = key self.root = root_key self._reg = None
[docs] class KeyMatchConditions:
[docs] @staticmethod def regex_matcher(subkey_name): return lambda x: re.match(subkey_name, x.name)
[docs] @staticmethod def name_matcher(subkey_name): return lambda x: subkey_name == x.name
[docs] @contextmanager def invalid_reg_ref_error_handler(self): try: yield except FileNotFoundError as e: if sys.platform == "win32" and e.winerror == 2: tty.debug("Key %s at position %s does not exist" % (self.key, str(self.root))) else: raise e
def __bool__(self): return self.reg != -1 def _load_key(self): try: self._reg = self.root.get_subkey(self.key) except FileNotFoundError as e: if sys.platform == "win32" and e.winerror == 2: self._reg = -1 tty.debug("Key %s at position %s does not exist" % (self.key, str(self.root))) else: raise e def _valid_reg_check(self): if self.reg == -1: tty.debug(f"[WINREG ACCESS] Cannot perform operation for nonexistent key {self.key}") return False return True def _regex_match_subkeys(self, subkey): r_subkey = re.compile(subkey) return [key for key in self.get_subkeys() if r_subkey.match(key.name)] @property def reg(self): if not self._reg: self._load_key() return self._reg
[docs] def get_value(self, value_name): """Return registry value corresponding to provided argument (if it exists)""" if not self._valid_reg_check(): raise RegistryError(f"Cannot query value from invalid key {self.key}") with self.invalid_reg_ref_error_handler(): return self.reg.get_value(value_name)
[docs] def get_subkey(self, subkey_name): if not self._valid_reg_check(): raise RegistryError(f"Cannot query subkey from invalid key {self.key}") with self.invalid_reg_ref_error_handler(): return self.reg.get_subkey(subkey_name)
[docs] def get_subkeys(self): if not self._valid_reg_check(): raise RegistryError(f"Cannot query subkeys from invalid key {self.key}") with self.invalid_reg_ref_error_handler(): return self.reg.subkeys
[docs] def get_matching_subkeys(self, subkey_name): """Returns all subkeys regex matching subkey name Note: this method obtains only direct subkeys of the given key and does not desced to transtitve subkeys. For this behavior, see `find_matching_subkeys`""" self._regex_match_subkeys(subkey_name)
[docs] def get_values(self): if not self._valid_reg_check(): raise RegistryError(f"Cannot query values from invalid key {self.key}") with self.invalid_reg_ref_error_handler(): return self.reg.values
def _traverse_subkeys(self, stop_condition, collect_all_matching=False, recursive=True): """Perform simple BFS of subkeys, returning the key that successfully triggers the stop condition. Args: stop_condition: lambda or function pointer that takes a single argument a key and returns a boolean value based on that key collect_all_matching: boolean value, if True, the traversal collects and returns all keys meeting stop condition. If false, once stop condition is met, the key that triggered the condition ' is returned. recusrive: boolean value, if True perform a recursive search of subkeys Return: the key if stop_condition is triggered, or None if not """ collection = [] if not self._valid_reg_check(): raise InvalidKeyError(self.key) with self.invalid_reg_ref_error_handler(): queue = self.reg.subkeys for key in queue: if stop_condition(key): if collect_all_matching: collection.append(key) else: return key if recursive: queue.extend(key.subkeys) return collection if collection else None
[docs] def find_subkey(self, subkey_name, recursive=True): """Perform a BFS of subkeys until desired key is found Returns None or RegistryKey object corresponding to requested key name Args: subkey_name (str): subkey to be searched for recursive (bool): perform a recursive search Return: the desired subkey as a RegistryKey object, or none """ return self._traverse_subkeys( WindowsRegistryView.KeyMatchConditions.name_matcher(subkey_name), recursive=recursive )
[docs] def find_matching_subkey(self, subkey_name, recursive=True): """Perform a BFS of subkeys until a key matching subkey name regex is found Returns None or the first RegistryKey object corresponding to requested key name Args: subkey_name (str): subkey to be searched for recursive (bool): perform a recursive search Return: the desired subkey as a RegistryKey object, or none """ return self._traverse_subkeys( WindowsRegistryView.KeyMatchConditions.regex_matcher(subkey_name), recursive=recursive )
[docs] def find_subkeys(self, subkey_name, recursive=True): """Exactly the same as find_subkey, except this function tries to match a regex to multiple keys Args: subkey_name (str) Return: the desired subkeys as a list of RegistryKey object, or none """ kwargs = {"collect_all_matching": True, "recursive": recursive} return self._traverse_subkeys( WindowsRegistryView.KeyMatchConditions.regex_matcher(subkey_name), **kwargs )
[docs] def find_value(self, val_name, recursive=True): """ If non recursive, return RegistryValue object corresponding to name Args: val_name (str): name of value desired from registry recursive (bool): optional argument, if True, the registry is searched recursively for the value of name val_name, else only the current key is searched Return: The desired registry value as a RegistryValue object if it exists, otherwise, None """ if not recursive: return self.get_value(val_name) else: key = self._traverse_subkeys(lambda x: val_name in x.values) if not key: return None else: return key.values[val_name]
[docs] class RegistryError(Exception): """RunTime Error concerning the Windows Registry"""
[docs] class InvalidKeyError(RegistryError): """Runtime Error describing issue with invalid key access to Windows registry""" def __init__(self, key): message = f"Cannot query invalid key: {key}" super().__init__(message)
[docs] class InvalidRegistryOperation(RegistryError): """A Runtime Error ecountered when a registry operation is invalid for an indeterminate reason""" def __init__(self, name, e, *args, **kwargs): message = ( f"Windows registry operations: {name} encountered error: {str(e)}" "\nMethod invoked with parameters:\n" ) message += "\n\t".join([f"{k}:{v}" for k, v in kwargs.items()]) message += "\n" message += "\n\t".join(args) super().__init__(self, message)