casement 0.4.0__py3-none-any.whl

casement/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+from .version import version as __version__

casement/__main__.py

@@ -0,0 +1,16 @@
+""" Enables support for calling the casement cli using `python -m casement`
+"""
+
+from __future__ import absolute_import
+
+import sys
+
+import casement.cli
+
+if __name__ == '__main__':
+    # TODO: move casement cli to click
+    # prog_name prevents __main__.py from being shown as the command name in the help
+    # text. We don't know the exact command the user passed so we provide a generic
+    # `python -m casement` command.
+    # sys.exit(casement.cli.main(prog_name="python -m casement"))
+    sys.exit(casement.cli.main())

casement/app_id.py

@@ -0,0 +1,88 @@
+import ctypes
+import os
+from ctypes import wintypes
+
+import pythoncom
+from win32com.propsys import propsys
+from win32com.shell import shellcon
+
+
+class AppId(object):
+    @staticmethod
+    def for_shortcut(shortcut):
+        """Gets the AppUserModel.ID for the given shortcut.
+
+        This will allow windows to group windows with the same app id on a shortcut
+        pinned to the taskbar. Use :py:meth:`AppId.for_application` to set the
+        app id for a running application.
+        """
+        if os.path.exists(shortcut):
+            # These imports won't work inside python 2 DCC's
+            from win32com.propsys import propsys
+
+            # Original info from https://stackoverflow.com/a/61714895
+            key = propsys.PSGetPropertyKeyFromName("System.AppUserModel.ID")
+            store = propsys.SHGetPropertyStoreFromParsingName(shortcut)
+            return store.GetValue(key).GetValue()
+
+    @staticmethod
+    def set_for_shortcut(shortcut, app_id):
+        """Sets AppUserModel.ID info for a windows shortcut.
+
+        Note: This doesn't seem to work on a pinned taskbar shortcut. Set it on
+        a desktop shortcut then pin that shortcut.
+
+        This will allow windows to group windows with the same app id on a shortcut
+        pinned to the taskbar. Use :py:meth:`AppId.set_for_application` to set
+        the app id for a running application.
+
+        Args:
+            shortcut (str): The .lnk filename to set the app id on.
+            app_id (str): The app id to set on the shortcut
+        """
+        if os.path.exists(shortcut):
+            # Original info from https://stackoverflow.com/a/61714895
+            key = propsys.PSGetPropertyKeyFromName("System.AppUserModel.ID")
+            store = propsys.SHGetPropertyStoreFromParsingName(
+                shortcut, None, shellcon.GPS_READWRITE, propsys.IID_IPropertyStore
+            )
+
+            new_value = propsys.PROPVARIANTType(app_id, pythoncom.VT_BSTR)
+            store.SetValue(key, new_value)
+            store.Commit()
+
+    @staticmethod
+    def for_application():
+        """Returns the current Windows 7+ app user model id used for taskbar
+        grouping."""
+
+        lp_buffer = wintypes.LPWSTR()
+        app_user_model_id = (
+            ctypes.windll.shell32.GetCurrentProcessExplicitAppUserModelID
+        )
+        app_user_model_id(ctypes.cast(ctypes.byref(lp_buffer), wintypes.LPWSTR))
+        appid = lp_buffer.value
+        ctypes.windll.kernel32.LocalFree(lp_buffer)
+        return appid
+
+    @staticmethod
+    def set_for_application(appid, prefix=None):
+        """Controls Windows taskbar grouping.
+
+        Specifies a Explicit App User Model ID that Windows 7+ uses to control
+        grouping of windows on the taskbar.  This must be set before any ui is
+        displayed. The best place to call it is in the first widget to be displayed
+        __init__ method.
+
+        See :py:meth:`AppId.set_for_shortcut` to set the app id on a windows shortcut.
+
+        Args:
+            appid (str): The id of the application. Should use full camel-case.
+                http://msdn.microsoft.com/en-us/library/dd378459%28v=vs.85%29.aspx#how
+            prefix (str, optional): The prefix attached to the id.
+        """
+
+        # https://stackoverflow.com/a/27872625
+        if prefix:
+            appid = u'%s.%s' % (prefix, appid)
+        return not ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(appid)

casement/cli.py

@@ -0,0 +1,95 @@
+import importlib
+import logging
+import sys
+from argparse import ArgumentParser
+
+
+class CasementParser(object):
+    '''
+    To implement a cli for casement, create a submodule with the name of your
+    cli command. For example to add a ``casement test echo`` command, you would
+    create casement\test.py with the following code::
+
+        import argparse
+        from argparse import ArgumentParser
+
+        class _CLI(object):
+            def __init__(self, args):
+                # Parse the command and create the parser casement will use
+                parser = ArgumentParser()
+                parser.add_argument('command')
+                args = parser.parse_args(args)
+                # This will be added to args passed to the run command
+                self.command = args.command
+                # Create self.parser by calling the requested function
+                getattr(self, args.command)()
+
+            def echo(self):
+                """Creates a ArgumentParser to handle the echo command as self.parser"""
+                self.parser = ArgumentParser(
+                    usage='casement shortcut test [-h] [-v] text',
+                )
+                self.parser.add_argument('text', nargs=argparse.REMAINDER)
+
+            def run(self, args):
+                """Do something with the arguments parsed from self.parser"""
+                if args.command == 'echo':
+                    print('ECHO: {}'.format(' '.join(args.text)))
+    '''
+
+    def __init__(self):
+        self.target_cli = None
+        self._base_parser = ArgumentParser(
+            description='Windows management tool',
+            usage="casement <command> [<args>]\n\n"
+            "Valid commands are:\n"
+            "    shortcut or sc: Manage windows shortcuts.",
+        )
+        self._base_parser.add_argument('command', help='Command to run')
+        args = self._base_parser.parse_args(sys.argv[1:2])
+
+        # Convert short command names to full command names
+        short_names = {
+            'sc': 'shortcut',
+        }
+        self.command = short_names.get(args.command, args.command)
+        # use dispatch pattern to invoke method with same name
+        try:
+            module = importlib.import_module(
+                '.{}'.format(self.command), package='casement'
+            )
+        except ImportError:
+            self._base_parser.print_help()
+            sys.exit(1)
+        # parse_args defaults to [1:] for args, but we need to remove
+        # the 2 levels of commands for proper validation
+        self.args_list = sys.argv[3:]
+
+        self.target_cli = module._CLI(sys.argv[2:3])
+        for action in self.target_cli.parser._actions:
+            if action.dest == 'verbose':
+                break
+        else:
+            self.target_cli.parser.add_argument(
+                '-v', '--verbose', action='store_true', help='Give more output.'
+            )
+
+    def parse_args(self):
+        """Parse sub-command arguments adding global options."""
+        args = self.target_cli.parser.parse_args(self.args_list)
+        # Add command to the args from the target_cli
+        try:
+            args.command = self.target_cli.command
+        except AttributeError:
+            args.command = None
+        return args
+
+
+def main():
+    casement = CasementParser()
+    args = casement.parse_args()
+    logging.basicConfig(
+        format='%(message)s', level=logging.DEBUG if args.verbose else logging.INFO
+    )
+
+    casement.target_cli.run(args)

casement/enums.py

@@ -0,0 +1,22 @@
+from enum import Enum
+
+
+class FlashTimes(Enum):
+    """Windows flags for casement.utils.flashWindow().
+
+    https://docs.microsoft.com/en-us/windows/desktop/api/winuser/ns-winuser-flashwinfo
+    """
+
+    "'Stop flashing. The system restores the window to its original state.'"
+    FLASHW_STOP = 0
+    "Flash the window caption."
+    FLASHW_CAPTION = 0x00000001
+    "Flash the taskbar button."
+    FLASHW_TRAY = 0x00000002
+    """Flash both the window caption and taskbar button. This is equivalent
+    to setting the ``FLASHW_CAPTION | FLASHW_TRAY flags``."""
+    FLASHW_ALL = 0x00000003
+    "Flash continuously, until the ``FLASHW_STOP`` flag is set."
+    FLASHW_TIMER = 0x00000004
+    "Flash continuously until the window comes to the foreground."
+    FLASHW_TIMERNOFG = 0x0000000C

casement/env_var.py

@@ -0,0 +1,154 @@
+import logging
+import os
+from contextlib import contextmanager
+
+import win32api
+import win32con
+import win32file
+import win32gui
+from six.moves import winreg
+from six.moves.collections_abc import MutableMapping
+
+from .registry import REG_LOCATIONS, RegKey
+
+_logger_modify = logging.getLogger(__name__ + ".modify")
+_logger_broadcast = logging.getLogger(__name__ + ".broadcast")
+
+
+class EnvVar(MutableMapping):
+    """A dictionary like mapping of environment variables as defined in the
+    registry. Stored environment variables are not expanded by default. You can
+    use `normalize_path` for various path manipulation like expanding variables
+    and dealing with short/long file paths.
+
+    Arguments:
+        system (bool, optional): Controls if this instance modifies system or
+            user environment variables.
+
+    Every time you set or delete a environment variable it will send the
+    `WM_SETTINGCHANGE` message notifying other applications that system-wide
+    settings have changed.
+    See: https://learn.microsoft.com/en-us/windows/win32/winmsg/wm-settingchange
+
+    You can prevent this message from being sent every time you modify env vars
+    by using the `EnvVar.delayed_broadcast()` with context:
+
+        user_env = EnvVar(system=False)
+        with EnvVar.delayed_broadcast():
+            user_env['VAR_B'] = 'value b'
+            user_env['VAR_C'] = 'value c'
+            del user_env['VAR_A']
+
+    By using `EnvVar.delayed_broadcast()` broadcast will only be called once,
+    instead of three times.
+    """
+
+    # These class variables are used to control if broadcast sends its message
+    _broadcast_enabled = True
+    _broadcast_required = False
+
+    def __init__(self, system=False):
+        key, sub_key = REG_LOCATIONS["system" if system else "user"]['env_var']
+        self.__reg__ = RegKey(key, sub_key)
+
+    def __delitem__(self, key):
+        entry = self.__reg__.entry(key)
+        with self.delayed_broadcast():
+            _logger_modify.debug('Deleting env var: "{}"'.format(key))
+            entry.delete()
+            type(self)._broadcast_required = True
+
+    def __getitem__(self, key):
+        entry = self.__reg__.entry(key)
+        try:
+            return entry.value()
+        except OSError:
+            raise KeyError(key)
+
+    def __iter__(self):
+        return iter(self.__reg__.entry_names())
+
+    def __len__(self):
+        reg_key = self.__reg__._key()
+        if not reg_key:
+            return 0
+
+        _, count, _ = winreg.QueryInfoKey(reg_key)
+        return count
+
+    def __setitem__(self, key, value, value_type=winreg.REG_EXPAND_SZ):
+        entry = self.__reg__.entry(key)
+        with self.delayed_broadcast():
+            _logger_modify.debug('Setting env var: "{}" to "{}"'.format(key, value))
+            entry.set(value, value_type=value_type)
+            type(self)._broadcast_required = True
+
+    @classmethod
+    def broadcast(cls):
+        """Notify the system about the changes. Uses SendMessageTimeout to avoid
+        hanging if applications fail to respond to the broadcast.
+        """
+        if cls._broadcast_enabled is False:
+            _logger_broadcast.debug(
+                'Skipping broadcasting that the environment was changed'
+            )
+            return
+
+        _logger_broadcast.debug('Broadcasting that the environment was changed')
+        win32gui.SendMessageTimeout(
+            win32con.HWND_BROADCAST,
+            win32con.WM_SETTINGCHANGE,
+            0,
+            'Environment',
+            win32con.SMTO_ABORTIFHUNG,
+            1000,
+        )
+        # Reset the needs broadcast variable now that we have broadcast
+        cls._broadcast_required = False
+
+    @classmethod
+    @contextmanager
+    def delayed_broadcast(cls):
+        """Context manager that disables broadcast calls for each set/delete of
+        environment variables. Only if any set/delete calls were made inside the
+        with context, will it call broadcast.
+        """
+        try:
+            current = cls._broadcast_enabled
+            cls._broadcast_enabled = False
+            yield
+        finally:
+            cls._broadcast_enabled = current
+            if cls._broadcast_required:
+                cls.broadcast()
+
+    @classmethod
+    def normalize_path(cls, path, expandvars=True, tilde=None, normpath=True):
+        """Normalize a path handling short/long names, env vars and normpath.
+
+        Args:
+            path (str): Input path to expand.
+            expandvars (bool, optional): Expand environment variables.
+            tilde (bool, optional): Converts windows short paths(`C:\\PROGRA~1`).
+                If True, short paths are expanded to full file paths. If False
+                file paths are converted to short paths. Nothing is done if None.
+            normpath (bool, optional): If True calls os.path.normpath.
+
+        Returns:
+            str: Input path with any tilde-shortenings expanded.
+
+        Raises:
+            pywintypes.error: Raised if path doesn't exist when tilde is not None.
+        """
+        if tilde:
+            path = win32api.GetShortPathName(path)
+        elif tilde is False:
+            path = win32file.GetLongPathName(path)
+
+        if expandvars:
+            path = os.path.expandvars(path)
+
+        if normpath:
+            path = os.path.normpath(path)
+
+        return path

casement/registry.py

@@ -0,0 +1,272 @@
+"""
+key: Nodes in tree
+Each node in the tree is called a key.
+Each key can contain both subkeys and data entries called values.
+"""
+import six
+from six.moves import winreg
+
+
+def _generate_key_map():
+    """Creates a map of strings to winreg.HKEY_* objects."""
+    key_map = {}
+
+    for key in dir(winreg):
+        if key.startswith('HKEY_'):
+            # Add the long names
+            key_map[key] = getattr(winreg, key)
+            # Add the winreg value so we can lookup nice names for keys
+            key_map[getattr(winreg, key)] = key
+            # Generate shortnames
+            short = 'HK' + ''.join([s[0] for s in key.split('_')[1:]])
+            if short not in key_map:
+                key_map[short] = key_map[key]
+    return key_map
+
+
+key_map = _generate_key_map()
+
+"""Stores commonly looked up locations in the registry."""
+REG_LOCATIONS = {
+    "system": {
+        "classes": (winreg.HKEY_LOCAL_MACHINE, 'Software\\Classes'),
+        "env_var": (
+            winreg.HKEY_LOCAL_MACHINE,
+            'SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment',
+        ),
+        "uninstall": (
+            winreg.HKEY_LOCAL_MACHINE,
+            'Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+        ),
+    },
+    "user": {
+        "classes": (winreg.HKEY_CURRENT_USER, 'Software\\Classes'),
+        "env_var": (winreg.HKEY_CURRENT_USER, 'Environment'),
+        "regedit": (
+            winreg.HKEY_CURRENT_USER,
+            'Software\\Microsoft\\Windows\\CurrentVersion\\Applets\\Regedit',
+        ),
+    },
+}
+
+
+class RegKey(object):
+    """Object for accessing a specific registry key.
+
+    Example:
+
+        import winreg
+        from casement.registry import RegKey, REG_LOCATIONS
+
+        # Examples of different ways to get access to the same registry key.
+        classes_system = RegKey(*REG_LOCATIONS['system']['classes'])
+        classes_system = RegKey('HKEY_LOCAL_MACHINE\\Software\\Classes')
+        classes_system = RegKey('HKEY_LOCAL_MACHINE', 'Software\\Classes')
+        classes_system = RegKey(winreg.HKEY_LOCAL_MACHINE, 'Software\\Classes')
+
+    Args:
+        key: The path to the registry key as a string, or a winreg HKEY_* constant.
+            If a string is passed it needs to start with one of keys stored in
+            `key_map`(Example: HKEY_CLASSES_ROOT, HKCR). Alternatively you can
+            pass a winreg HKEY_* constant (Example: `winreg.HKEY_CURRENT_USER`).
+        sub_key (str, optional): A string to access sub-keys of key. If None and
+            key is a string it will split key into key and sub-key.
+        computer_name (str, optional): Name of another computer to connect to it's
+            registry instead of the current one.
+        architecture (int, optional): Access this key in the the 32 or 64 bit registry.
+            Valid values are 32 or 64.
+    """
+
+    def __init__(self, key, sub_key=None, computer_name=None, architecture=64):
+        # If sub_key is not passed, it must be part of key
+        if sub_key is None:
+            key, sub_key = key.split('\\', 1)
+
+        # Convert key strings into winreg keys
+        if isinstance(key, six.string_types):
+            key = key.upper()
+            key = key_map[key]
+
+        self.architecture = architecture
+        self.computer_name = computer_name
+        self.key = key
+        self.sub_key = sub_key
+
+    def __str__(self):
+        return 'RegKey({!r}, {!r}, {!r}, {})'.format(
+            key_map.get(self.key, self.key),
+            self.sub_key,
+            self.computer_name,
+            self.architecture,
+        )
+
+    def _key(self, write=False, create=False, delete=False):
+        """Returns a winreg.OpenKeyEx or None.
+
+        Returns:
+            A winreg handle object
+        """
+        connection = winreg.ConnectRegistry(self.computer_name, self.key)
+        sam = self._sam(self.architecture)
+        access = winreg.KEY_READ
+        if write:
+            access = winreg.KEY_WRITE
+
+        if create:
+            func = winreg.CreateKeyEx
+        else:
+            func = winreg.OpenKeyEx
+
+        try:
+            return func(connection, self.sub_key, 0, access | sam)
+        except OSError:
+            return None
+
+    @classmethod
+    def _sam(cls, architecture):
+        """Return the correct wow64 key for the requested architecture."""
+        if architecture == 32:
+            return winreg.KEY_WOW64_32KEY
+        elif architecture == 64:
+            return winreg.KEY_WOW64_64KEY
+        return 0
+
+    def child(self, name):
+        """Returns a RegKey for a sub_key with the given name.
+
+        Args:
+            name (str): The name of the child key to return.
+        """
+        cls = type(self)
+        sub_key = '{}\\{}'.format(self.sub_key, name)
+        return cls(
+            self.key,
+            sub_key=sub_key,
+            computer_name=self.computer_name,
+            architecture=self.architecture,
+        )
+
+    def child_names(self):
+        """Generator returning the name for all sub_keys of this key."""
+        reg_key = self._key()
+        if not reg_key:
+            return
+
+        index = 0
+        while True:
+            try:
+                yield winreg.EnumKey(reg_key, index)
+                index += 1
+            except OSError:
+                break
+
+    def create(self):
+        self._key(create=True)
+
+    def delete(self):
+        """Delete the entire registry key. Raises a RuntimeError if the key has
+        child keys."""
+        # If the key doesn't exist, there is nothing to do
+        if not self.exists():
+            return False
+
+        # TODO: add recursive delete?
+        for child in self.child_names():
+            # We can't delete this key if it has sub-keys. Using for loop instead
+            # of using next() so this can be used inside a contextmanager
+            if child:
+                msg = "Unable to delete key, it has sub-keys. {}".format(self)
+                raise RuntimeError(msg)
+
+        sam = self._sam(self.architecture)
+        winreg.DeleteKeyEx(self.key, self.sub_key, sam)
+        return True
+
+    def entry(self, name=None):
+        """Returns a RegEntry for the given name. To access the (Default) entry
+        pass an empty string or None.
+
+        Args:
+            name (str, optional): The name of the entry to return.
+        """
+        return RegEntry(self, name)
+
+    def entry_names(self):
+        """Generator returning the name for all entry's stored on this key."""
+        reg_key = self._key()
+        if not reg_key:
+            return
+
+        _, count, _ = winreg.QueryInfoKey(reg_key)
+        for index in range(count):
+            name, _, _ = winreg.EnumValue(reg_key, index)
+            yield name
+
+    def exists(self):
+        """Returns True if the key exists in the registry."""
+        key = self._key()
+        return key is not None
+
+    def regedit(self, multiple=True):
+        """Opens regedit to this registry key."""
+        if not self.exists():
+            raise RuntimeError("Can't open regedit to a key that doesn't exist.")
+
+        regedit_key = REG_LOCATIONS['user']['regedit']
+        reg = RegKey(*regedit_key)
+        if not reg.exists():
+            raise RuntimeError("Unable to find regedit preference {}".format(reg))
+
+        # Update the registry prefs storing the last key it had open.
+        last_key = reg.entry('LastKey')
+        computer = self.computer_name if self.computer_name else "Computer"
+        new = '\\'.join((computer, key_map.get(self.key, self.key), self.sub_key))
+        last_key.set(new, winreg.REG_SZ)
+
+        # Launch regedit
+        import subprocess
+
+        cmd = ['regedit']
+        if multiple:
+            cmd.append('/m')
+        subprocess.Popen(cmd)
+
+
+class RegEntry(object):
+    def __init__(self, key, name):
+        self.key = key
+        self.name = name
+
+    def delete(self):
+        key = self.key._key(write=True)
+        winreg.DeleteValue(key, self.name)
+        winreg.CloseKey(key)
+
+    def type(self):
+        """Returns the winreg value type."""
+        return self.value_info()[1]
+
+    def set(self, value, value_type=None):
+        key = self.key._key(write=True, create=True)
+
+        if isinstance(value_type, six.string_types):
+            value_type = getattr(winreg, value_type)
+
+        winreg.SetValueEx(key, self.name, 0, value_type, value)
+        winreg.CloseKey(key)
+        # TODO: add notify, or keep that in EnvVar?
+
+    def value(self):
+        """Returns the data value."""
+        value, _ = self.value_info()
+        # We may need to do some conversion based on type in the future.
+        return value
+
+    def value_info(self):
+        """Returns the entry value and value type.
+
+        Returns:
+            object: Value stored in key
+            int: registry type for value. See winreg's Value Types
+        """
+        return winreg.QueryValueEx(self.key._key(), self.name)