CLI¶

Registering functions¶

Once you’ve defined your functions, you need to register them with a CLI instance.

You can register as many functions as you like with the CLI instance.

from targ import CLI


def add(a: int, b: int):
    print(a + b)


def subtract(a: int, b: int):
    print(a - b)


if __name__ == "__main__":
    cli = CLI()
    cli.register(add)
    cli.register(subtract)
    cli.run()

Coroutines¶

You can also register coroutines, as well as normal functions:

 import asyncio

 from targ import CLI


 async def timer(seconds: int):
     print(f"Sleeping for {seconds}")
     await asyncio.sleep(seconds)
     print("Finished")


if __name__ == "__main__":
   cli = CLI()
   cli.register(timer)
   cli.run()

Aliases¶

You can specify aliases for each command, which can make your CLI more convenient to use. For example, an alias could be an abbreviation, or a common mispelling.

from targ import CLI


def add(a: int, b: int):
    print(a + b)


if __name__ == "__main__":
    cli = CLI()
    cli.register(add, aliases=['+', 'sum'])
    cli.run()

All of the following will now work:

python main.py add 1 1
python main.py + 1 1
python main.py sum 1 1

Groups¶

You can add your functions / coroutines to a group:

cli.register(say_hello, 'greetings')
cli.register(add, 'maths')

And then call them as follows:

python main.py greetings say_hello 'bob'
python main.py maths add 1 2

Overriding the command name¶

By default the command name is the name of the function being registered. However, you can choose to override it:

cli.register(add, command_name='sum')

Traceback¶

By default, targ will print out an abbreviated error message if it encounters a problem. To see the full Python traceback, pass in the --trace argument.

python main.py maths add 1 'abc' --trace

Solo mode¶

Sometimes you’ll just want to register a single command with your CLI, in which case, specifying the command name is redundant.

from targ import CLI


def add(a: int, b: int):
    print(a + b)


if __name__ == "__main__":
    cli = CLI()
    cli.register(add)
    cli.run(solo=True)

You can then omit the command name:

python main.py 1 1

Source¶

class targ.CLI(description: str = 'Targ CLI')¶

The root class for building the CLI.

Example usage:

cli = CLI()
cli.register(some_function)

Parameters:: description – Customise the title of your CLI tool.

command_exists(group_name: str, command_name: str) → bool¶: This isn’t used by Targ itself, but is useful for third party code which wants to inspect the CLI, to find if a command with the given name exists.

register(command: Callable, group_name: str | None = None, command_name: str | None = None, aliases: List[str] = [])¶

Register a function or coroutine as a CLI command.

Parameters:

command – The function or coroutine to register as a CLI command.
group_name – If specified, the CLI command will belong to a group. When calling a command which belongs to a group, it must be prefixed with the group_name. For example python my_file.py group_name command_name.
command_name – By default, the name of the CLI command will be the same as the function or coroutine which is being called. You can override this here.
aliases – The command can also be accessed using these aliases.

run(solo: bool = False)¶

Run the CLI.

Parameters:: solo – By default, a command name must be given when running the CLI, for example python my_file.py command_name. In some situations, you may only have a single command registered with the CLI, so passing in the command name is redundant. If solo=True, you can omit the command name i.e. python my_file.py, and Targ will automatically call the single registered command.