✨ Enhance command alias handling and display

[pipinstalled]

• Added support for positional and additional aliases in the command decorator.
• Updated format_commands to display command names along with their visible aliases.
• Improved command listing to maintain original order and avoid duplicates.
• Enhanced command info structure to include aliases and hidden aliases.

This improves the usability and clarity of command help output.

[github-actions]

📝 Docs preview

Last commit dc6b01a at: https://6e6e2d36.typertiangolo.pages.dev

Modified Pages

• https://6e6e2d36.typertiangolo.pages.dev/tutorial/commands/name/ - (before)

[svlandeg]

@pipinstalled: you can go ahead and set add # pragma: no cover to the pass statements in the tests, otherwise the coverage check will keep failing.

[pipinstalled]

@pipinstalled: you can go ahead and set add # pragma: no cover to the pass statements in the tests, otherwise the coverage check will keep failing.

@svlandeg I added # pragma but still coverage failed

[svlandeg]

@pipinstalled: you can go ahead and set add # pragma: no cover to the pass statements in the tests, otherwise the coverage check will keep failing.

@svlandeg I added # pragma but still coverage failed

You'll have to look into the specifics of the coverage report. What this typically means is that there's a code path that is untested, so you'd have to implement more tests to cover it.

[pipinstalled]

@tiangolo Do you have any idea when this PR will merge? :)

[basnijholt]

This is great! Right now I am hacking around it (basnijholt/compose-farm#148).

[onyx-and-iris]

This will be great, I went the route of creating a custom alias class but I recently realised it broke shell completion :/ Thanks for all the efforts you've gone to with this PR.

[svlandeg]

Thanks for the PR, @pipinstalled!

I can see how it can be useful to define an alias for a given command.

In this specific PR, there are two ways implemented to accomplish that: either by positional arguments, or using an aliases= parameter. I'm not usually keen on implementing different ways of accomplishing the same thing: it creates confusion for users and unnecessary code maintenance.

Further, there is already a way (on master) to register different names for the same command:

@app.command("list")
@app.command("ls")
@app.command("listthem", hidden=True)
def list_items():
    print("Listing items")

I know that that would show up slightly differently in the help, they would show up as separate commands. At the same time I do also worry that this PR adds a new format_commands function and edits the Rich formatting in _print_commands_panel - it feels like these are potential cases for regressions or future issues.

TLDR: I'm not convinced that this a feature we'll want to support, especially considering the amount of changes needed in core etc. I'll run this by Tiangolo though, to see what he thinks.

[svlandeg]

These should all be and instead of or, right?

[pipinstalled]

@svlandeg Thanks for the review!

That makes sense. I didn’t mean to introduce two different ways of doing the same thing — that’s definitely not ideal long term.

My main goal was to allow defining aliases while keeping them grouped as a single logical command in the help output. The existing decorator approach works, but it shows them as separate commands, which can get a bit noisy in larger CLIs.

If having both positional aliases and aliases= feels redundant, I’m totally fine simplifying this and keeping just one approach.

About the changes in format_commands and _print_commands_panel: fair point. I can take another look and see if there’s a way to reduce the surface of those changes.

Happy to adjust this based on your and @tiangolo’s thoughts.

[onyx-and-iris]

I definitely agree on just one way to define aliases, my vote would go towards the aliases= keyword.

I would also like to see an improvement on the default way of defining them. Defining multiple decorators and then hiding them from the help output seems less than ideal.

[svlandeg]

If having both positional aliases and aliases= feels redundant, I’m totally fine simplifying this and keeping just one approach.

About the changes in format_commands and _print_commands_panel: fair point. I can take another look and see if there’s a way to reduce the surface of those changes.

I think doing both of these would help increase this PR's chances of getting reviewed by Tiangolo & (hopefully) merged. I agree with @onyx-and-iris, to me the aliases keyword also seems like the nicest approach.

[github-actions]

This pull request has a merge conflict that needs to be resolved.

[github-actions]

Heads-up: this will be closed in 3 days unless there's new activity.

[github-actions]

This has been waiting for the original user for a while and seems to be inactive, so it will be closed now. If there's still interest, feel free to start a new conversation.