tessl/pypi-rich-click

Format click help output nicely with rich

—

Pending

Overview

Eval results

Files

Core Decorators

Name: tessl/pypi-rich-click
Author: tessl

Essential decorators for creating rich-formatted Click commands and groups. These decorators provide the primary interface for building CLI applications with Rich-Click, offering enhanced help output, styling capabilities, and configuration options.

Capabilities

Command Decorator

Creates rich-formatted commands using RichCommand by default. Supports all Click command options while providing enhanced help formatting.

def command(name=None, cls=None, **attrs):
    """
    Command decorator function that uses RichCommand by default.
    
    Parameters:
    - name (str, optional): Name of the command
    - cls (Type[Command], optional): Command class to use, defaults to RichCommand
    - **attrs: Additional command attributes
    
    Returns:
    Union[Command, Callable]: Command object or decorator function
    """

Usage examples:

import rich_click as click

# Simple command
@click.command()
def hello():
    """A simple command."""
    click.echo("Hello!")

# Command with custom name
@click.command("greet")
def hello():
    """Greet someone."""
    click.echo("Hello!")

# Command with custom class
@click.command(cls=MyCustomRichCommand)
def hello():
    """Custom command."""
    click.echo("Hello!")

Group Decorator

Creates rich-formatted command groups using RichGroup by default. Enables creation of multi-command CLIs with enhanced formatting.

def group(name=None, cls=None, **attrs):
    """
    Group decorator function that uses RichGroup by default.
    
    Parameters:
    - name (str, optional): Name of the group
    - cls (Type[Group], optional): Group class to use, defaults to RichGroup
    - **attrs: Additional group attributes
    
    Returns:
    Union[Group, Callable]: Group object or decorator function
    """

Usage examples:

import rich_click as click

# Simple group
@click.group()
def cli():
    """A CLI application."""
    pass

@cli.command()
def hello():
    """Say hello."""
    click.echo("Hello!")

# Group with custom name
@click.group("mycli")
def cli():
    """My CLI application."""
    pass

# Group with custom class
@click.group(cls=MyCustomRichGroup)
def cli():
    """Custom group."""
    pass

Context Passing Decorator

Type-aware context passing decorator that provides RichContext instead of regular Click Context.

def pass_context(f):
    """
    Marks a callback as wanting to receive the current RichContext object as first argument.
    
    Parameters:
    - f (Callable): Function to decorate
    
    Returns:
    Callable: Decorated function that receives RichContext
    """

Usage example:

import rich_click as click

@click.command()
@click.pass_context
def hello(ctx):
    """Command that uses context."""
    # ctx is a RichContext instance
    click.echo(f"Command invoked with: {ctx.info_name}")

Rich Configuration Decorator

Decorator for configuring Rich-Click settings including help configuration and console options.

def rich_config(help_config=None, *, console=None):
    """
    Use decorator to configure Rich Click settings.
    
    Parameters:
    - help_config (Union[Mapping[str, Any], RichHelpConfiguration], optional): 
        Rich help configuration for formatting help messages and exceptions
    - console (Console, optional): Rich Console instance for the command
    
    Returns:
    Callable: Decorator function for configuring Rich settings
    
    Raises:
    - NotSupportedError: If used with incompatible command types
    """

Usage examples:

import rich_click as click
from rich.console import Console

# Basic configuration
@click.command()
@click.rich_config({"style_option": "bold red"})
def hello():
    """Configured command."""
    click.echo("Hello!")

# With custom console
console = Console(width=120)

@click.command()
@click.rich_config(console=console)
def hello():
    """Command with custom console."""
    click.echo("Hello!")

# With RichHelpConfiguration object
from rich_click import RichHelpConfiguration

config = RichHelpConfiguration(
    style_option="bold cyan",
    show_arguments=True
)

@click.command()
@click.rich_config(config)
def hello():
    """Command with configuration object."""
    click.echo("Hello!")

Exception Classes

Not Supported Error

Exception raised when rich_config decorator is used with incompatible objects.

class NotSupportedError(Exception):
    """
    Exception raised when rich_config is used with unsupported objects.
    
    Raised when rich_config decorator is applied to objects that are not
    RichCommand, RichGroup, or functions.
    """

Type Information

# Type aliases used in decorators
_AnyCallable = Callable[..., Any]
F = TypeVar("F", bound=Callable[..., Any])
FC = TypeVar("FC", bound=Union[Command, _AnyCallable])
GrpType = TypeVar("GrpType", bound=Group)
CmdType = TypeVar("CmdType", bound=Command)

Install with Tessl CLI