cli: sopel-plugins (basic version)

[Exirel]

Should fix #244 and fix #1519 at the same time.

This PR adds a new command line to Sopel: sopel-plugins.

This command line supports 4 actions:

• list, to list available plugins (all by default, or just enabled/disabled plugins)
• show, to show detailed information about a plugin
• configure, to run a config wizard for a plugin
• enable, to enable a plugin
• disable, to disable a plugin

In order to implement it, I had to update the plugin handlers, adding methods to get meta description. I think we could built from that to include other meta-data (such as version, author, etc.).

This is the first version of the command. I think it's better to stop here for now, let users test it, play with it, etc. and see what's asked.

In the future, I think we will need to rework how a plugin can expose the commands, URL callback, rules, and jobs to the outside world, but I don't want to do that in that PR, which is big enough as it is, and fairly usable to me.

sopel-plugins list

usage: sopel-plugins list [-h] [-c filename] [-C] [-e | -d] [-n]

List available Sopel plugins from all possible sources: built-in, from
``sopel_modules.*``, from ``sopel.plugins`` entry points, or Sopel's plugin
directories. Enabled plugins are displayed in green; disabled, in red.

optional arguments:
  -h, --help            show this help message and exit
  -c filename, --config filename
                        Use a specific configuration file
  -C, --no-color        Disable colors
  -e, --enabled-only    Display only enabled plugins
  -d, --disabled-only   Display only disabled plugins
  -n, --name-only       Display only plugin names

sopel-plugins show

usage: sopel-plugins show [-h] [-c filename] name

Show detailed information about a plugin.

positional arguments:
  name                  Plugin name

optional arguments:
  -h, --help            show this help message and exit
  -c filename, --config filename
                        Use a specific configuration file

sopel-plugins configure

usage: sopel-plugins configure [-h] [-c filename] name

Run a config wizard to configure a plugin. This can be used whether the plugin
is enabled or not.

positional arguments:
  name                  Plugin name

optional arguments:
  -h, --help            show this help message and exit
  -c filename, --config filename
                        Use a specific configuration file

sopel-plugins enable

usage: sopel-plugins enable [-h] [-c filename] [-a] name

Enable a Sopel plugin by its name, no matter where it comes from. The
``coretasks`` plugin is always enabled. By default, a plugin that is not
excluded is enabled, unless at least one plugin is defined in the
``core.enable`` list. In that case, Sopel uses a "allow-only" policy for
plugins, and enabled plugins must be added to this list.

positional arguments:
  name                  Name of the plugin to enable

optional arguments:
  -h, --help            show this help message and exit
  -c filename, --config filename
                        Use a specific configuration file
  -a, --allow-only      Enforce allow-only policy, adding the plugin to the
                        ``core.enable`` list.

sopel-plugins disable

usage: sopel-plugins disable [-h] [-c filename] [-f] [-r] name

Disable a Sopel plugin by its name, no matter where it comes from. It is not
possible to disable the ``coretasks`` plugin.

positional arguments:
  name                  Name of the plugin to disable

optional arguments:
  -h, --help            show this help message and exit
  -c filename, --config filename
                        Use a specific configuration file
  -f, --force           Force exclusion of the plugin. When ``core.enable`` is
                        defined, a plugin may be disabled without being
                        excluded. In this case, use this option to force its
                        exclusion.
  -r, --remove          Remove from ``core.enable`` list if applicable.

[dgw]

Couple tiny line notes, but my main point of interest is in the future evolution of cli.utils.

I'm thinking maybe the formatting bits should go in a subpackage, like cli.utils.formatting or cli.utils.text? That would be a nice place to stick things like the ANSI escape-sequence constants—which should probably have all colors added, at least, if not other things too (bold; maybe also underline, etc.).

Also, isn't color 30 black, not gray? 🤔 (And it's not used anywhere, so if you were trying to add only the formatting functions you needed… ya missed one. 😜)

[Exirel]

@dgw I changed the sopel-plugins list to have an output like this:

admin/python-module admin.py - Sopel Admin Module (sopel.modules.admin) [enabled]
coretasks/python-module Tasks that allow the bot to run, but aren't user-facing functionality (sopel.coretasks) [enabled]

and I use green for enabled plugins, red for disabled one, and yellow for enabled but that can't be loaded properly.

All I need now is #1564 to write the documentation.

[Exirel]

Update: actually it needs #1646 to be merged so I can write the doc, then, it can be merged!

[Exirel]

I added a --name-only option to sopel-plugins list.

Next step before I can hit the "ready for review", is to implement a sopel-plugins show <plugin> subcommand.

[Exirel]

And now, with sopel-plugins configure <name> in order to fix #1519

[Exirel]

And now with documentation! 🕺

[dgw]

First round! I can't run this through its paces on my CLI just yet, but I will between this and my next review.

This is all little stuff. I wouldn't even bother submitting before I can test the new CLI myself, but 1) I promised a review today and 2) there's a semi-important line note (the first one) that needs to be published anyway.

[dgw]

Since you're clearly working on this (or were very recently), I'll submit the notes I collected today.

I'm sure there will be more to come. Or maybe not… Depends on whether you want to do error-case handling and such in a future PR or just chuck it into this one. :)

[dgw]

Seems we're down to nitpick territory. 🎉

I'll open a PR momentarily to take care of sopel-config being absent from the CLI docs, so we needn't worry about that particular conversation in this PR.

[dgw]

I realized that a new PR would mean even more merge conflicts down the road, so I added sopel-config to the CLI docs myself in this PR, and also fixed the latest round of grammar nitpicks myself. 😁