Repository navigation
deprecate MultiCommand, merge into Group #2590
Description
As part of rewriting the parser in #2205, I was looking at the complexities of Click's definitions and processing. MultiCommand and CommandCollection could be combined with Group to simplify to a single way of working with multiple commands. This is a little more difficult than #2589 removing BaseCommand.
Currently, they're distinct because Group provides further group and command decorators. MultiCommand is the base and doesn't specify how commands are registered, and CommandCollection "flattens" multiple MultiCommands instead of nesting like Group.group.
The docs occasionally refer to "mulitcommand" instead of "group" in situations where the user would probably understand "group" better. There are very few examples in the docs of either class, and all of them can be reasonably implemented with Group instead.
#347 (and many linked issues) show a confusion over how CommandCollection is supposed to work. It doesn't use each source's parameters, and doesn't invoke the source's callback before a command. In other words, currently the collection only collects the commands in each source, but users expect it to merge the behavior of all sources. I'm not entirely convinced that we should continue to support either of these things. But we could continue to support the current behavior by adding Group.add_source or extend_commands with the same behavior, where the command is looked up first on the group, then on each source. In the future we could also add a merge_group method.
Activity
davidism commentedon Aug 18, 2023
To expand on why I'm not convinced that we should support flattening or merging groups, in general it's because it adds ambiguity and indirection when defining the CLI. Whether you flatten or merge, there's probably a way to get the source's callback called before its command. But there's no convenient way to merge different group's parameters, especially in the face of overlapping or conflicting parameters. It's something that any given project can make a call on, but that Click would have a hard time implementing in a generic and compatible way for all cases.
davidism commentedon Aug 18, 2023
@janluke @kdeldycke any feedback on this is appreciated
[-]deprecate `MultiCommand` and `CommandCollection`[/-][+]deprecate `MultiCommand` and `CommandCollection`, merge into `Group`[/+]davidism commentedon Aug 19, 2023
A search for
CommandCollectionon SourceGraph shows that it's in use. Some of those uses seem to be unnecessary. Many are for loading plugins that add top-level commands, where a customGroup.get_commandwould probably serve them better. I'll leave it for now and make it a subclass ofGroup.[-]deprecate `MultiCommand` and `CommandCollection`, merge into `Group`[/-][+]deprecate `MultiCommand`, merge into `Group`[/+]kdeldycke commentedon Aug 20, 2023
I agree
CommandCollectionis confusing. I never had any use for that, and when working on Click Extra, I voluntarily ignored it, thinking it was too exotic. My rationale was to focus only on good support forCommandandGroupas they are the first-class citizen of the Click ecosystem. Then see if my users were asking forCommandCollection. Nobody came forCommandCollection.So if you can get rid of
CommandCollection, I vote for.Just noticed you also just got rid of
MultiCommand, and yes, that's also a good idea!