Using plugin alias that doesn't match click.group method name about click-plugins HOT 2 CLOSED

@grovduck questions are welcome! The docs definitely need some work.

This is a use case I had not considered but after poking around the behavior is, surprisingly, correct. You're on the right track with your point about entry point names matching the objects they reference. The string plugin=root_plugin.cli:main_group is a set of instructions for pkg_resources. plugin is an ID you are assigning to root_plugin.cli:main_group, which points to a Python object. In code terms:

from pkg_resources import iter_entry_points

mapping = {e.name: e.load() for e in iter_entry_points('root.plugins')}

which produces:

{'plugin': <click.core.Group at 0x10b379668>}

click then uses the Group()'s name as the subcommand name in the CLI:

mapping['plugin'].name

which defaults to the function name, which in this case is main_group.

The solution is to do @click.group(name='plugin-name') so you can reference $ root plugin-name.

Alternatively, click derives a default Group.name from the decorated function's name, so you could change the name of main_group() to plugin(). The $ foo command is correct because you're telling setuptools to install an executable called foo pointing to main_group. For the top Group() in the chain click uses the executable's name rather than Group.name. You can see this behavior by adding this snippet to your root_plugin/cli.py file and executing directly:

if __name__ == '__main__':
    main_group()

Although the displayed program name can also be changed in this case with main_group(prog_name='foo').

Caveat: if an exception is encountered in EntryPoint.load() the plugin will be registered under EntryPoint.name rather than Group.name. Executing $ root plugin will reveal the traceback.

  plugin     † Warning: could not load plugin. See `root plugin --help`.

I'll leave this ticket open and add this info to the docs.

from click-plugins.

Excellent, thanks so much @geowurster. I hadn't seen that syntax on click.group() before. Works like a charm.

from click-plugins.