Parameterization

Parameters are key-value pairs that are passed to the tasks. The value of a pair can be any instance or an argument which is a dynamic value. Read more about arguments in Arguments.

There are several levels of parameters:

  1. Batch parameters: set to individual runs

  2. Task parameters: specified to a task

  3. Function parameters: specified to a task function

  4. Session parameters: specified to the session

The parameters override themselves in the above order, batch parameters override task parameters and task parameters override function parameters. Only parameters with the same keys are overridden and the execution of a task can utilize all of the parameter levels.

Batch Parameters

Batch parameters are parameters set to an individual run. They are stored in batches attribute in tasks. Each run of a task consumes the oldest batch parameters. If there are none, no batch parameters are used.

Batch parameters are useful when you want to run tasks manually with other parameters than they normally run with.

Here is an example:

@app.task()
def do_things(arg):
    ...

# Getting a task instance
task = app.session[do_things]

# Setting batch run
task.run(arg="a value")

Note

The above only sets the task running once when the scheduling session starts. Typically you want to set it running depending on custom logic when the scheduler is already running, ie. when a user requests to run a task. To do so, you can create a metatask that gets the tasks that should be run manually and then set them running with correct parameters

from rocketry.conds import minutely

@app.task()
def do_things(arg):
    ...

def get_task_to_run():
    ... # Get name of the task to run
    return {
        'name': 'do_things',
        'params': {'arg': 'a value'}
    }

@app.task(minutely, execution="main")
def manual_run():

    # Get the task to run and its parameters
    task_to_run = get_task_to_run()
    task_name = task_to_run['name']
    params = task_to_run['params']

    # Set the task running with the given
    # parameters
    task = app.session[task_name]
    task.run(params)

Task Parameters

Task parameters are specified in the task initiation.

To set task parameters:

@app.task(parameters={"arg": "a value"})
def do_things(arg):
    ...

Function Parameters

Function parameters are parameters in the function’s signature.

To set function parameters:

from rocketry.args import SimpleArg

@app.task()
def do_things(arg=SimpleArg('a value')):
    ...

Note

The above example is simple but not practical. There are other dynamic argument types that are more practical such as Arg which takes value from the session parameters.

Session Parameters

Session parameters are set to the session level. They are used if nothing else were set.

To set session parameters:

from rocketry.args import SimpleArg

app.params(arg=SimpleArg('a value'))

Alternatively:

@app.param("arg")
def get_arg():
    return 'a value'

Parameters in Conditions and Parameters

Parameters can also be accessed in custom conditions and other parameters.

To use in custom condtion:

from rocketry.args import Arg

@app.cond("is foo")
def is_foo(arg=Arg("my_arg")):
    assert arg == "Hello world"
    ...
    return True

To use in custom parameter pairs:

@app.param("my_arg_2")
def get_my_arg(arg=Arg("my_arg")):
    assert arg == "Hello world"
    return "Hello world 2"

Warning

The arguments may end up in infinite recursion if argument A requests argument B and argument B requests argument A.