From 835ed070e5304f34018aed417a6f5fa53d7f59b3 Mon Sep 17 00:00:00 2001 From: tobi-wan-kenobi Date: Fri, 15 May 2020 10:22:10 +0200 Subject: [PATCH] [core/module] Add docstrings --- bumblebee_status/core/module.py | 109 +++++++++++++++++++++++++++++++- 1 file changed, 108 insertions(+), 1 deletion(-) diff --git a/bumblebee_status/core/module.py b/bumblebee_status/core/module.py index eb15833..d8faa1c 100644 --- a/bumblebee_status/core/module.py +++ b/bumblebee_status/core/module.py @@ -15,6 +15,17 @@ except Exception as e: log = logging.getLogger(__name__) +"""Loads a module by name + +:param module_name: Name of the module to load +:param config: Configuration to apply to the module (defaults to an empty configuration) +:param theme: Theme for this module, defaults to None, which means whatever is configured in "config" + +:return: A module object representing the module, or an Error module if loading failed +:rtype: class bumblebee_status.module.Module +""" + + def load(module_name, config=core.config.Config([]), theme=None): error = None module_short, alias = (module_name.split(":") + [module_name])[0:2] @@ -36,6 +47,13 @@ def load(module_name, config=core.config.Config([]), theme=None): class Module(core.input.Object): + """Represents a module (single piece of functionality) of the bar + + :param config: Configuration to apply to the module (defaults to an empty configuration) + :param theme: Theme for this module, defaults to None, which means whatever is configured in "config" + :param widgets: A list of bumblebee_status.widget.Widget objects that the module is comprised of + """ + def __init__(self, config=core.config.Config([]), theme=None, widgets=[]): super().__init__() self.__config = config @@ -52,23 +70,55 @@ class Module(core.input.Object): for widget in self.__widgets: widget.module = self + """Override this to determine when to show this module + + :return: True if the module should be hidden, False otherwise + :rtype: boolean + """ + def hidden(self): return False + """Retrieve CLI/configuration parameters for this module. For example, if + the module is called "test" and the user specifies "-p test.x=123" on the + commandline, using self.parameter("x") retrieves the value 123. + + :param key: Name of the parameter to retrieve + :param default: Default value, if parameter is not set by user (defaults to None) + + :return: Parameter value, or default + :rtype: string + """ + def parameter(self, key, default=None): value = default for prefix in [self.name, self.module_name, self.alias]: value = self.__config.get("{}.{}".format(prefix, key), value) - # TODO retrieve from config file return value + """Set a parameter for this module + + :param key: Name of the parameter to set + :param value: New value of the parameter + """ + def set(self, key, value): self.__config.set("{}.{}".format(self.name, key), value) + """Override this method to define tasks that should be done during each + update interval (for instance, querying an API, calling a CLI tool to get new + date, etc. + """ + def update(self): pass + """Wrapper method that ensures that all exceptions thrown by the + update() method are caught and displayed in a bumblebee_status.module.Error + module + """ + def update_wrapper(self): try: self.update() @@ -78,17 +128,42 @@ class Module(core.input.Object): self.__widgets = [module.widget()] self.update = module.update + """Retrieves the list of widgets for this module + + :return: A list of widgets + :rtype: list of bumblebee_status.widget.Widgets + """ + def widgets(self): return self.__widgets + """Removes all widgets of this module""" + def clear_widgets(self): del self.__widgets[:] + """Adds a widget to the module + + :param full_text: Text or callable (method) that defines the text of the widget (defaults to "") + :param name: Name of the widget, defaults to None, which means autogenerate + + :return: The new widget + :rtype: bumblebee_status.widget.Widget + """ + def add_widget(self, full_text="", name=None): widget = core.widget.Widget(full_text=full_text, name=name, module=self) self.widgets().append(widget) return widget + """Convenience method to retrieve a named widget + + :param name: Name of widget to retrieve, defaults to None (in which case the first widget is returned) + + :return: The widget with the corresponding name, None if not found + :rtype: bumblebee_status.widget.Widget + """ + def widget(self, name=None): if not name: return self.widgets()[0] @@ -98,9 +173,27 @@ class Module(core.input.Object): return w return None + """Override this method to define states for the module + + :param widget: Widget for which state should be returned + + :return: a list of states for this widget + :rtype: list of strings + """ + def state(self, widget): return [] + """Convenience method that sets warning and critical state for numbers + + :param value: Current value to calculate state against + :param warn: Warning threshold + :parm crit: Critical threshold + + :return: None if value is below both thresholds, "critical", "warning" as appropriate otherwise + :rtype: string + """ + def threshold_state(self, value, warn, crit): if value > float(self.parameter("critical", crit)): return "critical" @@ -110,14 +203,28 @@ class Module(core.input.Object): class Error(Module): + """Represents an "error" module + + :param module: The module name that produced the error + :param error: The error message to display + :param config: Configuration to apply to the module (defaults to an empty configuration) + :param theme: Theme for this module, defaults to None, which means whatever is configured in "config" + """ + def __init__(self, module, error, config=core.config.Config([]), theme=None): super().__init__(config, theme, core.widget.Widget(self.full_text)) self.__module = module self.__error = error + """Returns the error message + :param widget: the error widget to display + """ + def full_text(self, widget): return "{}: {}".format(self.__module, self.__error) + """Overriden state, always returns critical (it *is* an error, after all""" + def state(self, widget): return ["critical"]