diff options
| -rw-r--r-- | cmd2/argcomplete_bridge.py | 10 | ||||
| -rwxr-xr-x | cmd2/argparse_completer.py | 12 | ||||
| -rw-r--r-- | cmd2/cmd2.py | 56 | ||||
| -rw-r--r-- | cmd2/utils.py | 2 | ||||
| -rwxr-xr-x | examples/python_scripting.py | 8 | ||||
| -rwxr-xr-x | examples/table_display.py | 4 | ||||
| -rw-r--r-- | tests/conftest.py | 13 |
7 files changed, 53 insertions, 52 deletions
diff --git a/cmd2/argcomplete_bridge.py b/cmd2/argcomplete_bridge.py index 7bdb816f..51e856ef 100644 --- a/cmd2/argcomplete_bridge.py +++ b/cmd2/argcomplete_bridge.py @@ -23,16 +23,18 @@ else: import os import shlex import sys + from typing import List, Tuple, Union from . import constants from . import utils - def tokens_for_completion(line, endidx): + def tokens_for_completion(line: str, endidx: int) -> Union[Tuple[List[str], List[str], int, int], + Tuple[None, None, None, None]]: """ Used by tab completion functions to get all tokens through the one being completed - :param line: str - the current input line with leading whitespace removed - :param endidx: int - the ending index of the prefix text + :param line: the current input line with leading whitespace removed + :param endidx: the ending index of the prefix text :return: A 4 item tuple where the items are On Success tokens: list of unquoted tokens @@ -46,7 +48,7 @@ else: The last item in both lists is the token being tab completed On Failure - Both items are None + All 4 items are None """ unclosed_quote = '' quotes_to_try = copy.copy(constants.QUOTES) diff --git a/cmd2/argparse_completer.py b/cmd2/argparse_completer.py index 0e241cd9..450d793d 100755 --- a/cmd2/argparse_completer.py +++ b/cmd2/argparse_completer.py @@ -676,12 +676,12 @@ class AutoCompleter(object): """ Performs tab completion against a list - :param text: str - the string prefix we are attempting to match (all returned matches must begin with it) - :param line: str - the current input line with leading whitespace removed - :param begidx: int - the beginning index of the prefix text - :param endidx: int - the ending index of the prefix text - :param match_against: Collection - the list being matched against - :return: List[str] - a list of possible tab completions + :param text: the string prefix we are attempting to match (all returned matches must begin with it) + :param line: the current input line with leading whitespace removed + :param begidx: the beginning index of the prefix text + :param endidx: the ending index of the prefix text + :param match_against: the list being matched against + :return: a list of possible tab completions """ return [cur_match for cur_match in match_against if cur_match.startswith(text)] diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 8b1cabc9..546b03cd 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -181,7 +181,7 @@ def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser) -> Calla """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given instance of argparse.ArgumentParser, but also returning unknown args as a list. - :param argparser: argparse.ArgumentParser - given instance of ArgumentParser + :param argparser: given instance of ArgumentParser :return: function that gets passed parsed args and a list of unknown args """ import functools @@ -223,7 +223,7 @@ def with_argparser(argparser: argparse.ArgumentParser) -> Callable: """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given instance of argparse.ArgumentParser. - :param argparser: argparse.ArgumentParser - given instance of ArgumentParser + :param argparser: given instance of ArgumentParser :return: function that gets passed parsed args """ import functools @@ -553,7 +553,7 @@ class Cmd(cmd.Cmd): Also handles BrokenPipeError exceptions for when a commands's output has been piped to another process and that process terminates before the cmd2 command is finished executing. - :param msg: message to print to current stdout - anything convertible to a str with '{}'.format() is OK + :param msg: message to print to current stdout (anything convertible to a str with '{}'.format() is OK) :param end: string appended after the end of the message if not already present, default a newline """ if msg is not None and msg != '': @@ -606,7 +606,7 @@ class Cmd(cmd.Cmd): Never uses a pager inside of a script (Python or text) or when output is being redirected or piped or when stdout or stdin are not a fully functional terminal. - :param msg: message to print to current stdout - anything convertible to a str with '{}'.format() is OK + :param msg: message to print to current stdout (anything convertible to a str with '{}'.format() is OK) :param end: string appended after the end of the message if not already present, default a newline :param chop: True -> causes lines longer than the screen width to be chopped (truncated) rather than wrapped - truncated text is still accessible by scrolling with the right & left arrow keys @@ -897,14 +897,13 @@ class Cmd(cmd.Cmd): :param line: the current input line with leading whitespace removed :param begidx: the beginning index of the prefix text :param endidx: the ending index of the prefix text - :param flag_dict: dict - dictionary whose structure is the following: - keys - flags (ex: -c, --create) that result in tab completion for the next - argument in the command line - values - there are two types of values - 1. iterable list of strings to match against (dictionaries, lists, etc.) - 2. function that performs tab completion (ex: path_complete) - :param all_else: Collection or function - an optional parameter for tab completing any token that isn't preceded - by a flag in flag_dict + :param flag_dict: dictionary whose structure is the following: + keys - flags (ex: -c, --create) that result in tab completion for the next + argument in the command line + values - there are two types of values + 1. iterable list of strings to match against (dictionaries, lists, etc.) + 2. function that performs tab completion (ex: path_complete) + :param all_else: an optional parameter for tab completing any token that isn't preceded by a flag in flag_dict :return: a list of possible tab completions """ # Get all tokens through the one being completed @@ -940,14 +939,13 @@ class Cmd(cmd.Cmd): :param line: the current input line with leading whitespace removed :param begidx: the beginning index of the prefix text :param endidx: the ending index of the prefix text - :param index_dict: dict - dictionary whose structure is the following: - keys - 0-based token indexes into command line that determine which tokens - perform tab completion - values - there are two types of values - 1. iterable list of strings to match against (dictionaries, lists, etc.) - 2. function that performs tab completion (ex: path_complete) - :param all_else: Collection or function - an optional parameter for tab completing any token that isn't at an - index in index_dict + :param index_dict: dictionary whose structure is the following: + keys - 0-based token indexes into command line that determine which tokens + perform tab completion + values - there are two types of values + 1. iterable list of strings to match against (dictionaries, lists, etc.) + 2. function that performs tab completion (ex: path_complete) + :param all_else: an optional parameter for tab completing any token that isn't at an index in index_dict :return: a list of possible tab completions """ # Get all tokens through the one being completed @@ -1685,8 +1683,8 @@ class Cmd(cmd.Cmd): - raise EmptyStatement - will silently fail and do nothing - raise <AnyOtherException> - will fail and print an error message - :param statement: - the parsed command-line statement as a Statement object - :return: (bool, statement) - (stop, statement) containing a potentially modified version of the statement object + :param statement: the parsed command-line statement as a Statement object + :return: (stop, statement) containing a potentially modified version of the statement object """ stop = False return stop, statement @@ -1698,8 +1696,8 @@ class Cmd(cmd.Cmd): It even runs when an empty line is entered. Thus, if you need to do something like update the prompt due to notifications from a background thread, then this is the method you want to override to do it. - :param stop: bool - True implies the entire application should exit. - :return: bool - True implies the entire application should exit. + :param stop: True implies the entire application should exit. + :return: True implies the entire application should exit. """ return stop @@ -2031,8 +2029,8 @@ class Cmd(cmd.Cmd): If the command provided doesn't exist, then it executes _default() instead. - :param statement: Command - intended to be a Statement instance parsed command from the input stream, - alternative acceptance of a str is present only for backward compatibility with cmd + :param statement: intended to be a Statement instance parsed command from the input stream, alternative + acceptance of a str is present only for backward compatibility with cmd :return: a flag indicating whether the interpretation of commands should stop """ # For backwards compatibility with cmd, allow a str to be passed in @@ -2704,10 +2702,10 @@ Usage: Usage: unalias [-a] name [name ...] arg = arg.strip() # Support the run command even if called prior to invoking an interactive interpreter - def run(filename): + def run(filename: str): """Run a Python script file in the interactive console. - :param filename: str - filename of *.py script file to run + :param filename: filename of *.py script file to run """ try: with open(filename) as f: @@ -3436,7 +3434,7 @@ class History(list): def get(self, getme: Optional[Union[int, str]]=None) -> List[HistoryItem]: """Get an item or items from the History list using 1-based indexing. - :param getme: item(s) to get - either an integer index or string to search for + :param getme: optional item(s) to get (either an integer index or string to search for) :return: list of HistoryItems matching the retrieval criteria """ if not getme: diff --git a/cmd2/utils.py b/cmd2/utils.py index 9d71d061..735221c8 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -89,7 +89,7 @@ def cast(current: Any, new: str) -> Any: """Tries to force a new value into the same type as the current when trying to set the value for a parameter. :param current: current value for the parameter, type varies - :param new: str - new value + :param new: new value :return: new value with same type as current, or the current value if there was an error casting """ typ = type(current) diff --git a/examples/python_scripting.py b/examples/python_scripting.py index 069bcff5..ab5ecc2b 100755 --- a/examples/python_scripting.py +++ b/examples/python_scripting.py @@ -35,12 +35,12 @@ class CmdLineApp(cmd2.Cmd): self.cwd = os.getcwd() self.prompt = self.colorize('{!r} $ '.format(self.cwd), 'cyan') - def postcmd(self, stop, line): + def postcmd(self, stop: bool, line: str) -> bool: """Hook method executed just after a command dispatch is finished. - :param stop: bool - if True, the command has indicated the application should exit - :param line: str - the command line text for this command - :return: bool - if this is True, the application will exit after this command and the postloop() will run + :param stop: if True, the command has indicated the application should exit + :param line: the command line text for this command + :return: if this is True, the application will exit after this command and the postloop() will run """ """Override this so prompt always displays cwd.""" self._set_prompt() diff --git a/examples/table_display.py b/examples/table_display.py index 75eada85..63447377 100755 --- a/examples/table_display.py +++ b/examples/table_display.py @@ -151,8 +151,8 @@ class TableDisplay(cmd2.Cmd): def ptable(self, rows, columns, grid_args, row_stylist): """Format tabular data for pretty-printing as a fixed-width table and then display it using a pager. - :param rows: required argument - can be a list-of-lists (or another iterable of iterables), a two-dimensional - NumPy array, or an Iterable of non-iterable objects + :param rows: can be a list-of-lists (or another iterable of iterables), a two-dimensional + NumPy array, or an Iterable of non-iterable objects :param columns: column headers and formatting options per column :param grid_args: argparse arguments for formatting the grid :param row_stylist: function to determine how each row gets styled diff --git a/tests/conftest.py b/tests/conftest.py index a23c44d0..a85135b9 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -6,9 +6,10 @@ Copyright 2016 Federico Ceratto <federico.ceratto@gmail.com> Released under MIT license, see LICENSE file """ import sys +from typing import Optional +from unittest import mock from pytest import fixture -from unittest import mock import cmd2 @@ -156,17 +157,17 @@ def base_app(): return c -def complete_tester(text, line, begidx, endidx, app): +def complete_tester(text: str, line: str, begidx: int, endidx: int, app) -> Optional[str]: """ This is a convenience function to test cmd2.complete() since in a unit test environment there is no actual console readline is monitoring. Therefore we use mock to provide readline data to complete(). - :param text: str - the string prefix we are attempting to match - :param line: str - the current input line with leading whitespace removed - :param begidx: int - the beginning index of the prefix text - :param endidx: int - the ending index of the prefix text + :param text: the string prefix we are attempting to match + :param line: the current input line with leading whitespace removed + :param begidx: the beginning index of the prefix text + :param endidx: the ending index of the prefix text :param app: the cmd2 app that will run completions :return: The first matched string or None if there are no matches Matches are stored in app.completion_matches |