Python task configuration

Configure a task's metadata as code
Task configuration defines the core metadata of an Airplane task; this includes all information like the task name and parameters aside from the actual code that is executed when the task is run.
While tasks can be initially configured in the Airplane UI, defining tasks as code is advantageous because it allows you to reap the benefits of version control; you can view the current state of a task and its history, subject tasks to the same code review and deploy mechanisms as the rest of your codebase, or roll back a task to a previous commit.
If you do edit the task configuration through the UI, you can run airplane tasks init --from your_task_slug to sync changes back to your code configuration.
Task configuration was previously accomplished using a yaml-based task definition. This new, inline task configuration allows tasks to be configured and developed in the same Python file.
To migrate from a task definition to a single-file task configuration, run airplane tasks init --from=my_slug and then copy/paste the code body into the newly created _airplane.py file.

Writing tasks

To define a task, the Python SDK provides an airplane.task(), decorator. For example:
python
Copied
1
# my_task_airplane.py
2
import airplane
3
4
@airplane.task()
5
def my_task():
6
"""This is my task defined entirely in Python!"""
7
print("Hello world!")
All functions decorated with airplane.task() will be discovered as tasks. You can even define multiple tasks in the same file!
Airplane will only discover tasks that are in files ending in _airplane.py.
python
Copied
1
import airplane
2
3
@airplane.task()
4
def my_first_task():
5
pass
6
7
@airplane.task()
8
def my_second_task():
9
pass
When you run airplane deploy, Airplane imports your task files to discover tasks. If you have any code outside of the task implementation function (including code that is imported), this code will also be executed. This allows you to define helper functions, constants, or other code that is shared across tasks, but may also cause unexpected behavior if the code has side effects.
python
Copied
1
import airplane
2
3
# You can share code between tasks by defining it outside of the task implementation function.
4
def get_airplane_task_name(slug: str) -> str:
5
return f"Airplane task {slug}"
6
7
# But be careful! This code will be executed when you run `airplane deploy`.
8
make_api_call()
9
10
@airplane.task(
11
slug="my_task",
12
name=get_airplane_task_name("my_task"),
13
)
14
def my_task():
15
print("Hello world!")

Parameters

Task parameters are inferred from the parameters of the decorated Python function.
python
Copied
1
import airplane
2
3
@airplane.task()
4
def my_task(
5
# Task accepts a `name` argument
6
name: str,
7
):
8
print(f"Hello {name}!")

Parameter types

The type hint on the function parameter determines the Parameter type of the generated task. All function parameters must have a type hint. The following table shows the supported Python types and their equivalent Airplane parameter types:
Python typeAirplane type
strshort text
airplane.LongTextlong text
airplane.SQLSQL
boolboolean
intinteger
floatnumber
airplane.Filefile
datetime.datedate
datetime.datetimedate + time
airplane.ConfigVarconfig variable

Optional parameters

Task parameters can be marked as optional via typing.Optional.
python
Copied
1
from typing import Optional
2
3
import airplane
4
5
@airplane.task()
6
def my_task(
7
# Task accepts an optional `name` argument
8
name: Optional[str],
9
):
10
if name is None:
11
print("Hellow world!")
12
else:
13
print(f"Hello {name}!")

Default parameters

Default parameter values can be specified via the Python default argument syntax.
python
Copied
1
import airplane
2
3
@airplane.task()
4
def my_task(
5
# Task accepts a `name` argument that defaults to Eric
6
name: str = "Eric",
7
):
8
print(f"Hello {name}!")

Additional configuration

See Parameter configuration for information about how to specify additional configuration for task parameters.

Examples

Attach a resource to a task and create a schedule

python
Copied
1
import airplane
2
3
@airplane.task(
4
resouces=[
5
# Attach the resource with slug "backend_db" under the alias "db"
6
airplane.Resource(
7
slug="backend_db",
8
alias="db",
9
)
10
],
11
schedules=[
12
airplane.Schedule(
13
slug="midnight_daily",
14
cron="0 0 * * *",
15
description="Runs at midnight each day",
16
param_values={
17
# Schedule must provide a value for the `text` parameter since
18
# the parameter is required.
19
"text": "param value"
20
},
21
)
22
],
23
)
24
def my_task(text: str):
25
pass

Pass environment variables to a task and set label constraints for self-hosted agents

python
Copied
1
import airplane
2
3
@airplane.task(
4
env_vars=[
5
# Set an env var with a predefined value
6
airplane.EnvVar(
7
name="MY_ENV_VAR",
8
value="MY_ENV_VAR_VALUE",
9
),
10
# Set an env var from a defined config var
11
airplane.EnvVar(
12
name="MY_ENV_VAR",
13
config_var_name="my_config_var_name",
14
),
15
],
16
# Run only on agents with label "region:us-west-2"
17
constraints={
18
"region": "us-west-2",
19
},
20
)
21
def my_task():
22
pass

Require requests for task execution and set a custom timeout

python
Copied
1
import airplane
2
3
@airplane.task(
4
# Require requests to execute
5
require_requests=True,
6
allow_self_approvals=False,
7
# Set a timeout of 200 seconds
8
timeout=200,
9
)
10
def my_task():
11
pass

Task with a date parameter that has labeled select options and a default value

python
Copied
1
import datetime
2
# For versions of Python prior to 3.9, `Annotated` can be imported from the `typing_extensions` package.
3
from typing import Annotated
4
5
import airplane
6
7
@airplane.task()
8
def my_task(
9
my_date: Annotated[
10
datetime.date,
11
airplane.ParamConfig(
12
options=[
13
airplane.LabeledOption(
14
label="first date", value=datetime.date(2019, 1, 2)
15
),
16
airplane.LabeledOption(
17
label="second date", value=datetime.date(2019, 1, 2)
18
),
19
],
20
),
21
] = datetime.date(2019, 1, 1),
22
):
23
pass

Reference

Task configuration

The airplane.task() decorator accepts the following arguments to configure a task:
airplane.task(slug, name, description=None, require_requests=False,
allow_self_approvals=True, restrict_callers=None, timeout=3600,
constraints=None, schedules=None, resources=None, env_vars=None)
slug
optional
default: function name
str
A unique identifier that ties this configuration to a task in Airplane. This cannot be changed (a different slug will end up creating a new task). Slugs must:
  • Be fewer than 50 characters long.
  • Use only lowercase letters, numbers and underscores.
  • Start with a lowercase later.
name
optional
default: function name in sentence case
str

A user-facing name for the task. This can be changed.

description
optional
str

A user-facing description for the task. Supports markdown.

require_requests
optional
default: False
bool

If true, a task must be requested before it can start executing. This disables direct execution, including schedules.

allow_self_approvals
optional
default: True
bool

If true, a request can be approved by the requestor.

restrict_callers
optional
List[Literal["task", "view"]]

The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.

timeout
optional
default: 3600 (1 hour)
int
Limits how long a task can run before it is automatically cancelled. Value is in seconds. For more information, see timeouts.
constraints
optional
Dict[str, str]
Restricts this task to run only on agents with matching labels. For more information, see Run constraints.
schedules
optional
Dict[str, airplane.Schedule]
A map from schedule slug to a schedule that automatically runs the task on a recurring cadence. For more information, see Schedule configuration.
resources
optional
List[airplane.Resource]
A list of resources to attach to this task. Once attached, a resource can be used to call Built-ins. The resource's fields can also be accessed via the AIRPLANE_RESOURCES environment variable. For more information, see resource attachments.
env_vars
optional
List[airplane.EnvVar]
Environment variables that will be passed into the task. For secrets or values that are shared across multiple tasks, environment variables can load their value from config variables.
default_run_permissions
optional
Literal["task-viewers", "task-participants"]
Manage who can view new runs of this task. For more information, see Run and session permissions.

Parameter configuration

Simple parameters are inferred from the parameters of the decorated Python function.
Additional parameter configuration can be specified using a typing.Annotated type hint annotated with an airplane.ParamConfig object. For versions of Python prior to 3.9, typing_extensions.Annotated can be used.
For example, to specify a short text parameter with select options, you can use typing.Annotated and airplane.ParamConfig like so:
python
Copied
1
# For versions of Python prior to 3.9, `Annotated` can be imported from the `typing_extensions` package.
2
from typing import Annotated
3
4
import airplane
5
6
@airplane.task()
7
def my_task(
8
# Task accepts a `name` argument that is either Eric or Beth
9
name: Annotated[
10
str,
11
airplane.ParamConfig(options=["Eric", "Beth"])
12
],
13
):
14
print(f"Hello {name}!")
The airplane.ParamConfig class accepts the following arguments to configure a parameter:
airplane.ParamConfig(slug, name, description=None, regex=None, options=None)
slug
optional
default: argument's name
str
A unique identifier for this parameter. Slugs must:
  • Be fewer than 50 characters long.
  • Use only lowercase letters, numbers and underscores.
  • Start with a lowercase later.
name
optional
default: argument's name in sentence case
str

A human-readable name that identifies this parameter.

description
optional
str

A description that renders underneath the parameter.

regex
optional
str
A regular expression to validate the provided string value. Only valid for shorttext and longtext parameters.
options
optional
List[airplane.LabeledOption]
If included, only values from the provided list will be accepted. An optional label can be provided for each option to override how these options are rendered in forms. Only valid for shorttext, longtext, sql, integer, float, date, and datetime parameters.

Schedule configuration

airplane.Schedule(slug, cron, name, description=None, param_values=None)
slug
REQUIRED
str
A unique identifier that ties this configuration to a schedule in Airplane. This cannot be changed (a different slug will end up creating a new schedule). Slugs must:
  • Be fewer than 50 characters long.
  • Use only lowercase letters, numbers and underscores.
  • Start with a lowercase later.
cron
REQUIRED
str
Cron string of the schedule. To see acceptable formats, see Cron syntax.
name
optional
default: schedule slug
str

Name of the schedule.

description
optional
str

Description of the schedule.

param_values
optional
Dict[str, Any]

Map of param slug to value to pass to the task on each run.

Docstrings

Descriptions for tasks and parameters can be optionally specified in the function's docstring. Descriptions explicitly defined in the task/parameter configuration take precedence over docstring descriptions.
python
Copied
1
import airplane
2
3
@airplane.task()
4
def my_task(name: str):
5
"""Says hello to you!
6
7
Args:
8
name: Your first and last name.
9
"""
10
print(f"Hello {name}!")
Airplane currently supports ReST, Google, Numpydoc-style and Epydoc docstrings.

YAML reference (deprecated)

Task configuration was previously accomplished using a yaml-based task definition. We recommend migrating to the new, inline task configuration allows tasks to be configured and developed in the same Python file.
To migrate from a task definition to a single-file task configuration, run airplane tasks init --from=my_slug and then copy/paste the code body into the newly created _airplane.py file.

Standard fields

The fields below apply to all task definitions, regardless of the type of task.
slug
string
REQUIRED
A unique identifier that ties this definition file to a task in Airplane. This cannot be changed (a different slug will end up creating a new task).
Slugs must:
  • Be fewer than 50 characters long
  • Use only lowercase letters, numbers, and underscores
  • Start with a lowercase letter
name
string
REQUIRED
User-facing name for the task. This can be changed.
User-facing description for the task. This can be changed.
A list of parameters. Each parameter is a user-facing field to input data into the task.
Example:
yaml
Copied
1
parameters:
2
- slug: name
3
name: Name
4
type: shorttext
5
description: The user's name.
6
default: Alfred Pennyworth
7
required: false
8
options:
9
- Alfred Pennyworth
10
- Bruce Wayne
11
regex: "^[a-zA-Z ]+$"
parameters.slug
string
REQUIRED
Unique identifier for the parameter. This is the identifier you'll use to interpolate parameters into arguments, pass them when calling from the CLI, etc.
parameters.name
string
REQUIRED
User-facing name for the parameter.
parameters.type
enum
REQUIRED
Possible Values
shorttextYour commonly used string input
longtextA string, but with a larger input box for users
sqlSimilar to Long Text inputs but offer SQL syntax highlighting
booleanPresented as on/off toggles
uploadAllows users to upload a file
Show more
The type of the parameter. See Parameter types for more information.
User-facing description of the parameter.
parameters.required
boolean
default: true
Whether the parameter is required.
parameters.default
string/number/boolean
The default value of the parameter. The type depends on the type of the parameter.
parameters.options
list of string/number/boolean/object
Constrains the value of parameter to a list of options.
The type depends on the type of the parameter.
You can optionally add a label to each option. Labels are shown to the user instead of the value. To add a label, the option should be an object with fields label and value.
Example:
yaml
Copied
1
options:
2
- Alfred Pennyworth
3
- Bruce Wayne
4
- label: BW
5
value: Bruce Wayne
For more information, see Select options.
Allows you to more dynamically control what values are permitted. For more information, see Regular expressions.
requireRequests
boolean
default: false
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
Requiring requests will disable schedules. Any existing schedules will be paused on the next attempted execution.
allowSelfApprovals
boolean
default: true
If true, a request can be approved by the requestor.
timeout
number (in seconds)
default: 3600 (1 hour)
Limits how long a task can run before it is automatically cancelled.
Maximum of 43200 (12 hours)
For more information, see timeouts.
Restricts this task to run only on agents with matching labels.
Example:
yaml
Copied
1
constraints:
2
aws-region: us-west-2
For more information, see Run constraints.
schedules
object
Mapping of unique identifiers to schedules that should be deployed with the task.
For more information, see Schedules.
Example:
yaml
Copied
1
schedules:
2
my_first_schedule:
3
cron: 0 0 * * *
4
name: My First Schedule
5
description: This is my first daily midnight UTC schedule!
6
paramValues:
7
my_first_param: my_first_param_value
The unique identifier is used to add, update and remove schedules as changes are made to the task definition file. Adding a new entry will create a new schedule, modifying an entry will update the schedule and removing an entry will pause the schedule.
The unique identifier must adhere to the slug format.
schedules.cron
string
REQUIRED
Cron string of the schedule. To see acceptable formats, see Cron syntax.
Name of the schedule.
Description of the schedule.
Map of param slugs and values to pass to the task on each run.
resources
object
Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the resource settings.
For more information on resource attachments, see resource attachments.
Example:
yaml
Copied
1
resources:
2
db: prod_postgres_db
If you would like to use the resource slug as the alias for all resources passed into this task, you can also use a list shorthand:
yaml
Copied
1
resources:
2
- prod_postgres_db
3
- prod_rest_api
defaultRunPermissions
enum
default: task-viewers
Possible Values
task-viewersAnyone who can view the task can also view the run.
task-participantsCan only be viewed by those who execute, request, or approve the run.
Manage who can view new runs of this task.

Python

python
object
Marks the task as a Python task.
Example:
yaml
Copied
1
python:
2
entrypoint: my_task.py
python.entrypoint
string
REQUIRED
The path to the .py file containing the logic for this task. This can be absolute or relative to the location of the definition file.
Examples:
yaml
Copied
1
entrypoint: my_folder/my_task.py
Environment variables that will be passed into the task.
Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.
Example:
yaml
Copied
1
envVars:
2
# From value
3
API_ENDPOINT:
4
value: api.myco.dev/
5
# From config variable
6
MY_SECRET:
7
config: MY_SECRET_CONFIG_VAR