Skip to content

Commit

Permalink
cli: modernize docstrings
Browse files Browse the repository at this point in the history
As usual, spelling & grammar fixed by @dgw

Co-authored-by: dgw <dgw@technobabbl.es>
  • Loading branch information
Exirel and dgw committed Aug 28, 2020
1 parent 5525ed2 commit 1532f8c
Show file tree
Hide file tree
Showing 4 changed files with 118 additions and 28 deletions.
26 changes: 20 additions & 6 deletions sopel/cli/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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')

Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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::
Expand All @@ -129,7 +136,14 @@ def handle_init(options):


def handle_get(options):
"""Read the settings to display the value of <section> <key>"""
"""Read the settings to display the value of ``<section> <key>``.
: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:
Expand All @@ -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
Expand Down
52 changes: 45 additions & 7 deletions sopel/cli/plugins.py
Original file line number Diff line number Diff line change
Expand Up @@ -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')

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
54 changes: 46 additions & 8 deletions sopel/cli/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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()
Expand Down
14 changes: 7 additions & 7 deletions sopel/cli/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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``)
Expand All @@ -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``)
Expand All @@ -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``)
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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``)
Expand Down Expand Up @@ -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``
Expand Down

0 comments on commit 1532f8c

Please sign in to comment.