Accepting arguments

You can define command line arguments for your tasks by using the args parameter in the task decorator.

The args parameter accepts a list containing either:

• A string representing the argument name (e.g. --name).

• A tuple containing the argument name and a shortcut (e.g. ("--name", "-n")).

• An instance of Arg (e.g. Arg("--name", "-n")), useful for more complex arguments.

In addition, you can pass extra_args=True to the task decorator to allow unknown arguments to be passed to the task.

Arguments will be automatically parsed when the task is run, and passed as keyword arguments to the task function. If extra_args=True is set, the unknown arguments will be passed as positional arguments.

from quickie import Arg, task

@task(
    args=[
        ("--name", "-n"),  # Shortcut for Arg("--name", "-n")
        "--age",  # Shortcut for Arg("--age")
    ]
)
def hello(name, age):
    print(f"Hello, {name}! You are {age} years old.")

@task(
    args=[
        Arg("--flag", help="A flag", action="store_true"),
    ],
    extra_args=True
)
def with_extra_args(*args, flag=False):
    print(f"{args=}, {flag=}")

Forcing positional arguments

Sometimes when calling a task you want to force an argument to be treated as positional, even if it is defined as a keyword argument. This can be done by adding the arguments after --.

For example, if you have a task defined as:

@command(extra_args=True)
def commit(*args):
    return ["git", "commit", *args]

If you try to get the help message from git commit, you might try running qk commit --help, however this will will show the help message from our task instead. So what you want to do is run qk commit -- --help, which will result in --help being passed as a positional argument to the task.

Auto completion

You can also define auto-completion for your task arguments. This is done by passing a completer argument to the Arg instance. Refer to the task autocompletion section for more information.

Under the hood

Under the hood each Task defines an argparse.ArgumentParser instance. The Arg class is a simple wrapper around argparse.ArgumentParser.add_argument that allows you to define the arguments in a more convenient way and accepts the same arguments as argparse.ArgumentParser.add_argument. The only additional argument is completer, which is used for task autocompletion.

This should be enough for most use cases, but you can still inherit from Arg and override the add and set_completer methods to customize how the argument is added to the parser and how the completer is set.

Please refer to argparse.ArgumentParser.add_argument for more information on the available arguments.