From 1532f8c7349273dd1f064da176b39704c0a19c5c Mon Sep 17 00:00:00 2001 From: Florian Strzelecki Date: Mon, 10 Aug 2020 00:32:57 +0200 Subject: [PATCH] cli: modernize docstrings As usual, spelling & grammar fixed by @dgw Co-authored-by: dgw --- sopel/cli/config.py | 26 ++++++++++++++++----- sopel/cli/plugins.py | 52 ++++++++++++++++++++++++++++++++++++------ sopel/cli/run.py | 54 +++++++++++++++++++++++++++++++++++++------- sopel/cli/utils.py | 14 ++++++------ 4 files changed, 118 insertions(+), 28 deletions(-) diff --git a/sopel/cli/config.py b/sopel/cli/config.py index a8f84320f0..c2728c12c4 100644 --- a/sopel/cli/config.py +++ b/sopel/cli/config.py @@ -10,7 +10,11 @@ def build_parser(): - """Configure an argument parser for ``sopel-config``""" + """Build and configure an argument parser for ``sopel-config``. + + :return: the argument parser + :rtype: :class:`argparse.ArgumentParser` + """ parser = argparse.ArgumentParser( description='Sopel configuration tool') @@ -65,7 +69,8 @@ def handle_list(options): """Display a list of configurations available in Sopel's config directory. :param options: parsed arguments - :type options: ``argparse.Namespace`` + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine This command displays an unordered list of config names from Sopel's config directory, without their extensions:: @@ -99,10 +104,12 @@ def handle_list(options): def handle_init(options): - """Use config wizard to initialize a new configuration file for the bot + """Use config wizard to initialize a new configuration file for the bot. :param options: parsed arguments - :type options: ``argparse.Namespace`` + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the file is invalid or if it already exists .. note:: @@ -129,7 +136,14 @@ def handle_init(options): def handle_get(options): - """Read the settings to display the value of
""" + """Read the settings to display the value of ``
``. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the section and/or key does not exist; + 2 if the settings can't be loaded + """ try: settings = utils.load_settings(options) except Exception as error: @@ -154,7 +168,7 @@ def handle_get(options): def main(): - """Console entry point for ``sopel-config``""" + """Console entry point for ``sopel-config``.""" parser = build_parser() options = parser.parse_args() action = options.action diff --git a/sopel/cli/plugins.py b/sopel/cli/plugins.py index c784f09d3b..0a3e7668f4 100644 --- a/sopel/cli/plugins.py +++ b/sopel/cli/plugins.py @@ -11,7 +11,11 @@ def build_parser(): - """Configure an argument parser for ``sopel-plugins``""" + """Configure an argument parser for ``sopel-plugins``. + + :return: the argument parser + :rtype: :class:`argparse.ArgumentParser` + """ parser = argparse.ArgumentParser( description='Sopel plugins tool') @@ -149,7 +153,12 @@ def build_parser(): def handle_list(options): - """List Sopel plugins""" + """List Sopel plugins. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine + """ settings = utils.load_settings(options) no_color = options.no_color name_only = options.name_only @@ -226,7 +235,13 @@ def handle_list(options): def handle_show(options): - """Show plugin details""" + """Show plugin details. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the plugin doesn't exist or can't be loaded + """ plugin_name = options.name settings = utils.load_settings(options) usable_plugins = plugins.get_usable_plugins(settings) @@ -276,7 +291,13 @@ def handle_show(options): def handle_configure(options): - """Configure a Sopel plugin with a config wizard""" + """Configure a Sopel plugin with a config wizard. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the plugin doesn't exist or can't be loaded + """ plugin_name = options.name settings = utils.load_settings(options) usable_plugins = plugins.get_usable_plugins(settings) @@ -339,6 +360,10 @@ def _handle_disable_plugin(settings, plugin_name, force): def display_unknown_plugins(unknown_plugins): + """Print an error message when one or more plugins are unknown. + + :param list unknown_plugins: list of unknown plugins + """ # at least one of the plugins does not exist tools.stderr(utils.get_many_text( unknown_plugins, @@ -349,7 +374,14 @@ def display_unknown_plugins(unknown_plugins): def handle_disable(options): - """Disable Sopel plugins""" + """Disable Sopel plugins. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the plugin doesn't exist, + or if attempting to disable coretasks (required) + """ plugin_names = options.names force = options.force ensure_remove = options.remove @@ -450,7 +482,13 @@ def _handle_enable_plugin(settings, usable_plugins, plugin_name, allow_only): def handle_enable(options): - """Enable a Sopel plugin""" + """Enable a Sopel plugin. + + :param options: parsed arguments + :type options: :class:`argparse.Namespace` + :return: 0 if everything went fine; + 1 if the plugin doesn't exist + """ plugin_names = options.names allow_only = options.allow_only settings = utils.load_settings(options) @@ -489,7 +527,7 @@ def handle_enable(options): def main(): - """Console entry point for ``sopel-plugins``""" + """Console entry point for ``sopel-plugins``.""" parser = build_parser() options = parser.parse_args() action = options.action diff --git a/sopel/cli/run.py b/sopel/cli/run.py index 6b51936421..680990892c 100755 --- a/sopel/cli/run.py +++ b/sopel/cli/run.py @@ -49,6 +49,13 @@ def run(settings, pid_file, daemon=False): + """Run the bot with these ``settings``. + + :param settings: settings with which to run the bot + :type settings: :class:`sopel.config.Config` + :param str pid_file: path to the bot's PID file + :param bool daemon: tell if the bot should be run as a daemon + """ delay = 20 # Acts as a welcome message, showing the program and platform version at start @@ -114,6 +121,11 @@ def run(settings, pid_file, daemon=False): def add_legacy_options(parser): + """Add legacy options to the argument parser. + + :param parser: argument parser + :type parser: :class:`argparse.ArgumentParser` + """ # TL;DR: option -d/--fork is not deprecated. # When the legacy action is replaced in Sopel 8, 'start' will become the # new default action, with its arguments. @@ -170,7 +182,11 @@ def add_legacy_options(parser): def build_parser(): - """Build an ``argparse.ArgumentParser`` for the bot""" + """Build an argument parser for the bot. + + :return: the argument parser + :rtype: :class:`argparse.ArgumentParser` + """ parser = argparse.ArgumentParser(description='Sopel IRC Bot', usage='%(prog)s [options]') add_legacy_options(parser) @@ -313,7 +329,7 @@ def get_configuration(options): """Get or create a configuration object from ``options``. :param options: argument parser's options - :type options: ``argparse.Namespace`` + :type options: :class:`argparse.Namespace` :return: a configuration object :rtype: :class:`sopel.config.Config` @@ -385,7 +401,11 @@ def get_running_pid(filename): def command_start(opts): - """Start a Sopel instance""" + """Start a Sopel instance. + + :param opts: parsed arguments + :type opts: :class:`argparse.Namespace` + """ # Step One: Get the configuration file and prepare to run try: settings = get_configuration(opts) @@ -432,7 +452,11 @@ def command_start(opts): def command_configure(opts): - """Sopel Configuration Wizard""" + """Sopel Configuration Wizard. + + :param opts: parsed arguments + :type opts: :class:`argparse.Namespace` + """ configpath = utils.find_config(opts.configdir, opts.config) if opts.plugins: utils.plugins_wizard(configpath) @@ -441,7 +465,11 @@ def command_configure(opts): def command_stop(opts): - """Stop a running Sopel instance""" + """Stop a running Sopel instance. + + :param opts: parsed arguments + :type opts: :class:`argparse.Namespace` + """ # Get Configuration try: settings = utils.load_settings(opts) @@ -480,7 +508,11 @@ def command_stop(opts): def command_restart(opts): - """Restart a running Sopel instance""" + """Restart a running Sopel instance. + + :param opts: parsed arguments + :type opts: :class:`argparse.Namespace` + """ # Get Configuration try: settings = utils.load_settings(opts) @@ -513,7 +545,10 @@ def command_restart(opts): def command_legacy(opts): - """Legacy Sopel run script + """Legacy Sopel run script. + + :param opts: parsed arguments + :type opts: :class:`argparse.Namespace` The ``legacy`` command manages the old-style ``sopel`` command line tool. Most of its features are replaced by the following commands: @@ -644,7 +679,10 @@ def command_legacy(opts): def main(argv=None): - """Sopel run script entry point""" + """Sopel run script entry point. + + :param list argv: command line arguments + """ try: # Step One: Parse The Command Line parser = build_parser() diff --git a/sopel/cli/utils.py b/sopel/cli/utils.py index dc6e6c18c8..4f3623c6fd 100644 --- a/sopel/cli/utils.py +++ b/sopel/cli/utils.py @@ -39,7 +39,7 @@ def _colored(text, color, reset=True): def green(text, reset=True): - """Add ANSI escape sequences to make the text green in term + """Add ANSI escape sequences to make the text green in terminal. :param str text: text to colorized in green :param bool reset: if the text color must be reset after (default ``True``) @@ -50,7 +50,7 @@ def green(text, reset=True): def yellow(text, reset=True): - """Add ANSI escape sequences to make the text yellow in term + """Add ANSI escape sequences to make the text yellow in terminal. :param str text: text to colorized in yellow :param bool reset: if the text color must be reset after (default ``True``) @@ -61,7 +61,7 @@ def yellow(text, reset=True): def red(text, reset=True): - """Add ANSI escape sequences to make the text red in term + """Add ANSI escape sequences to make the text red in terminal. :param str text: text to colorized in red :param bool reset: if the text color must be reset after (default ``True``) @@ -72,7 +72,7 @@ def red(text, reset=True): def wizard(filename): - """Global Configuration Wizard + """Global Configuration Wizard. :param str filename: name of the new file to be created :return: the created configuration object @@ -127,7 +127,7 @@ def wizard(filename): def plugins_wizard(filename): - """Plugins Configuration Wizard + """Plugins Configuration Wizard. :param str filename: path to an existing Sopel configuration :return: the configuration object @@ -173,7 +173,7 @@ def _plugin_wizard(settings, plugin): def enumerate_configs(config_dir, extension='.cfg'): - """List configuration files from ``config_dir`` with ``extension`` + """List configuration files from ``config_dir`` with ``extension``. :param str config_dir: path to the configuration directory :param str extension: configuration file's extension (default to ``.cfg``) @@ -201,7 +201,7 @@ def enumerate_configs(config_dir, extension='.cfg'): def find_config(config_dir, name, extension='.cfg'): - """Build the absolute path for the given configuration file ``name`` + """Build the absolute path for the given configuration file ``name``. :param str config_dir: path to the configuration directory :param str name: configuration file ``name``