Tutorials

Run a command based application with craft-cli

This tutorial will explain how to use Craft CLI to run an application that is based on commands.

Along the way you will define a simple command (named unlink, with the functionality of removing files), and call the appropriate library mechanisms for that command to be executed when running the application.

Prerequisites

Craft CLI is a standard Python library, so the best way to have it available is installed in a virtual environment.

The first step, then, is to create a virtual environment (you may skip this test if you already have one):

$ python3 -m venv env

Note that Python 3.8 or 3.9 are the supported versions.

Then enable the virtual environment and install Craft CLI:

$ source env/bin/activate
$ pip install craft-cli

Define the command and run it using the Dispatcher

First start with a class sub-classing BaseCommand with the appropriate attributes to name it and have automatic help texts, then provide a fill_parser method to declare what arguments are possible for this command, and finally a run method where the “real” functionality is implemented:

import pathlib
import textwrap
import sys
from craft_cli import (
    ArgumentParsingError,
    BaseCommand,
    CommandGroup,
    CraftError,
    Dispatcher,
    EmitterMode,
    ProvideHelpException,
    emit,
)


class RemoveFileCommand(BaseCommand):
    """Remove the indicated file."""

    name = "unlink"
    help_msg = "Remove the indicated file."
    overview = textwrap.dedent("""
        Remove the indicated file.

        A file needs to be indicated. It is an argument error if the path does not exist
        or it's a directory.

        It will return successfully if the file was properly removed.
    """)

    def fill_parser(self, parser):
        """Add own parameters to the general parser."""
        parser.add_argument("filepath", type=pathlib.Path, help="The file to be removed")

    def run(self, parsed_args):
        """Run the command."""
        if not parsed_args.filepath.exists() or parsed_args.filepath.is_dir():
            raise ArgumentParsingError("The indicated path is not a file or does not exist.")
        try:
            parsed_args.filepath.unlink()
        except Exception as exc:
            raise CraftError(f"Problem removing the file: {exc}.")

        emit.message("File removed successfully.")

Then initiate the emit object and call the Dispatcher functionality:

emit.init(EmitterMode.BRIEF, "example-app", "Starting example app v1.")
command_groups = [CommandGroup("Basic", [RemoveFileCommand])]
summary = "Example application for the craft-cli tutorial."

try:
    dispatcher = Dispatcher("example-app", command_groups, summary=summary)
    dispatcher.pre_parse_args(sys.argv[1:])
    dispatcher.load_command(None)
    dispatcher.run()
except (ArgumentParsingError, ProvideHelpException) as err:
    print(err, file=sys.stderr)  # to stderr, as argparse normally does
    emit.ended_ok()
except CraftError as err:
    emit.error(err)
except KeyboardInterrupt as exc:
    error = CraftError("Interrupted.")
    error.__cause__ = exc
    emit.error(error)
except Exception as exc:
    error = CraftError(f"Application internal error: {exc!r}")
    error.__cause__ = exc
    emit.error(error)
else:
    emit.ended_ok()

Finally, put both chunks of code in a example-app.py file, and (having the virtual environment you prepared at the beginning still activated), run it. You should see the help message for the whole application (as a command is missing, which would be the same output if you pass the help, -h or --help parameters):

$ python example-app.py
Usage:
    example-app [help] <command>

Summary:    Example application for the craft-cli tutorial.

Global options:
       -h, --help:  Show this help message and exit
    -v, --verbose:  Show debug information and be more verbose
      -q, --quiet:  Only show warnings and errors, not progress
      --verbosity:  Set the verbosity level to 'quiet', 'brief',
                    'verbose', 'debug' or 'trace'",

Starter commands:

Commands can be classified as follows:
          Example:  unlink

For more information about a command, run 'example-app help <command>'.
For a summary of all commands, run 'example-app help --all'.

Ask help for specifically for the command:

$ python example-app.py help unlink
Usage:
    example-app unlink [options] <filepath>

Summary:
    Remove the indicated file.

    A file needs to be indicated. It is an argument error if the path does not exist
    or it's a directory.

    It will return successfully if the file was properly removed.

Positional arguments:
         filepath:  The file to be removed

Options:
       -h, --help:  Show this help message and exit
    -v, --verbose:  Show debug information and be more verbose
      -q, --quiet:  Only show warnings and errors, not progress
      --verbosity:  Set the verbosity level to 'quiet', 'brief',
                    'verbose', 'debug' or 'trace'",

For a summary of all commands, run 'example-app help --all'.

Time to run the command on a file, you should see the successful message:

$ touch testfile
$ ls testfile
testfile
$ env/bin/python example-app.py unlink testfile
File removed successfully.
$ ls testfile
ls: cannot access 'testfile': No such file or directory

Explore different error situations, first trying to remove a directory, then trying to remove a file but with “unexpected” problems:

$ mkdir testdir
$ python example-app.py unlink testdir
The indicated path is not a file or does not exist.

$ touch /tmp/testfile
$ sudo chown root /tmp/testfile
$ python example-app.py unlink /tmp/testfile
Problem removing the file: [Errno 1] Operation not permitted: '/tmp/testfile'.
Full execution log: '/home/user/.cache/example-app/log/example-app-20220114-120745.861866.log'

Congratulations! You have built a complete application with good UX by using Craft CLI and implementing the functionality in one command.