6. Developing fox CLI

fox CLI is primary a tool to interact with the foxBMS 2 repository through the command line. All commands must therefore be implemented as a part of it. The fox CLI implementation is found in the cli/-directory at the root of the repository.

6.1. Adding a New Command

When a new tool, i.e., a command needs to be implemented the following steps need to be done (exemplary new command my-command):

  • Add a new file cli/cmd_my_command/my_command_impl.py which implements the main entrance function of this command.

  • Add a new file cli/commands/c_my_command.py that implements the command line interface of the tool.

    import click
    
    from ..cmd_my_command import my_command_impl
    
    # Add the new CLI commands afterwards using click, e.g., as follows:
    @click.command("my-command")
    @click.pass_context
    def run_my_command(ctx: click.Context) -> None:
        """Add help message here"""
        # my_command_impl.do_something must return a `SubprocessResult` object
        # pass the CLI arguments to `do_something` if additional arguments
        # and/or options are needed
        ret = my_command_impl.do_something()
        ctx.exit(ret.returncode)
    
  • In cli/cli.py add the new command to the cli:

    # add import of the command
    from .commands.c_my_command import my_command
    # add the command to the application
    # ...
    main.add_command(my_command)
    # ...
    

Adhere to the following rules when using click:

  • Always import click as import click and do not use from click import ..., except when you are

    • only using echo and/or secho or

    • are testing click application using CliRunner.

  • Use cli/helpers/click_helpers.py for common click options (except for CAN, see next point)

  • When the tool uses CAN communication use the cli/helpers/fcan.py to handle the CLI arguments.

  • When using a verbosity flag, @verbosity_option SHALL be the second last decorator.

  • @click.pass_context SHALL be the last decorator.

6.2. Directory Description

6.2.1. Directories

Table 6.8 Directory description of the cli directory

Directory Name

Long Name

Content Description

cmd_*

Command_*

Actual implementation of the specific CLI command

commands

Commands

Implementation of the command line interface of each tool

helpers

Helpers

Helper functions that are used by several parts of the CLI tool

fallback

Fallback

Fallback for the fox CLI wrappers when the environment is missing

pre-commit

pre-commit

Scripts that are run as part of the pre-commit framework

6.2.2. Files

  • cli/cli.py: registers all commands.

  • cli/foxbms_version.py: Reads the foxBMS 2 version information from the single source of truth for the version information, the wscript at the root of the repository.

6.3. Unit Tests

  • Unit tests for the fox CLI shall be implemented in tests/cli.

  • The command line interface for each command shall be tested in tests/cli/commands/*, where each command uses its own file to tests its interface.

  • Each tool shall then be tested in the appropiate subdirectory, e.g., cli/cmd_etl/batetl/etl/can_decode.py is then tested in tests/cli/cmd_etl/batetl/etl/test_can_decode.py.