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:
Batch parameters: set to individual runs
Task parameters: specified to a task
Function parameters: specified to a task function
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
.