click-command-tree

Common errors

• Error: No such command 'tree'.

  cause The `click-command-tree` plugin was not correctly registered with your Click application's root group, or the `click-plugins` dependency is missing.
  fix Ensure you have `click-plugins` installed (`pip install click-plugins`) and that your root `click.group` is decorated with `@with_plugins(importlib.metadata.entry_points(group="click_command_tree"))` (or `pkg_resources` for older Python).

• AttributeError: module 'pkg_resources' has no attribute 'iter_entry_points'

  cause `pkg_resources` is deprecated, and its `iter_entry_points` function may not be available or function as expected in newer Python environments, particularly Python 3.8+.
  fix Update your code to use `importlib.metadata.entry_points` instead of `pkg_resources.iter_entry_points`. For example: `import importlib.metadata` and then `@with_plugins(importlib.metadata.entry_points(group="click_command_tree"))`.

Warnings

• breaking The `tree` command no longer displays commands marked with `hidden=True` in their Click definition.
  Fix: If you relied on `hidden` commands appearing in the `tree` output for internal tooling or documentation, this behavior has changed. To include them, you would need to modify the `click-command-tree` source or find an alternative method.
• breaking The output format of the `tree` command was altered to include docstrings for commands and groups.
  Fix: If you were programmatically parsing the output of the `tree` command, your parsing logic may need to be updated to account for the inclusion of docstrings.
• gotcha Correctly registering the plugin requires using `click-plugins` with the appropriate entry point group, and the method for retrieving entry points (`importlib.metadata` vs `pkg_resources`) varies by Python version.
  Fix: For Python 3.8 and later, use `importlib.metadata.entry_points(group="click_command_tree")`. For older Python versions, `pkg_resources.iter_entry_points('click_command_tree')` might be necessary, though the library itself targets Python 3.8-3.12.

Install

• pip install click-command-tree Install stable version

Imports

• click

  import click

  Standard import for defining Click commands and groups.
• with_plugins

  from click_plugins import with_plugins

  Required to register `click-command-tree` as a plugin to a Click group.
• importlib.metadata.entry_points
  wrong:

  @with_plugins(pkg_resources.iter_entry_points('click_command_tree'))

  correct:

  import importlib.metadata
  @with_plugins(importlib.metadata.entry_points(group='click_command_tree'))

  `pkg_resources` is deprecated in favor of `importlib.metadata` for Python 3.8+ for accessing entry points.

Quickstart

This example creates a simple Click CLI with nested commands and demonstrates how to integrate `click-command-tree` to generate a command tree. Run `python your_cli.py tree` to see the output. Note how `delete_user` (marked `hidden=True`) is excluded from the tree output due to changes in version 1.1.1.

import click
from click_plugins import with_plugins
import importlib.metadata

@with_plugins(importlib.metadata.entry_points(group="click_command_tree"))
@click.group()
def cli():
    """A sample CLI to demonstrate click-command-tree.

    Try: `python your_cli.py tree`
    """
    pass

@cli.group()
def users():
    """Manage users.
    """
    pass

@users.command(name="add")
def add_user():
    """Add a new user.
    """
    click.echo("Adding user...")

@users.command(hidden=True)
def delete_user():
    """Delete a user (hidden command).
    """
    click.echo("Deleting user...")

@cli.command()
def config():
    """Configure settings.
    """
    click.echo("Configuring settings...")

if __name__ == '__main__':
    cli()