Python task configuration
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
_airplane.py
file.Writing tasks
airplane.task()
, decorator. For example:pythonCopied1# my_task_airplane.py2import airplane34@airplane.task()5def my_task():6"""This is my task defined entirely in Python!"""7print("Hello world!")
airplane.task()
will be discovered as tasks. You can even define
multiple tasks in the same file!_airplane.py
.pythonCopied1import airplane23@airplane.task()4def my_first_task():5pass67@airplane.task()8def my_second_task():9pass
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.pythonCopied1import airplane23# You can share code between tasks by defining it outside of the task implementation function.4def get_airplane_task_name(slug: str) -> str:5return f"Airplane task {slug}"67# But be careful! This code will be executed when you run `airplane deploy`.8make_api_call()910@airplane.task(11slug="my_task",12name=get_airplane_task_name("my_task"),13)14def my_task():15print("Hello world!")
Parameters
pythonCopied1import airplane23@airplane.task()4def my_task(5# Task accepts a `name` argument6name: str,7):8print(f"Hello {name}!")
Parameter types
Python type | Airplane type |
---|---|
str | short text |
airplane.LongText | long text |
airplane.SQL | SQL |
bool | boolean |
int | integer |
float | number |
airplane.File | file |
datetime.date | date |
datetime.datetime | date + time |
airplane.ConfigVar | config variable |
airplane.JSON | JSON |
List
.Optional parameters
typing.Optional
.pythonCopied1from typing import Optional23import airplane45@airplane.task()6def my_task(7# Task accepts an optional `name` argument8name: Optional[str],9):10if name is None:11print("Hellow world!")12else:13print(f"Hello {name}!")
Default parameters
pythonCopied1import airplane23@airplane.task()4def my_task(5# Task accepts a `name` argument that defaults to Eric6name: str = "Eric",7):8print(f"Hello {name}!")
Additional configuration
Examples
Attach a resource to a task and create a schedule
pythonCopied1import airplane23@airplane.task(4resources=[5# Attach the resource with slug "backend_db" under the alias "db"6airplane.Resource(7slug="backend_db",8alias="db",9)10],11schedules=[12airplane.Schedule(13slug="midnight_daily",14cron="0 0 * * *",15description="Runs at midnight each day",16param_values={17# Schedule must provide a value for the `text` parameter since18# the parameter is required.19"text": "param value"20},21)22],23)24def my_task(text: str):25pass
Manage granular task permissions in code
pythonCopied1import airplane23@airplane.task(4permissions=airplane.ExplicitPermissions(5viewers=airplane.PermissionAssignees(groups=["support"]),6executers=airplane.PermissionAssignees(users=["jordan@airplane.dev"]),7)8)9def my_task(text: str):10pass
Pass environment variables to a task and set label constraints for self-hosted agents
pythonCopied1import airplane23@airplane.task(4env_vars=[5# Set an env var with a predefined value6airplane.EnvVar(7name="MY_ENV_VAR",8value="MY_ENV_VAR_VALUE",9),10# Set an env var from a defined config var11airplane.EnvVar(12name="MY_ENV_VAR",13config_var_name="my_config_var_name",14),15],16# Run only on agents with label "region:us-west-2"17constraints={18"region": "us-west-2",19},20)21def my_task():22pass
Require requests for task execution and set a custom timeout
pythonCopied1import airplane23@airplane.task(4# Require requests to execute5require_requests=True,6allow_self_approvals=False,7# Set a timeout of 200 seconds8timeout=200,9)10def my_task():11pass
Task with a date parameter that has labeled select options and a default value
pythonCopied1import datetime2# For versions of Python prior to 3.9, `Annotated` can be imported from the `typing_extensions` package.3from typing import Annotated45import airplane67@airplane.task()8def my_task(9my_date: Annotated[10datetime.date,11airplane.ParamConfig(12options=[13airplane.LabeledOption(14label="first date", value=datetime.date(2019, 1, 2)15),16airplane.LabeledOption(17label="second date", value=datetime.date(2019, 1, 2)18),19],20),21] = datetime.date(2019, 1, 1),22):23pass
Reference
Task configuration
airplane.task()
decorator accepts the following arguments to configure a task:- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
A user-facing name for the task. This can be changed.
A user-facing description for the task. Supports markdown.
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
If true, a request can be approved by the requestor.
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.
AIRPLANE_RESOURCES
environment variable. For more information, see resource attachments.Parameter configuration
typing.Annotated
type hint
annotated with an airplane.ParamConfig
object. For versions of Python prior to 3.9,
typing_extensions.Annotated
can be used.typing.Annotated
and airplane.ParamConfig
like so:pythonCopied1# For versions of Python prior to 3.9, `Annotated` can be imported from the `typing_extensions` package.2from typing import Annotated34import airplane56@airplane.task()7def my_task(8# Task accepts a `name` argument that is either Eric or Beth9name: Annotated[10str,11airplane.ParamConfig(options=["Eric", "Beth"])12],13):14print(f"Hello {name}!")
airplane.ParamConfig
class accepts the following arguments to configure a parameter:- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
A human-readable name that identifies this parameter.
A description that renders underneath the parameter.
shorttext
and longtext
parameters.A validation function that returns a string if the value is invalid, or null
if the value is valid. The function is evaluated as a JS template and can refer to other parameters by using the params
keyword.
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. The values can either be hardcoded, or can be dynamically generated by a task by providing a slug
and optional params
. For more information, See Task-backed select options for more information.An expression that hides the param if it evaluates to a truthy value. The expression is evaluated as a JS template and can refer to other parameters by using the params
keyword.
Schedule configuration
- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
Name of the schedule.
Description of the schedule.
Map of param slug to value to pass to the task on each run.
Permissions configuration
Groups and users who can see task information, but can't request or execute tasks.
Groups and users who have all the permission of viewers, and can also request tasks.
Groups and users who have all the permissions of requesters, and can also execute tasks and other's requests.
Groups and users who have full access to the task, and can change task configurations and permissions.
Output display configuration
Code
Code is a syntax-highlighted code block.
Language to use for syntax highlighting.
Description list
Description list is a list of term and description pairs (aka key and value pairs).
Value of the display.
The value should be a JST that evaluates to the expected format of a description list, which is a list of objects with term
anddescription
fields. The JST can reference the output of the task.
File
File is a file preview. File requires the output to be an Airplane file.
JSON
JSON is a syntax-highlighted JSON block.
Statistic
Statistic is a simple display designed to prominently display quantifiable metrics so that users can easily discern key information at a glance.
Value of the display.
The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.
Label of the display.
The label can be a JST that can reference the output of the task.
Sublabel of the display.
The sublabel can be a JST that can reference the output of the task.
Table
Table is a rich, interactive table.
Value of the display.
The value should be a JST that evaluates to the expected format of a table, which is a list of objects with fields corresponding to the columns. The JST can reference the output of the task. If not set, the value will be the output of the task.
Columns of the table.
airplane.Column
is a class with label
and accessor
as arguments.
label
is what's displayed as the column header. accessor
indicates which field of the table value should be used for this column. If not set, the columns will be inferred from the output of the task.
Text
Text is component that displays plain text. Text also supports Markdown formatting.
Value of the display.
The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.
Docstrings
pythonCopied1import airplane23@airplane.task()4def my_task(name: str):5"""Says hello to you!67Args:8name: Your first and last name.9"""10print(f"Hello {name}!")
YAML reference (deprecated)
airplane tasks init --from=my_slug
and then copy/paste the code body into the newly created
_airplane.py
file.Standard fields
- Be fewer than 50 characters long
- Use only lowercase letters, numbers, and underscores
- Start with a lowercase letter
yamlCopied1parameters:2- slug: name3name: Name4type: shorttext5description: The user's name.6default: Alfred Pennyworth7required: false8options:9- Alfred Pennyworth10- Bruce Wayne11regex: "^[a-zA-Z ]+$"
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 |
label
and value
.yamlCopied1options:2- Alfred Pennyworth3- Bruce Wayne4- label: BW5value: Bruce Wayne
43200
(12 hours)yamlCopied1constraints:2aws-region: us-west-2
yamlCopied1schedules:2my_first_schedule:3cron: 0 0 * * *4name: My First Schedule5description: This is my first daily midnight UTC schedule!6paramValues:7my_first_param: my_first_param_value
yamlCopied1resources:2db: prod_postgres_db
yamlCopied1resources:2- prod_postgres_db3- prod_rest_api
yamlCopied1permissions: "team_access"
yamlCopied1permissions:2viewers:3groups:4- customer_success5users:6- success@airplane.dev7requesters:8groups:9- support10users:11- support@airplane.dev12executers:13groups:14- devs15admins:16groups:17- team_admins
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. |
Python
yamlCopied1python:2entrypoint: my_task.py
.py
file containing the logic for this task. This
can be absolute or relative to the location of the definition file.yamlCopied1entrypoint: my_folder/my_task.py
yamlCopied1envVars:2# From value3API_ENDPOINT:4value: api.myco.dev/5# From config variable6MY_SECRET:7config: MY_SECRET_CONFIG_VAR