From 06e3202f55692aa03da756233f61148db83026e8 Mon Sep 17 00:00:00 2001 From: Camilo Roca Date: Wed, 1 Jul 2015 21:56:41 +0200 Subject: [PATCH] docstring conform to PEP 484 --- scriptharness/__init__.py | 32 ++++++++++++++++----------- scriptharness/actions.py | 26 +++++++++++----------- scriptharness/commands.py | 43 ++++++++++++++++++++----------------- scriptharness/config.py | 23 ++++++++++---------- scriptharness/errorlists.py | 16 +++++++------- scriptharness/log.py | 17 ++++++++------- scriptharness/process.py | 2 +- scriptharness/script.py | 32 +++++++++++++-------------- scriptharness/structures.py | 34 ++++++++++++++--------------- scriptharness/version.py | 5 +++-- 10 files changed, 123 insertions(+), 107 deletions(-) diff --git a/scriptharness/__init__.py b/scriptharness/__init__.py index db9a7e4..0fea1a7 100644 --- a/scriptharness/__init__.py +++ b/scriptharness/__init__.py @@ -36,9 +36,9 @@ class ScriptManager(object): multiple globals that pylint would complain about. Attributes: - all_scripts (dict): a dict of name:script - action_class (class): the class to instantiate for new actions - script_class (class): the class to instantiate for new scripts + all_scripts (Dict[str, scriptharness.script.Script]): a dict of name:script + action_class (scriptharness.actions.Action): the class to instantiate for new actions + script_class (scriptharness.script.Script): the class to instantiate for new scripts """ def __init__(self): self.all_scripts = {} @@ -59,6 +59,10 @@ def get_script(self, *args, **kwargs): def get_config(self, name="root"): """Back end for scriptharness.get_config(). + + Args: + name (Optional[str]): The name of the script to get the config from. + Defaults to "root". """ if name not in self.all_scripts: raise ScriptHarnessException(os.linesep.join([ @@ -74,6 +78,10 @@ def get_config(self, name="root"): def get_logger(self, name="root"): """Back end for scriptharness.get_logger(). + + Args: + name (Optional[str]): The name of the script to get the config from. + Defaults to "root". """ if name not in self.all_scripts: raise ScriptHarnessException(os.linesep.join([ @@ -104,8 +112,8 @@ def get_script(*args, **kwargs): """This will retrieve an existing script or create one and return it. Args: - actions (tuple of Actions): When creating a new Script, - this is required. When retrieving an existing script, this is + actions (Tuple[scriptharness.actions.Action...]): When creating a new + Script, this is required. When retrieving an existing script, this is ignored/optional. parser (argparse.ArgumentParser): When creating a new Script, @@ -136,7 +144,7 @@ def get_config(name="root"): of name `name`. Returns: - config (dict): By default scriptharness.structures.LoggingDict + config (Dict[str, str]): By default scriptharness.structures.LoggingDict """ return MANAGER.get_config(name=name) @@ -158,7 +166,7 @@ def get_logger(name="root"): of name `name`. Returns: - logger (logging.Logger) + logging.Logger: logger """ return MANAGER.get_logger(name=name) @@ -185,11 +193,11 @@ def get_actions(all_actions): """Build a tuple of Action objects for the script. Args: - all_actions (data structure): ordered mapping of action_name:enabled + all_actions (Sequence[str, bool]): ordered mapping of action_name:enabled bool, as accepted by iterate_pairs() Returns: - tuple of Action objects + Tuple[scriptharness.actions.Action, ...]: tuple of Action objects """ action_list = [] for action_name, value in iterate_pairs(all_actions): @@ -201,11 +209,11 @@ def get_actions_from_list(all_actions, default_actions=None): """Helper method to generate the ordered mapping for get_actions(). Args: - all_actions (list): ordered list of all action names - default_actions (Optional[list]): actions that are enabled by default + all_actions (List[str]): ordered list of all action names + default_actions (Optional[List[str]]): actions that are enabled by default Returns: - tuple of Action objects + Tuple[scriptharness.actions.Action, ...]: tuple of Action objects """ if default_actions is None: default_actions = all_actions[:] diff --git a/scriptharness/actions.py b/scriptharness/actions.py index 5fe7f7d..69f0984 100644 --- a/scriptharness/actions.py +++ b/scriptharness/actions.py @@ -6,8 +6,8 @@ Attributes: LOGGER_NAME (str): logging.Logger name to use - STRINGS (dict): strings for actions. In the future these may be in a - function to allow for localization. + STRINGS (Dict[str, Dict[str, str]]): strings for actions. In the future + these may be in a function to allow for localization. """ from __future__ import absolute_import, division, print_function, \ unicode_literals @@ -43,7 +43,7 @@ def get_function_by_name(function_name): function_name (str): The name of the function to find. Returns: - function: the function found. + Callable[[Any], Any]: the function found. Raises: scriptharness.exceptions.ScriptHarnesException: if the function is @@ -70,14 +70,15 @@ class Action(object): enabled (bool): Enabled actions will run. Disabled actions will log the skip_message and not run. - strings (dict): Strings for action-specific log messages. + strings (Dict[str, str]): Strings for action-specific log messages. logger_name (str): The logger name for logging calls inside this object. - function (function): This is the function to call in run_function(). + function (Callable[[Any], Any]): This is the function to call in + run_function(). - history (dict): History of the action (return_value, status, start_time, - end_time). + history (Dict[str, Any]): History of the action (return_value, status, + start_time, end_time). """ def __init__(self, name, action_groups=None, function=None, enabled=True): r"""Create the Action object. @@ -85,13 +86,13 @@ def __init__(self, name, action_groups=None, function=None, enabled=True): Args: name (str): Action name, for logging. - action_groups (list): a list of action group names that this + action_groups (List[str]): a list of action group names that this Action belongs to. If scriptharness_volatile_action_group is specified in config (usually via \--action-group), all actions belonging to that action group will be enabled by default, and all others disabled by default. - function (Optional[function]). This is the function or method + function (Optional[Callable[[Any], Any]]). This is the function or method to run in run_function(). If not specified, use get_function_by_name() to find the function that matches the action name. If not found, raise. @@ -124,8 +125,8 @@ def run_function(self, context): This sets self.history['return_value'] for posterity. Args: - context (Context): the context from the calling Script - (passed from run()). + context (Context): the context from the calling Script; as defined + in `script.py`. (passed from run()). """ self.history['return_value'] = self.function(context) @@ -135,7 +136,8 @@ def run(self, context): This sets self.history timestamps and status. Args: - context (Context): the context from the calling Script. + context (Context): the context from the calling Script; as defined + in `script.py` Returns: status (int): one of SUCCESS, ERROR, or FATAL. diff --git a/scriptharness/commands.py b/scriptharness/commands.py index 339b686..49ca1c3 100644 --- a/scriptharness/commands.py +++ b/scriptharness/commands.py @@ -4,7 +4,7 @@ Attributes: LOGGER_NAME (str): default logging.Logger name. - STRINGS (dict): Strings for logging. + STRINGS (Dict[str, Dict[str, str]]): Strings for logging. """ from __future__ import absolute_import, division, print_function, \ unicode_literals @@ -75,7 +75,7 @@ def check_output(command, logger_name="scriptharness.commands.check_output", """Wrap subprocess.check_output with logging Args: - command (str or list): The command to run. + command (str or List[str]): The command to run. logger_name (Optional[str]): the logger name to log with. level (Optional[int]): the logging level to log with. Defaults to logging.INFO @@ -103,7 +103,7 @@ def detect_errors(command): Otherwise it's unsuccessful. Args: - command (Command obj): + command (Command): instance of `Command` class """ status = scriptharness.status.SUCCESS return_value = command.history.get('return_value') @@ -119,7 +119,7 @@ def detect_parsed_errors(command): to 0, the command is successful. Otherwise it's unsuccessful. Args: - command (Command obj): + command (Command): instance of `Command` class """ status = scriptharness.status.SUCCESS if command.parser.history.get('num_errors'): @@ -135,23 +135,23 @@ class Command(object): scriptharness.commands.Output object. Attributes: - command (list or string): The command to send to subprocess.Popen + command (List[str] or str): The command to send to subprocess.Popen logger (logging.Logger): logger to log with. - detect_error_cb (function): this function determines whether the - command was successful. + detect_error_cb (Callable[[Any], scriptharness.status]): this function + determines whether the command was successful. - history (dict): This dictionary holds the timestamps and status of + history (Dict[str, Any]): This dictionary holds the timestamps and status of the command. - kwargs (dict): These kwargs will be passed to subprocess.Popen, except + kwargs (Dict[Any, Any]): These kwargs will be passed to subprocess.Popen, except for the optional 'output_timeout' and 'timeout', which are processed by Command. `output_timeout` is how long a command can run without outputting anything to the screen/log. `timeout` is how long the command can run, total. - strings (dict): Strings to log. + strings (Dict[str, str]): Strings to log. """ def __init__(self, command, logger=None, detect_error_cb=None, **kwargs): self.command = command @@ -166,7 +166,7 @@ def log_env(self, env): """Log environment variables. Here for subclassing. Args: - env (dict): the environment we'll be passing to subprocess.Popen. + env (Dict[str, str]): the environment we'll be passing to subprocess.Popen. """ env = self.fix_env(env) self.logger.info(self.strings['env'], {'env': pprint.pformat(env)}) @@ -176,7 +176,10 @@ def fix_env(env): """Windows environments are fiddly. Args: - env (dict): the environment we'll be passing to subprocess.Popen. + env (Dict[str, str]): the environment we'll be passing to subprocess.Popen. + + Returns: + Dict[bytes, bytes]: copy of the env key and values but as byte strings """ if os.name == 'nt': env.setdefault("SystemRoot", os.environ["SystemRoot"]) @@ -310,7 +313,7 @@ class Output(Command): The output can be binary or text. Attributes: - strings (dict): Strings to log. + strings (Dict[str, str]): Strings to log. stdout (NamedTemporaryFile): file to log stdout to stderr (NamedTemporaryFile): file to log stderr to + all of the attributes in scriptharness.commands.Command @@ -411,7 +414,7 @@ def run(command, cmd_class=Command, halt_on_failure=False, *args, **kwargs): are explicitly trying to kill the script. Args: - command (list or str): Command line to run. + command (List[str] or str): Command line to run. cmd_class (Optional[Command subclass]): the class to instantiate. Defaults to scriptharness.commands.Command. @@ -422,7 +425,7 @@ def run(command, cmd_class=Command, halt_on_failure=False, *args, **kwargs): **kwargs: kwargs for subprocess.Popen. Returns: - command exit code (int) + int: command exit code Raises: scriptharness.exceptions.ScriptHarnessFatal: on fatal error @@ -453,11 +456,11 @@ def parse(command, **kwargs): are explicitly trying to kill the script. Args: - command (list or str): Command line to run. + command (List[str] or str): Command line to run. **kwargs: kwargs for run/ParsedCommand. Returns: - command exit code (int) + int: command exit code Raises: scriptharness.exceptions.ScriptHarnessFatal: on fatal error @@ -480,7 +483,7 @@ def get_output(command, halt_on_failure=False, **kwargs): scriptharness.unicode.to_unicode(). Args: - command (list or str): the command to use in subprocess.Popen + command (List[str] or str): the command to use in subprocess.Popen halt_on_failure (Optional[bool]): raise ScriptHarnessFatal on error if True. Default: False @@ -520,14 +523,14 @@ def get_text_output(command, level=logging.INFO, **kwargs): Because we log the output, we're assuming the output is text. Args: - command (list or str): command for subprocess.Popen + command (List[str] or str): command for subprocess.Popen level (int): logging level **kwargs: kwargs to send to scriptharness.commands.Output Returns: - output (text): the stdout from the command. + output (str): the stdout from the command. """ cmd = Output(command, **kwargs) with get_output(command, **kwargs) as cmd: diff --git a/scriptharness/config.py b/scriptharness/config.py index 2517754..011429f 100644 --- a/scriptharness/config.py +++ b/scriptharness/config.py @@ -6,7 +6,7 @@ Attributes: LOGGER_NAME (str): logging.getLogger name - SCRIPTHARNESS_INITIAL_CONFIG (dict): These key/value pairs are available + SCRIPTHARNESS_INITIAL_CONFIG (Dict[str, str]): These key/value pairs are available in all scriptharness scripts. """ from __future__ import absolute_import, division, print_function, \ @@ -48,7 +48,7 @@ def parse_config_file(path): path (str): path or url to config file. Returns: - config (dict): the parsed json dict. + config (Dict[str, Any]): the parsed json dict. Raises: scriptharness.exceptions.ScriptHarnessException: if the path is @@ -164,7 +164,7 @@ def get_list_actions_string(action_name, enabled, groups=None): Args: action_name (str): name of the action enabled (bool): whether the action is enabled by default - groups (list): a list of action_group names that the action belongs to. + groups (List[str]): a list of action_group names that the action belongs to. Returns: string (str): a line of --list-actions output. @@ -183,9 +183,9 @@ def get_action_parser(all_actions): Actions to run are specified as the argparse.REMAINDER options. Args: - all_actions (iterable): this is either all Action objects for the - script, or a data structure of pairs of action_name:enabled to pass - to iterate_pairs(). + all_actions (scriptharness.actions.Action or Sequence[str, bool]): this + is either all Action objects for the script, or a data structure of + pairs of action_name:enabled to pass to iterate_pairs(). **kwargs: additional kwargs for ArgumentParser @@ -273,7 +273,8 @@ def get_parser(all_actions=None, parents=None, **kwargs): """Create a script option parser. Args: - parents (Optional[list]): ArgumentParsers to set as parents of the parser + parents (Optional[List[ArgumentParser]]): ArgumentParsers to set as + parents of the parser. Defaults to None. **kwargs: additional kwargs for ArgumentParser Returns: @@ -293,10 +294,10 @@ def parse_args(parser, cmdln_args=None): Args: parser (ArgumentParser): specify the parser to use - cmdln_args (optional): override the commandline args with these + cmdln_args (Optional[str]): override the commandline args with these Returns: - tuple(ArgumentParser, parsed_args) + Tuple[ArgumentParser, parsed_args] """ args = [] if cmdln_args is not None: # pragma: no branch @@ -322,7 +323,7 @@ def update_dirs(config, max_depth=2): with the other dirs as the replacement dictionary. Args: - config (dict): the config to parse for scriptharness_SOMETHING_dir keys. + config (Dict[str, str]): the config to parse for scriptharness_SOMETHING_dir keys. """ repl_dict = {} for key, value in config.items(): @@ -355,7 +356,7 @@ def build_config(parser, parsed_args, initial_config=None): Args: parser (ArgumentParser): the parser used to parse_args() parsed_args (argparse Namespace): the results of parse_args() - initial_config (Optional[dict]): initial configuration to set before + initial_config (Optional[Dict[str, str]]): initial configuration to set before commandline args """ config = deepcopy(SCRIPTHARNESS_INITIAL_CONFIG) diff --git a/scriptharness/errorlists.py b/scriptharness/errorlists.py index 60a195c..380ac82 100644 --- a/scriptharness/errorlists.py +++ b/scriptharness/errorlists.py @@ -26,9 +26,9 @@ def exactly_one(key1, key2, error_check, messages): key2 (str): Dictionary key. - error_check (dict): a single item of error_list. + error_check (Dict[str, str or regex]): a single item of error_list. - messages (list): the list of error messages so far. + messages (List[str]): the list of error messages so far. Returns: Bool: True if there is exactly one of the two keys in error_check. @@ -53,8 +53,8 @@ def verify_unicode(key, error_check, messages): Args: key (str): a dict key - error_check (dict): a single item of error_list - messages (list): The error messages so far + error_check (Dict[str, str or regex]): a single item of error_list + messages (List[str]): The error messages so far """ if key in error_check and not \ isinstance(error_check[key], six.text_type): @@ -75,7 +75,7 @@ def check_ignore(strict, ignore, message, messages): strict (bool): Whether the error-checking is strict or not. ignore (bool): True when 'level' is in error_check and negative. message (str): The message to append if ignore and strict. - messages (list): The error messages so far. + messages (List[str]): The error messages so far. """ if ignore and strict: messages.append(message) @@ -94,7 +94,7 @@ def check_context_lines(context_lines, orig_context_lines, name, messages): name (str): The name of the field (pre_context_lines or post_context_lines) - messages (list): The list of error messages so far. + messages (List[str]): The list of error messages so far. Returns: int: If context_lines is a non-int or negative, an error is appended @@ -165,10 +165,10 @@ def validate_error_list(self, error_list): This is going to be a pain to unit test properly. Args: - error_list (list of dicts): an error_list. + error_list (List[Dict[str, str or regex]]): an error_list. Returns: - (pre_context_lines, post_context_lines) (tuple of int, int) + Tuple[int, int]: (pre_context_lines, post_context_lines) Raises: scriptharness.exceptions.ScriptHarnessException: if error_list is not diff --git a/scriptharness/log.py b/scriptharness/log.py index 78e5eb4..65672f7 100644 --- a/scriptharness/log.py +++ b/scriptharness/log.py @@ -99,7 +99,7 @@ def get_file_handler(path, level=logging.INFO, formatter=None, path (str): the path to the logfile. level (Optional[int]): logging level for the file. formatter (Optional[logging.Formatter]): formatter to use for logs. - logger (Optional[logging logger]): logger to add the file handler to. + logger (Optional[logging.Logger]): logger to add the file handler to. mode (Optional[str]): mode to open the file Returns: @@ -122,7 +122,7 @@ def get_console_handler(formatter=None, logger=None, level=logging.INFO): Args: formatter (Optional[logging.Formatter]): formatter to use for logs. - logger (Optional[logging logger]): logger to add the file handler to. + logger (Optional[logging.Logger]): logger to add the file handler to. level (Optional[int]): logging level for the file. Returns: @@ -146,7 +146,7 @@ class LogMethod(object): Attributes: - default_config (dict): contains the config defaults that can be + default_config (Dict[str, str]): contains the config defaults that can be overridden via __init__ kwargs. Changing default_config directly may carry over to other decorated LogMethod functions! """ @@ -188,7 +188,7 @@ def decorated_function2(...): has the empty (), the function will be sent to LogMethod.__call__() Args: - func (Optional[function]): This is the decorated function. + func (Optional[Callable[[Any, ...] Any]]): This is the decorated function. **kwargs: Contains any config options to override default_config """ self.func = func @@ -217,7 +217,7 @@ def __call__(self, func, *args, **kwargs): so we need to create and return a wrapping function. Args: - func (function): this is the decorated function. + func (Callable[[*args, **kwargs], Any]): this is the decorated function. *args: the args from the wrapped function call. **kwargs: the kwargs from the wrapped function call. """ @@ -404,7 +404,8 @@ def __init__(self, error_list, logger=None, **kwargs): """Initialization method for the OutputParser class Args: - error_list (list of dicts): list of errors to look for. + error_list (ErrorList): list of errors to look for; as defined + in `errorlists.py`. logger (Optional[logging.Logger]): logger to use. @@ -434,8 +435,8 @@ def add_buffer(self, level, messages, error_check=None): line (str): line to log - error_check (Optional[dict]): the error_check in error_list that - first matched line, if applicable. Defaults to None. + error_check (Optional[Dict[str, str or regex]]): the error_check in + error_list that first matched line, if applicable. Defaults to None. """ error_check = error_check or {} for line in messages.split('\n'): diff --git a/scriptharness/process.py b/scriptharness/process.py index 2aae4b1..b36d683 100755 --- a/scriptharness/process.py +++ b/scriptharness/process.py @@ -103,7 +103,7 @@ def watch_command(logger, queue, runner, # pylint: disable=too-many-arguments runner (multiprocessing.Process): the runner Process to watch. - add_line_cb (function): any output lines read will be sent here. + add_line_cb (Callable[[str]]): any output lines read will be sent here. max_timeout (Optional[int]): when specified, the process will be killed if it takes longer than this number of seconds. Default: None diff --git a/scriptharness/script.py b/scriptharness/script.py index 2a8a7ca..6fd2297 100644 --- a/scriptharness/script.py +++ b/scriptharness/script.py @@ -4,8 +4,8 @@ Attributes: LOGGER_NAME (str): logging.Logger name to use - LISTENER_PHASES (tuple): valid phases for Script.add_listener() - ALL_PHASES (tuple): valid phases for build_context() + LISTENER_PHASES (Tuple[str, ...]): valid phases for Script.add_listener() + ALL_PHASES (Tuple[str, ...]): valid phases for build_context() PRE_RUN (str): the pre-run phase constant POST_RUN (str): the post-run phase constant PRE_ACTION (str): the pre-action phase constant @@ -55,7 +55,7 @@ def save_config(config, path): """Save the configuration file to path as json. Args: - config (dict): The config to save + config (Dict[str, str]): The config to save path (str): The path to write the config to """ make_parent_dir(path) @@ -93,8 +93,8 @@ def enable_actions(parsed_args, action_list): as appropriate. Args: - parsed_args (argparse Namespace) - action_list (list of Actions) + parsed_args (Argparse.Namespace) + action_list (List[Action]) """ args = parsed_args.__dict__ if args.get('scriptharness_volatile_action_group') is not None: @@ -129,10 +129,10 @@ class Script(object): Attributes: config (LoggingDict): the config for the script - actions (tuple): Action objects to run. - name (string): The name of the script - listeners (dict): Callbacks for run(). Listener functions can be - set for each of LISTENER_PHASES. + actions (Tuple[Action, ...]): Action objects to run. + name (str): The name of the script + listeners (Dict[str, Tuple[Callable[], List[str]]): Callbacks for run(). + Listener functions can be set for each of LISTENER_PHASES. logger (logging.Logger): the logger for the script """ config = None @@ -141,7 +141,7 @@ def __init__(self, actions, parser, name='root', **kwargs): """Script.__init__ Args: - actions (tuple): Action objects to run. + actions (Tuple[Action]): Action objects to run. parser (ArgumentParser): parser to use name (Optional[str]): The name of the Script in scriptharness.ScriptManager @@ -171,8 +171,8 @@ def build_config(self, parser, cmdln_args=None, initial_config=None): Args: parser (ArgumentParser): parser to use to parse the commandline args. - cmdln_args (Optional[tuple]): override the commandline args - initial_config (Optional[dict]): initial config dict to apply. + cmdln_args (Optional[Tuple[str, ...]]): override the commandline args + initial_config (Optional[Dict[str, str]): initial config dict to apply. Returns: parsed_args from parse_args() @@ -219,7 +219,7 @@ def verify_actions(self, actions): by name easily. Args: - actions (list of Action objects): these are passed from __init__(). + actions (List[Action]): these are passed from __init__(). """ action_dict = collections.OrderedDict() for action in actions: @@ -257,9 +257,9 @@ def add_listener(self, listener, phase, action_names=None): those action(s). Args: - listener (function): Function to call at the right time. + listener (Callable[Any, ...] Any): Function to call at the right time. phase (str): When to run the function. Choices in LISTENER_PHASES - action_names (iterable): for pre/post action phase listeners, + action_names (Iterable[str]): for pre/post action phase listeners, only run before/after these action(s). """ for name_var in ('__qualname__', '__name__'): @@ -288,7 +288,7 @@ def run_action(self, action): """Run a specific action. Args: - action (Action object). + action (Action). Raises: scriptharness.exceptions.ScriptHarnessFatal: when the Action diff --git a/scriptharness/structures.py b/scriptharness/structures.py index d26c8a4..31b4076 100644 --- a/scriptharness/structures.py +++ b/scriptharness/structures.py @@ -13,12 +13,12 @@ Attributes: DEFAULT_LEVEL (int): the default logging level to set DEFAULT_LOGGER_NAME (str): the default logger name to use - QUOTES (tuple): the order of quotes to use for key logging - LOGGING_STRINGS (dict): a dict of strings to use for logging, for easier - unittesting and potentially for future localization. - MUTED_LOGGING_STRINGS (dict): a dict of strings to use for logging when + QUOTES (Tuple[str, ...]): the order of quotes to use for key logging + LOGGING_STRINGS (Dict[str, Dict[str, str]]): a dict of strings to use for + logging, for easier unittesting and potentially for future localization. + MUTED_LOGGING_STRINGS (Dict[str, Dict[str, str]): a dict of strings to use for logging when the values in the list/dict shouldn't be logged - SUPPORTED_LOGGING_TYPES (dict): a non-logging to logging class map, e.g. + SUPPORTED_LOGGING_TYPES (Dict[TypeVar, Class]): a non-logging to logging class map, e.g. dict: LoggingDict. Not currently supporting sets or collections. """ @@ -122,7 +122,7 @@ def iterate_pairs(data): Usage:: for key, value in iterate_pairs(data_structure):: Args: - data (data structure): a dict, iterable-of-iterable pairs + data (Sequence[Any, Any]): a dict, iterable-of-iterable pairs """ if isinstance(data, dict): if six.PY2: @@ -196,8 +196,8 @@ def _child_set_parent(self, child, child_name): """If child is a Logging* instance, set its parent and name. Args: - child: an object, which might be a Logging* instance - child_name: the name to set in the child + child (Any): an object, which might be a Logging* instance + child_name (str): the name to set in the child """ if is_logging_class(child): child.recursively_set_parent(child_name, parent=self) @@ -208,14 +208,14 @@ def ancestor_child_list(self, child_list=None): Args: - child_list (list, automatically generated): in a multi-level nested + child_list (List[str]): in a multi-level nested Logging* class, generate the list of children's names. This list will be built by prepending our name and calling ancestor_child_list() on self.parent. Returns: - (ancestor, child_list) (LoggingClass, list): for self.full_name and - self.log_change support + LoggingClass, List[str]: (ancestor, child_list) for self.full_name and + self.log_change support """ child_list = child_list or [] if self.parent: @@ -233,10 +233,10 @@ def full_name(self): Args: ancestor (Optional[LoggingClass]): specify the ancestor - child_list (Optional[list]): a list of descendents' names, in order + child_list (Optional[List[str]]): a list of descendents' names, in order Returns: - name (string): the full name of self. + str: the full name of self. """ ancestor, child_list = self.ancestor_child_list() name = ancestor.name or "" @@ -277,7 +277,7 @@ class LoggingList(LoggingClass, list): level (int): the logging level for changes logger_name (str): the logger name to use muted (bool): whether our logging messages are muted - strings (dict): a dict of strings to use for messages + strings (Dict[str, str]): a dict of strings to use for messages """ def __init__(self, items, level=DEFAULT_LEVEL, muted=False, logger_name=DEFAULT_LOGGER_NAME): @@ -433,7 +433,7 @@ class LoggingDict(LoggingClass, dict): level (int): the logging level for changes logger_name (str): the logger name to use muted (bool): whether our logging messages are muted - strings (dict): a dict of strings to use for messages + strings (Dict[str, str]): a dict of strings to use for messages """ def __init__(self, items, level=DEFAULT_LEVEL, muted=False, logger_name=DEFAULT_LOGGER_NAME): @@ -589,7 +589,7 @@ def is_logging_class(item): """Determine if a class is one of the Logging* classes. Args: - item (object): the object to check. + item (Any): the object to check. """ return issubclass(item.__class__, LoggingClass) @@ -600,7 +600,7 @@ def add_logging_to_obj(item, **kwargs): Currently supported:: list, tuple, dict. Args: - item (object): a child of a LoggingDict. + item (LoggingDict): a child of a LoggingDict. Returns: A logging version of item, when applicable, or item. diff --git a/scriptharness/version.py b/scriptharness/version.py index 0996d2d..78b63d0 100755 --- a/scriptharness/version.py +++ b/scriptharness/version.py @@ -9,7 +9,8 @@ version info. Attributes: - __version__ (tuple): semver version - three integers and an optional string. + __version__ (Tuple[int, int, int, str]): semver version - three integers and an + optional string. __version_string__ (str): semver version in string format. """ from __future__ import absolute_import, division, print_function, \ @@ -28,7 +29,7 @@ def get_version_string(version): This function exists primarily for easier unit testing. Args: - version (tuple): three ints and an optional string. + version (Tuple[int, int, int, str]): three ints and an optional string. Returns: version_string (str): the tuple translated into a string per semver.org