diff options
Diffstat (limited to 'examples')
| -rwxr-xr-x | examples/bash_completion.py | 98 | ||||
| -rwxr-xr-x | examples/python_scripting.py | 12 | ||||
| -rw-r--r-- | examples/scripts/conditional.py | 1 | ||||
| -rwxr-xr-x | examples/table_display.py | 190 |
4 files changed, 265 insertions, 36 deletions
diff --git a/examples/bash_completion.py b/examples/bash_completion.py new file mode 100755 index 00000000..6a5a2a89 --- /dev/null +++ b/examples/bash_completion.py @@ -0,0 +1,98 @@ +#!/usr/bin/env python3 +# coding=utf-8 +# PYTHON_ARGCOMPLETE_OK - This is required at the beginning of the file to enable argcomplete support +"""A simple example demonstrating integration with argcomplete. + +This example demonstrates how to achieve automatic auto-completion of argparse arguments for a command-line utility +(CLU) in the Bash shell. + +Realistically it will probably only work on Linux and then only in a Bash shell. With some effort you can probably get +it to work on macOS or Windows Subsystem for Linux (WSL); but then again, specifically within a Bash shell. This +automatic Bash completion integration with the argcomplete module is included within cmd2 in order to assist developers +with providing a the best possible out-of-the-box experience with their cmd2 applications, which in many cases will +accept argparse arguments on the command-line when executed. But from an architectural point of view, the +"argcomplete_bridge" functionality within cmd2 doesn't really depend on the rest of cmd2 and could be used in your own +CLU which doesn't use cmd2. + +WARNING: For this example to work correctly you need the argcomplete module installed and activated: + pip install argcomplete + activate-global-python-argcomplete +Please see https://github.com/kislyuk/argcomplete for more information on argcomplete. +""" +import argparse + +optional_strs = ['Apple', 'Banana', 'Cranberry', 'Durian', 'Elderberry'] + +bash_parser = argparse.ArgumentParser(prog='base') + +bash_parser.add_argument('option', choices=['load', 'export', 'reload']) + +bash_parser.add_argument('-u', '--user', help='User name') +bash_parser.add_argument('-p', '--passwd', help='Password') + +input_file = bash_parser.add_argument('-f', '--file', type=str, help='Input File') + +if __name__ == '__main__': + from cmd2.argcomplete_bridge import bash_complete + # bash_complete flags this argument telling AutoCompleter to yield to bash to perform + # tab completion of a file path + bash_complete(input_file) + +flag_opt = bash_parser.add_argument('-o', '--optional', help='Optional flag with choices') +setattr(flag_opt, 'arg_choices', optional_strs) + +# Handle bash completion if it's installed +# This early check allows the script to bail out early to provide tab-completion results +# to the argcomplete library. Putting this at the end of the file would cause the full application +# to load fulfill every tab-completion request coming from bash. This can cause a notable delay +# on the bash prompt. +try: + # only move forward if we can import CompletionFinder and AutoCompleter + from cmd2.argcomplete_bridge import CompletionFinder + from cmd2.argparse_completer import AutoCompleter + import sys + if __name__ == '__main__': + completer = CompletionFinder() + + # completer will return results to argcomplete and exit the script + completer(bash_parser, AutoCompleter(bash_parser)) +except ImportError: + pass + +# Intentionally below the bash completion code to reduce tab completion lag +import cmd2 + + +class DummyApp(cmd2.Cmd): + """ + Dummy cmd2 app + """ + + def __init__(self): + super().__init__() + + +if __name__ == '__main__': + args = bash_parser.parse_args() + + # demonstrates some handling of the command line parameters + + if args.user is None: + user = input('Username: ') + else: + user = args.user + + if args.passwd is None: + import getpass + password = getpass.getpass() + else: + password = args.passwd + + if args.file is not None: + print('Loading file: {}'.format(args.file)) + + # Clear the argumentns so cmd2 doesn't try to parse them + sys.argv = sys.argv[:1] + + app = DummyApp() + app.cmdloop() diff --git a/examples/python_scripting.py b/examples/python_scripting.py index fd2d7e8f..069bcff5 100755 --- a/examples/python_scripting.py +++ b/examples/python_scripting.py @@ -56,7 +56,7 @@ class CmdLineApp(cmd2.Cmd): if not arglist or len(arglist) != 1: self.perror("cd requires exactly 1 argument:", traceback_war=False) self.do_help('cd') - self._last_result = cmd2.CmdResult('', 'Bad arguments') + self._last_result = cmd2.CommandResult('', 'Bad arguments') return # Convert relative paths to absolute paths @@ -64,7 +64,8 @@ class CmdLineApp(cmd2.Cmd): # Make sure the directory exists, is a directory, and we have read access out = '' - err = '' + err = None + data = None if not os.path.isdir(path): err = '{!r} is not a directory'.format(path) elif not os.access(path, os.R_OK): @@ -77,10 +78,11 @@ class CmdLineApp(cmd2.Cmd): else: out = 'Successfully changed directory to {!r}\n'.format(path) self.stdout.write(out) + data = path if err: self.perror(err, traceback_war=False) - self._last_result = cmd2.CmdResult(out, err) + self._last_result = cmd2.CommandResult(out, err, data) # Enable tab completion for cd command def complete_cd(self, text, line, begidx, endidx): @@ -96,7 +98,7 @@ class CmdLineApp(cmd2.Cmd): if unknown: self.perror("dir does not take any positional arguments:", traceback_war=False) self.do_help('dir') - self._last_result = cmd2.CmdResult('', 'Bad arguments') + self._last_result = cmd2.CommandResult('', 'Bad arguments') return # Get the contents as a list @@ -109,7 +111,7 @@ class CmdLineApp(cmd2.Cmd): self.stdout.write(fmt.format(f)) self.stdout.write('\n') - self._last_result = cmd2.CmdResult(contents) + self._last_result = cmd2.CommandResult(data=contents) if __name__ == '__main__': diff --git a/examples/scripts/conditional.py b/examples/scripts/conditional.py index 87cd10ac..d7ee5ea2 100644 --- a/examples/scripts/conditional.py +++ b/examples/scripts/conditional.py @@ -30,6 +30,7 @@ app('cd {}'.format(directory)) if self._last_result: print('\nContents of directory {!r}:'.format(directory)) app('dir -l') + print('{}\n'.format(self._last_result.data)) # Change back to where we were print('Changing back to original directory: {!r}'.format(original_dir)) diff --git a/examples/table_display.py b/examples/table_display.py index 2e6ea804..75eada85 100755 --- a/examples/table_display.py +++ b/examples/table_display.py @@ -1,36 +1,145 @@ #!/usr/bin/env python # coding=utf-8 """A simple example demonstrating the following: - 1) How to display tabular data within a cmd2 application + 1) How to display tabular data 2) How to display output using a pager NOTE: IF the table does not entirely fit within the screen of your terminal, then it will be displayed using a pager. You can use the arrow keys (left, right, up, and down) to scroll around the table as well as the PageUp/PageDown keys. You can quit out of the pager by typing "q". You can also search for text within the pager using "/". -WARNING: This example requires the tabulate module. +WARNING: This example requires the tableformatter module: https://github.com/python-tableformatter/tableformatter +- pip install tableformatter """ -import functools +import argparse +from typing import Tuple import cmd2 -import tabulate +import tableformatter as tf -# Format to use with tabulate module when displaying tables -TABLE_FORMAT = 'grid' +# Configure colors for when users chooses the "-c" flag to enable color in the table output +try: + from colored import bg + BACK_PRI = bg(4) + BACK_ALT = bg(22) +except ImportError: + try: + from colorama import Back + BACK_PRI = Back.LIGHTBLUE_EX + BACK_ALT = Back.LIGHTYELLOW_EX + except ImportError: + BACK_PRI = '' + BACK_ALT = '' + + +# Formatter functions +def no_dec(num: float) -> str: + """Format a floating point number with no decimal places.""" + return "{}".format(round(num)) + + +def two_dec(num: float) -> str: + """Format a floating point number with 2 decimal places.""" + return "{0:.2f}".format(num) -# Create a function to format a fixed-width table for pretty-printing using the desired table format -table = functools.partial(tabulate.tabulate, tablefmt=TABLE_FORMAT) # Population data from Wikipedia: https://en.wikipedia.org/wiki/List_of_cities_proper_by_population -EXAMPLE_DATA = [['Shanghai', 'Shanghai', 'China', 'Asia', 24183300, 6340.5, 3814], - ['Beijing', 'Hebei', 'China', 'Asia', 20794000, 1749.57, 11885], - ['Karachi', 'Sindh', 'Pakistan', 'Asia', 14910352, 615.58, 224221], - ['Shenzen', 'Guangdong', 'China', 'Asia', 13723000, 1493.32, 9190], - ['Guangzho', 'Guangdong', 'China', 'Asia', 13081000, 1347.81, 9705], - ['Mumbai', ' Maharashtra', 'India', 'Asia', 12442373, 465.78, 27223], - ['Istanbul', 'Istanbul', 'Turkey', 'Eurasia', 12661000, 620.29, 20411], - ] -EXAMPLE_HEADERS = ['City', 'Province', 'Country', 'Continent', 'Population', 'Area (km^2)', 'Pop. Density (/km^2)'] + +# ############ Table data formatted as an iterable of iterable fields ############ +EXAMPLE_ITERABLE_DATA = [['Shanghai (上海)', 'Shanghai', 'China', 'Asia', 24183300, 6340.5], + ['Beijing (北京市)', 'Hebei', 'China', 'Asia', 20794000, 1749.57], + ['Karachi (کراچی)', 'Sindh', 'Pakistan', 'Asia', 14910352, 615.58], + ['Shenzen (深圳市)', 'Guangdong', 'China', 'Asia', 13723000, 1493.32], + ['Guangzho (广州市)', 'Guangdong', 'China', 'Asia', 13081000, 1347.81], + ['Mumbai (मुंबई)', 'Maharashtra', 'India', 'Asia', 12442373, 465.78], + ['Istanbul (İstanbuld)', 'Istanbul', 'Turkey', 'Eurasia', 12661000, 620.29], + ] + +# Calculate population density +for row in EXAMPLE_ITERABLE_DATA: + row.append(row[-2]/row[-1]) + + +# Column headers plus optional formatting info for each column +COLUMNS = [tf.Column('City', width=11, header_halign=tf.ColumnAlignment.AlignCenter), + tf.Column('Province', header_halign=tf.ColumnAlignment.AlignCenter), + 'Country', # NOTE: If you don't need any special effects, you can just pass a string + tf.Column('Continent', cell_halign=tf.ColumnAlignment.AlignCenter), + tf.Column('Population', cell_halign=tf.ColumnAlignment.AlignRight, formatter=tf.FormatCommas()), + tf.Column('Area (km²)', width=7, header_halign=tf.ColumnAlignment.AlignCenter, + cell_halign=tf.ColumnAlignment.AlignRight, formatter=two_dec), + tf.Column('Pop. Density (/km²)', width=12, header_halign=tf.ColumnAlignment.AlignCenter, + cell_halign=tf.ColumnAlignment.AlignRight, formatter=no_dec), + ] + + +# ######## Table data formatted as an iterable of python objects ######### + +class CityInfo(object): + """City information container""" + def __init__(self, city: str, province: str, country: str, continent: str, population: int, area: float): + self.city = city + self.province = province + self.country = country + self.continent = continent + self._population = population + self._area = area + + def get_population(self): + """Population of the city""" + return self._population + + def get_area(self): + """Area of city in km²""" + return self._area + + +def pop_density(data: CityInfo) -> str: + """Calculate the population density from the data entry""" + if not isinstance(data, CityInfo): + raise AttributeError("Argument to pop_density() must be an instance of CityInfo") + return no_dec(data.get_population() / data.get_area()) + + +# Convert the Iterable of Iterables data to an Iterable of non-iterable objects for demonstration purposes +EXAMPLE_OBJECT_DATA = [] +for city_data in EXAMPLE_ITERABLE_DATA: + # Pass all city data other than population density to construct CityInfo + EXAMPLE_OBJECT_DATA.append(CityInfo(*city_data[:-1])) + +# If table entries are python objects, all columns must be defined with the object attribute to query for each field +# - attributes can be fields or functions. If a function is provided, the formatter will automatically call +# the function to retrieve the value +OBJ_COLS = [tf.Column('City', attrib='city', header_halign=tf.ColumnAlignment.AlignCenter), + tf.Column('Province', attrib='province', header_halign=tf.ColumnAlignment.AlignCenter), + tf.Column('Country', attrib='country'), + tf.Column('Continent', attrib='continent', cell_halign=tf.ColumnAlignment.AlignCenter), + tf.Column('Population', attrib='get_population', cell_halign=tf.ColumnAlignment.AlignRight, + formatter=tf.FormatCommas()), + tf.Column('Area (km²)', attrib='get_area', width=7, header_halign=tf.ColumnAlignment.AlignCenter, + cell_halign=tf.ColumnAlignment.AlignRight, formatter=two_dec), + tf.Column('Pop. Density (/km²)', width=12, header_halign=tf.ColumnAlignment.AlignCenter, + cell_halign=tf.ColumnAlignment.AlignRight, obj_formatter=pop_density), + ] + + +EXTREMELY_HIGH_POULATION_DENSITY = 25000 + + +def high_density_tuples(row_tuple: Tuple) -> dict: + """Color rows with extremely high population density red.""" + opts = dict() + if len(row_tuple) >= 7 and row_tuple[6] > EXTREMELY_HIGH_POULATION_DENSITY: + opts[tf.TableFormatter.ROW_OPT_TEXT_COLOR] = tf.TableColors.TEXT_COLOR_RED + return opts + + +def high_density_objs(row_obj: CityInfo) -> dict: + """Color rows with extremely high population density red.""" + opts = dict() + if float(pop_density(row_obj)) > EXTREMELY_HIGH_POULATION_DENSITY: + opts[tf.TableFormatter.ROW_OPT_TEXT_COLOR] = tf.TableColors.TEXT_COLOR_RED + return opts class TableDisplay(cmd2.Cmd): @@ -39,26 +148,45 @@ class TableDisplay(cmd2.Cmd): def __init__(self): super().__init__() - def ptable(self, tabular_data, headers=()): + 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 tabular_data: required argument - can be a list-of-lists (or another iterable of iterables), a list of - named tuples, a dictionary of iterables, an iterable of dictionaries, a two-dimensional - NumPy array, NumPy record array, or a Pandas dataframe. - :param headers: (optional) - to print nice column headers, supply this argument: - - headers can be an explicit list of column headers - - if `headers="firstrow"`, then the first row of data is used - - if `headers="keys"`, then dictionary keys or column indices are used - - Otherwise, a headerless table is produced + :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 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 """ - formatted_table = table(tabular_data, headers=headers) - self.ppaged(formatted_table) + if grid_args.color: + grid = tf.AlternatingRowGrid(BACK_PRI, BACK_ALT) + elif grid_args.fancy: + grid = tf.FancyGrid() + elif grid_args.sparse: + grid = tf.SparseGrid() + else: + grid = None + + formatted_table = tf.generate_table(rows=rows, columns=columns, grid_style=grid, row_tagger=row_stylist) + self.ppaged(formatted_table, chop=True) + + table_parser = argparse.ArgumentParser() + table_item_group = table_parser.add_mutually_exclusive_group() + table_item_group.add_argument('-c', '--color', action='store_true', help='Enable color') + table_item_group.add_argument('-f', '--fancy', action='store_true', help='Fancy Grid') + table_item_group.add_argument('-s', '--sparse', action='store_true', help='Sparse Grid') + + @cmd2.with_argparser(table_parser) + def do_table(self, args): + """Display data in iterable form on the Earth's most populated cities in a table.""" + self.ptable(EXAMPLE_ITERABLE_DATA, COLUMNS, args, high_density_tuples) - def do_table(self, _): - """Display data on the Earth's most populated cities in a table.""" - self.ptable(tabular_data=EXAMPLE_DATA, headers=EXAMPLE_HEADERS) + @cmd2.with_argparser(table_parser) + def do_object_table(self, args): + """Display data in object form on the Earth's most populated cities in a table.""" + self.ptable(EXAMPLE_OBJECT_DATA, OBJ_COLS, args, high_density_objs) if __name__ == '__main__': app = TableDisplay() + app.debug = True app.cmdloop() |