Task arguments

The first argument of the task is the context. Any argument after that (except special arguments) are mapped from the Vim command used to invoke the task:

@task
def greet(ctx, name, city):
    print('Hello %s, how is it in %s?' % (name, city))

OP greet John Washington

Simply enough, this will print "Hello John, how is it in Washington?"

Note that all arguments are strings, and they are separated by spaces. If you need an argument with multiple works, use backslash to escape it:

OP greet John\ Smith New\ York

Quoting the arguments will not work (Vim's argument handling do not support it)

The help invoking the tasks, you can set a completion function with <task>.complete. The completion function receives a single context object, and returns all possible completions:

@greet.complete
def __greet_complete(ctx):
    return [
        'John',
        'Robert',
        'Washington',
        'Seattle',
    ]

You don't have to return a list - any iterable will do - so if it's easier you could yield the completions instead:

@greet.complete
def __greet_complete(ctx):
    yield 'John'
    yield 'Robert'
    yield 'Washington'
    yield 'Seattle'

You don't have to worry about only returning matches that have the current argument as a suffix - Omnipytent will filter them for you. What you do have to worry about is which argument you are completing - our example would suggest "Seattle" for the name argument and Robert for the city. To avoid this mashup we can use ctx.arg_name or ctx.arg_index to determine which argument we are currently completing:

@greet.complete
def __greet_complete(ctx):
    if ctx.arg_name == 'name': # or `if ctx.arg_index == 0:`
        yield 'John'
        yield 'Robert'
    elif ctx.arg_index == 1:  # or `elif ctx.arg_name == 'city':`
        yield 'Washington'
        yield 'Seattle'

See :help omnipytent-completion-context-object for other useful things you can find in this context object.

Very often it is useful for tasks to complete files and directories. For this purpose, you can import file_completer and dir_completer from the omnipytent.completers module, and use them to create completion functions for the files or directories from a certain root path:

from omnipytent.completers import file_completer


@task
def run_test_file(ctx, test_file):
    # code to run the tests in test_file


run_test_file.complete(file_completer('tests'))

And the arguments of :OP run_test_file will be the files of the tests directory and its subdirectories.

As a final note - completion functions stack, so you can call @<task>.complete multiple times and get completions from all the completion functions you provide to it.