Hierarchy

provide.foundation.cli.click.hierarchy

Click group hierarchy management and validation.

Handles creation of Click command groups, parent group hierarchies, and validation of command registry entries.

Classes

Functions

create_subgroup

create_subgroup(
    cmd_name: str,
    entry: Any,
    groups: dict[str, Group],
    root_group: Group,
) -> None

Create a Click subgroup and add it to the appropriate parent.

Parameters:

Name	Type	Description	Default
cmd_name	str	Command name	required
entry	Any	Registry entry	required
groups	dict[str, Group]	Dictionary of existing groups	required
root_group	Group	Root group	required

Source code in provide/foundation/cli/click/hierarchy.py

def create_subgroup(cmd_name: str, entry: Any, groups: dict[str, Group], root_group: Group) -> None:
    """Create a Click subgroup and add it to the appropriate parent.

    Args:
        cmd_name: Command name
        entry: Registry entry
        groups: Dictionary of existing groups
        root_group: Root group

    """
    info = entry.metadata.get("info")
    parent = entry.metadata.get("parent")

    # Extract the actual group name (without parent prefix)
    actual_name = cmd_name.split(".")[-1] if parent else cmd_name

    subgroup = click.Group(
        name=actual_name,
        help=info.description,
        hidden=info.hidden,
    )
    groups[cmd_name] = subgroup

    # Add to parent or root
    if parent and parent in groups:
        groups[parent].add_command(subgroup)
    else:
        # Parent not found or no parent, add to root
        root_group.add_command(subgroup)

ensure_parent_groups

ensure_parent_groups(
    parent_path: str, registry: Registry
) -> None

Ensure all parent groups in the path exist, creating them if needed.

Parameters:

Name	Type	Description	Default
parent_path	str	Dot-notation path (e.g., "db.migrate")	required
registry	Registry	Command registry to update	required

Source code in provide/foundation/cli/click/hierarchy.py

def ensure_parent_groups(parent_path: str, registry: Registry) -> None:
    """Ensure all parent groups in the path exist, creating them if needed.

    Args:
        parent_path: Dot-notation path (e.g., "db.migrate")
        registry: Command registry to update

    """
    parts = parent_path.split(".")

    # Build up the path progressively
    for i in range(len(parts)):
        group_path = ".".join(parts[: i + 1])
        registry_key = group_path

        # Check if this group already exists
        if not registry.get_entry(registry_key, dimension=ComponentCategory.COMMAND.value):
            # Create a placeholder group
            def group_func() -> None:
                """Auto-generated command group."""

            # Set the function name for better debugging
            group_func.__name__ = f"{parts[i]}_group"

            # Register the group
            parent = ".".join(parts[:i]) if i > 0 else None

            from provide.foundation.hub.info import CommandInfo

            info = CommandInfo(
                name=parts[i],
                func=group_func,
                description=f"{parts[i].capitalize()} commands",
                metadata={"is_group": True, "auto_created": True},
                parent=parent,
            )

            registry.register(
                name=registry_key,
                value=group_func,
                dimension=ComponentCategory.COMMAND.value,
                metadata={
                    "info": info,
                    "description": info.description,
                    "parent": parent,
                    "is_group": True,
                    "auto_created": True,
                },
            )

            logger.debug(f"Auto-created group: {group_path}")  # type: ignore[attr-defined]

should_skip_command

should_skip_command(entry: Any) -> bool

Check if a command entry should be skipped (hidden or is a group).

Parameters:

Name	Type	Description	Default
entry	Any	Registry entry	required

Returns:

Type	Description
bool	True if command should be skipped

Source code in provide/foundation/cli/click/hierarchy.py

def should_skip_command(entry: Any) -> bool:
    """Check if a command entry should be skipped (hidden or is a group).

    Args:
        entry: Registry entry

    Returns:
        True if command should be skipped

    """
    info = entry.metadata.get("info")
    return not info or info.hidden or entry.metadata.get("is_group")

should_skip_entry

should_skip_entry(entry: Any) -> bool

Check if an entry should be skipped during processing.

Parameters:

Name	Type	Description	Default
entry	Any	Registry entry	required

Returns:

Type	Description
bool	True if entry should be skipped

Source code in provide/foundation/cli/click/hierarchy.py

def should_skip_entry(entry: Any) -> bool:
    """Check if an entry should be skipped during processing.

    Args:
        entry: Registry entry

    Returns:
        True if entry should be skipped

    """
    if not entry:
        return True

    info = entry.metadata.get("info")
    return not info

validate_command_entry

validate_command_entry(entry: Any) -> CommandInfo | None

Validate and extract command info from registry entry.

Parameters:

Name	Type	Description	Default
entry	Any	Registry entry	required

Returns:

Type	Description
CommandInfo | None	CommandInfo if valid, None otherwise

Source code in provide/foundation/cli/click/hierarchy.py

def validate_command_entry(entry: Any) -> CommandInfo | None:
    """Validate and extract command info from registry entry.

    Args:
        entry: Registry entry

    Returns:
        CommandInfo if valid, None otherwise

    """
    if not entry:
        return None

    info = entry.metadata.get("info")
    if not info:
        return None

    if not callable(info.func):
        return None

    return info