Panels - Tips

There are a few things to keep in mind when using RichPanels.

Handling --help option

The help option is associated with the default options panel.

If you define all the panels, the --help option will be left straggling in the default panel.

This is probably a mistake, and there are two ways to fix it:

MistakeFix (method 1)Fix (method 2)

# /// script
# dependencies = ["rich-click>=1.9"]
# ///
import rich_click as click

# The --help option will just be in its own panel at the top.
# This is probably not what is intended!
@click.command()
@click.option("--src", panel="Main")
@click.option("--dest", panel="Main")
@click.option("--env", panel="Extra")
@click.option("--log-level", panel="Extra")
def move_item(src, dest, env, log_level):
    """Move an item from a src location to a dest location"""
    pass

if __name__ == "__main__":
    move_item()

Output - Mistake

# /// script
# dependencies = ["rich-click>=1.9"]
# ///
import rich_click as click

# Explicitly define the panels and place --help in Extra:
@click.command()
@click.option("--src", panel="Main")
@click.option("--dest", panel="Main")
@click.option("--env", panel="Extra")
@click.option("--log-level", panel="Extra")
@click.option_panel("Main")
@click.option_panel("Extra", options=["--env", "--log-level", "--help"])
def move_item(src, dest, env, log_level):
    """Move an item from a src location to a dest location"""
    pass

if __name__ == "__main__":
    move_item()

Output - Fix (method 1)

# /// script
# dependencies = ["rich-click>=1.9"]
# ///
import rich_click as click

# Explicitly define the help_option() and set its panel.
@click.command()
@click.option("--src", panel="Main")
@click.option("--dest", panel="Main")
@click.option("--env", panel="Extra")
@click.option("--log-level", panel="Extra")
@click.help_option(panel="Extra")
def move_item(src, dest, env, log_level):
    """Move an item from a src location to a dest location"""
    pass

if __name__ == "__main__":
    move_item()

Output - Fix (method 2)

Sort order of panels

Panels are printed in the order that they are defined, from top to bottom.

@click.option_panel("first")
@click.command_panel("second")
@click.option_panel("third")

If panels are inferred from @click.option(panel=...), rather than defined by @click.option_panel(), then they are defined in the order that they appear in parameters from top to bottom.

The simplest way to control the order panels is to define them explicitly!

This also means that you can order options panels to come before command panels, and vice-versa, based on the decorator order.

Ordering of rows within panels

The easiest way to control the order of elements within a panel is to explicitly define the order within the panel itself.

If you are having trouble with ordering things, set the order within options= or commands=.

Additionally, it is suggested you set every object you intend on including in the panel.

# /// script
# dependencies = ["rich-click>=1.9"]
# ///
import rich_click as click

@click.command()
@click.option("--src", panel="Main")
@click.option("--dest", panel="Main")
@click.option("--env")
@click.option("--log-level")
@click.option_panel("Extra", options=["env", "log_level", "help"])
def move_item(src, dest, env, log_level):
    """Move an item from a src location to a dest location"""
    pass

if __name__ == "__main__":
    move_item()

Output

That said, the default behavior is also predictable and follows what base Click does for ordering:

• Arguments + options are presented in the order they occur in the decorators, from top to bottom.
• Subcommands are alphanumerically sorted.