Skip to content

Decorators

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

provide.foundation.hub.decorators

Classes

Functions

register_command 

register_command(
    name: str | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any,
) -> Callable[[F], F]

register_command(func: F) -> F

register_command(
    name_or_func: str | F | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any,
) -> Any

Register a CLI command in the hub.

Can be used as a decorator with or without arguments:

@register_command
def my_command():
    pass

@register_command("custom-name", aliases=["cn"], category="utils")
def my_command():
    pass

# Nested commands using dot notation - groups are auto-created
@register_command("container.status")
def container_status():
    pass

@register_command("container.volumes.backup")
def container_volumes_backup():
    pass

# Explicit group with custom description (optional)
@register_command("container", group=True, description="Container management")
def container_group():
    pass

Parameters:

Name Type Description Default
name_or_func str | F | None

Command name using dot notation for nesting (e.g., "container.status")

 None
description str | None

Command description (defaults to docstring)

 None
aliases list[str] | None

Alternative names for the command

 None
hidden bool

Whether to hide from help listing

 False
category str | None

Command category for grouping

 None
group bool

Whether this is a command group (not a command)

 False
replace bool

Whether to replace existing registration

 False
force_options

If True, all parameters with defaults become --options (disables Position-Based Hybrid for first parameter)

 required
registry Registry | None

Custom registry (defaults to global)

 None
**metadata Any

Additional metadata stored in CommandInfo.metadata

 {}

Returns:

Type Description
Any

Decorator function or decorated function
Source code in provide/foundation/hub/decorators.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def register_command(  # type: ignore[misc]
    name_or_func: str | F | None = None,
    *,
    description: str | None = None,
    aliases: list[str] | None = None,
    hidden: bool = False,
    category: str | None = None,
    group: bool = False,
    replace: bool = False,
    registry: Registry | None = None,
    **metadata: Any,
) -> Any:
    """Register a CLI command in the hub.

    Can be used as a decorator with or without arguments:

        @register_command
        def my_command():
            pass

        @register_command("custom-name", aliases=["cn"], category="utils")
        def my_command():
            pass

        # Nested commands using dot notation - groups are auto-created
        @register_command("container.status")
        def container_status():
            pass

        @register_command("container.volumes.backup")
        def container_volumes_backup():
            pass

        # Explicit group with custom description (optional)
        @register_command("container", group=True, description="Container management")
        def container_group():
            pass

    Args:
        name_or_func: Command name using dot notation for nesting (e.g., "container.status")
        description: Command description (defaults to docstring)
        aliases: Alternative names for the command
        hidden: Whether to hide from help listing
        category: Command category for grouping
        group: Whether this is a command group (not a command)
        replace: Whether to replace existing registration
        force_options: If True, all parameters with defaults become --options
                      (disables Position-Based Hybrid for first parameter)
        registry: Custom registry (defaults to global)
        **metadata: Additional metadata stored in CommandInfo.metadata

    Returns:
        Decorator function or decorated function

    """
    # Handle @register_command (without parens)
    if callable(name_or_func) and not isinstance(name_or_func, str):
        func = name_or_func
        return _register_command_func(
            func,
            name=None,
            description=description,
            aliases=aliases,
            hidden=hidden,
            category=category,
            group=group,
            replace=replace,
            registry=registry,
            **metadata,
        )

    # Handle @register_command(...) (with arguments)
    # At this point, name_or_func must be str | None (not F)
    name_str: str | None = name_or_func if isinstance(name_or_func, str) or name_or_func is None else None

    def decorator(func: F) -> F:
        return _register_command_func(
            func,
            name=name_str,
            description=description,
            aliases=aliases,
            hidden=hidden,
            category=category,
            group=group,
            replace=replace,
            registry=registry,
            **metadata,
        )

    return decorator