Coverage for src / puzzletree / cli / __init__.py: 100.00%

1"""Puzzletree CLI application module. 

2 

3---------------- 

4 

5This module initializes the CLI for the `puzzletree` package using the Typer library. 

6It serves as the entry point for Puzzle reconstruction experiments and CLI tooling. 

7 

8Each command is defined in its respective module and registered via Typer to allow 

9for a modular and extendable CLI application. 

10 

11Once installed, the `pyproject.toml` defines the entry point as 

12 

13``` py title="pyproject.toml" 

14[project.scripts] 

15puzzletree = "puzzletree:cli" 

16``` 

17 

18since in the puzzletree `src/puzzletree/__init__.py` we have the following import 

19 

20```python title="puzzletree/__init__.py" 

21from puzzletree.cli import cli 

22``` 

23 

24Once installed this allows you to run the CLI directly from the command line using: 

25```bash 

26puzzletree [COMMAND] [OPTIONS] 

27``` 

28or 

29 

30```bash 

31uv run python -m puzzletree [COMMAND] [OPTIONS] 

32``` 

33 

34This module is designed to be run as a script, and it will automatically 

35load the appropriate subcommands based on the environment and configuration. 

36It also provides a help message when no command is specified. 

37 

38 

39Example: 

40 python -m puzzletree reconstruct --input-dir ./puzzletree-city-tiles 

41 

42Dependencies: 

43 - Typer: A modern library for building CLI applications, based on Click. 

44 - Pydantic: For data validation and settings management. 

45 - Rich: For rich text and beautiful formatting in the terminal. 

46 - Pydantic-settings: For settings management with Pydantic. 

47 

48Each subcommand is defined in its own module and registered automatically via dynamic discovery. 

49 

50**Adding New Commands:** 

51 

52To add a new CLI command, create a new Python module in the `puzzletree/cli/` directory and define a function with a `.command` attribute: 

53 

54```python 

55from typer import Context 

56 

57def my_command(ctx: Context, ...): 

58 \"\"\"My command description.\"\"\" 

59 ... 

60 

61# Mark this function as a CLI command 

62my_command.command = "my-command" 

63``` 

64 

65The command will be automatically discovered and registered when the CLI application starts. No manual registration is required. 

66 

67Subcommands can define a default behavior through the use of a @app.callback() function. This callback is invoked when the subcommand is used without specifying a sub-subcommand. 

68 

69For example, in the dataset command, the @app.callback() handles dataset loading when no sub-subcommand (like list) is provided. This enables users to run puzzletree dataset --name my_dataset directly, without needing to call a secondary command. 

70 

71If we want to add sub-subcommands (such as list), we define them using the @app.command() decorator. In this case, the callback is still invoked before the sub-subcommand is executed unless invoke_without_command=True is used, allowing for flexible pre-processing or shared setup logic. 

72 

73Commands: 

74 - Commands are automatically discovered from modules in the cli directory 

75""" 

76 

77from puzzletree.cli.main_cli import cli_app as cli (empty)

78 

79__all__: list[str] = ["cli"] (empty)