Skip to content

formatter

xvr.cli.formatter

CategorizedCommand 

CategorizedCommand(category_order=[], *args, **kwargs)

Click Command with support for categorized parameters.

Source code in src/xvr/cli/formatter.py 
 9
10
11
12
13
14
15
16
17
18
19
def __init__(self, category_order=[], *args, **kwargs):
    # Set default context settings
    kwargs["context_settings"] = {
        "show_default": True,
        "max_content_width": 120,
        "help_option_names": ["-h", "--help"],
    }
    super().__init__(*args, **kwargs)

    # Get categories to use as section headers in the help page
    self.category_order = category_order + ["Miscellaneous"]

format_help 

format_help(ctx, formatter)

Format help using categorized display.

Source code in src/xvr/cli/formatter.py 
21
22
23
def format_help(self, ctx, formatter):
    """Format help using categorized display."""
    format_categorized_help(self, ctx, formatter, self.category_order)

CategorizedOption 

CategorizedOption(*args, category='Miscellaneous', **kwargs)

Click Option with category support for grouped help display.

Source code in src/xvr/cli/formatter.py 
77
78
79
def __init__(self, *args, category="Miscellaneous", **kwargs):
    self.category = category
    super().__init__(*args, **kwargs)

format_categorized_help 

format_categorized_help(command, ctx, formatter, category_order: list)

Format help output with parameters grouped by category using Click's default formatting.

Source code in src/xvr/cli/formatter.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def format_categorized_help(command, ctx, formatter, category_order: list):
    """Format help output with parameters grouped by category using Click's default formatting."""

    # Use Click's default usage and description formatting
    command.format_usage(ctx, formatter)
    if command.help:
        formatter.indent()
        formatter.write_paragraph()
        formatter.write_text(command.help)
        formatter.dedent()

    # Group parameters by category
    categories = defaultdict(list)
    for param in command.params:
        if isinstance(param, click.Argument):
            continue
        category = getattr(param, "category", "Miscellaneous")
        categories[category].append(param)

    # Collect all help records first to calculate consistent spacing
    all_rows = []
    category_sections = []

    for category in category_order:
        params = categories.get(category, [])
        if not params:
            continue

        rows = []
        for param in params:
            rv = param.get_help_record(ctx)
            rows.append(rv)

        if rows:
            section_name = f"{category} options" if len(categories) > 1 else "Options"
            category_sections.append((section_name, rows))
            all_rows.extend(rows)

    # Calculate the maximum width needed across all categories
    # And print each parameter description with consistent spacing
    if all_rows:
        max_width = max(len(row[0]) for row in all_rows)
        for section_name, rows in category_sections:
            with formatter.section(section_name):
                for parameter, docstring in rows:
                    formatter.write_text(f"{parameter:<{max_width}}  {docstring}")

categorized_option 

categorized_option(*param_decls, category='Miscellaneous', **kwargs)

Decorator to add a categorized option to a command.

Source code in src/xvr/cli/formatter.py 
82
83
84
85
86
87
88
89
90
91
92
93
def categorized_option(*param_decls, category="Miscellaneous", **kwargs):
    """Decorator to add a categorized option to a command."""

    def decorator(f):
        if not hasattr(f, "__click_params__"):
            f.__click_params__ = []
        f.__click_params__.append(
            CategorizedOption(param_decls, category=category, **kwargs)
        )
        return f

    return decorator