# Copyright (c) 2019 Sean Vig
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the \"Software\"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""
The objects in the command graph and command resolution on the objects
"""
import abc
import inspect
import traceback
from typing import Callable, List, Optional, Tuple, Union
from libqtile.command_graph import SelectorType
from libqtile.log_utils import logger
class SelectError(Exception):
"""Error raised in resolving a command graph object"""
def __init__(self, err_string: str, name: str, selectors: List[SelectorType]):
super().__init__("{}, name: {}, selectors: {}".format(err_string,
name,
selectors))
self.name = name
self.selectors = selectors
class CommandError(Exception):
"""Error raised in resolving a command"""
class CommandException(Exception):
"""Error raised while executing a command"""
class CommandObject(metaclass=abc.ABCMeta):
"""Base class for objects that expose commands
Each command should be a method named `cmd_X`, where X is the command name.
A CommandObject should also implement `._items()` and `._select()` methods
(c.f. docstring for `.items()` and `.select()`).
"""
def select(self, selectors: List[SelectorType]) -> "CommandObject":
"""Return a selected object
Recursively finds an object specified by a list of `(name, selector)`
items.
Raises SelectError if the object does not exist.
"""
obj = self
for name, selector in selectors:
root, items = obj.items(name)
# if non-root object and no selector given
if root is False and selector is None:
raise SelectError("", name, selectors)
# if no items in container, but selector is given
if items is None and selector is not None:
raise SelectError("", name, selectors)
# if selector is not in the list of contained items
if items is not None and selector and selector not in items:
raise SelectError("", name, selectors)
obj = obj._select(name, selector)
if obj is None:
raise SelectError("", name, selectors)
return obj
def items(self, name: str) -> Tuple[bool, List[str]]:
"""Build a list of contained items for the given item class
Returns a tuple `(root, items)` for the specified item class, where:
root: True if this class accepts a "naked" specification without an
item seletion (e.g. "layout" defaults to current layout), and False
if it does not (e.g. no default "widget").
items: a list of contained items
"""
ret = self._items(name)
if ret is None:
# Not finding information for a particular item class is OK here;
# we don't expect layouts to have a window, etc.
return False, []
return ret
@abc.abstractmethod
def _items(self, name) -> Tuple[bool, List[str]]:
"""Generate the items for a given
Same return as `.items()`. Return `None` if name is not a valid item
class.
"""
@abc.abstractmethod
def _select(self, name: str, sel: Optional[Union[str, int]]) -> "CommandObject":
"""Select the given item of the given item class
This method is called with the following guarantees:
- `name` is a valid selector class for this item
- `sel` is a valid selector for this item
- the `(name, sel)` tuple is not an "impossible" combination (e.g. a
selector is specified when `name` is not a containment object).
Return None if no such object exists
"""
def command(self, name: str) -> Callable:
"""Return the command with the given name
Parameters
----------
name : str
The name of the command to fetch.
Returns
-------
Callable
The command function that can be invoked.
"""
return getattr(self, "cmd_" + name, None)
@property
def commands(self) -> List[str]:
"""All of the commands on the given object"""
cmds = [i[4:] for i in dir(self) if i.startswith("cmd_")]
return cmds
def cmd_commands(self) -> List[str]:
"""Returns a list of possible commands for this object
Used by __qsh__ for command completion and online help
"""
return self.commands
def cmd_items(self, name) -> Tuple[bool, List[str]]:
"""Returns a list of contained items for the specified name
Used by __qsh__ to allow navigation of the object graph.
"""
return self.items(name)
def cmd_doc(self, name) -> str:
"""Returns the documentation for a specified command name
Used by __qsh__ to provide online help.
"""
if name in self.commands:
command = self.command(name)
signature = self._get_command_signature(command)
spec = name + signature
htext = inspect.getdoc(command) or ""
return spec + '\n' + htext
raise CommandError("No such command: %s" % name)
def _get_command_signature(self, command: Callable) -> str:
signature = inspect.signature(command)
args = list(signature.parameters)
if args and args[0] == "self":
args = args[1:]
parameters = [signature.parameters[arg] for arg in args]
signature = signature.replace(parameters=parameters)
return str(signature)
def cmd_eval(self, code: str) -> Tuple[bool, Optional[str]]:
"""Evaluates code in the same context as this function
Return value is tuple `(success, result)`, success being a boolean and
result being a string representing the return value of eval, or None if
exec was used instead.
"""
try:
try:
return True, str(eval(code))
except SyntaxError:
exec(code)
return True, None
except Exception:
error = traceback.format_exc().strip().split("\n")[-1]
return False, error
def cmd_function(self, function, *args, **kwargs) -> None:
"""Call a function with current object as argument"""
try:
function(self, *args, **kwargs)
except Exception:
error = traceback.format_exc()
logger.error('Exception calling "%s":\n%s', function, error)