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:pythonCopied1# my_task_airplane.py2import airplane34@airplane.task()5def my_task():6"""This is my task defined entirely in Python!"""7print("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
.pythonCopied1import airplane23@airplane.task()4def my_first_task():5pass67@airplane.task()8def my_second_task():9pass
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.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
Task parameters are inferred from the parameters of the decorated Python
function.
pythonCopied1import airplane23@airplane.task()4def my_task(5# Task accepts a `name` argument6name: str,7):8print(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 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 |
Optional parameters
Task parameters can be marked as optional via
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
Default parameter values can be specified via the Python default argument syntax.
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
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
pythonCopied1import airplane23@airplane.task(4resouces=[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
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
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
- 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
A user-facing name for the task. This can be changed.
description
optional
A user-facing description for the task. Supports markdown.
require_requests
optional
default: False
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
allow_self_approvals
optional
default: True
If true, a request can be approved by the requestor.
restrict_callers
optional
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)
constraints
optional
schedules
optional
resources
optional
AIRPLANE_RESOURCES
environment variable. For more information, see resource attachments.env_vars
optional
default_run_permissions
optional
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: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}!")
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
- 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
A human-readable name that identifies this parameter.
description
optional
A description that renders underneath the parameter.
regex
optional
shorttext
and longtext
parameters.options
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
- Be fewer than 50 characters long.
- Use only lowercase letters, numbers and underscores.
- Start with a lowercase later.
cron
REQUIRED
name
optional
default: schedule slug
Name of the schedule.
description
optional
Description of the schedule.
param_values
optional
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.
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)
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.
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
User-facing name for the task. This can be changed.
description
string
User-facing description for the task. This can be changed.
parameters
list
A list of parameters. Each parameter is a user-facing field to input data into the task.
Example:
yamlCopied1parameters:2- slug: name3name: Name4type: shorttext5description: The user's name.6default: Alfred Pennyworth7required: false8options:9- Alfred Pennyworth10- Bruce Wayne11regex: "^[a-zA-Z ]+$"
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.
User-facing name for the parameter.
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.
parameters.description
string
User-facing description of the parameter.
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:
yamlCopied1options:2- Alfred Pennyworth3- Bruce Wayne4- label: BW5value: Bruce Wayne
For more information, see Select options.
parameters.regex
string
Allows you to more dynamically control what values are permitted.
For more information, see Regular expressions.
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.
If true, a request can be approved by the requestor.
Limits how long a task can run before it is automatically cancelled.
Maximum of
43200
(12 hours)For more information, see timeouts.
constraints
object
Restricts this task to run only on agents with matching labels.
Example:
yamlCopied1constraints:2aws-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:
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
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.
Cron string of the schedule. To see acceptable formats, see
Cron syntax.
schedules.name
string
Name of the schedule.
schedules.description
string
Description of the schedule.
schedules.paramValues
object
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:
yamlCopied1resources:2db: 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:
yamlCopied1resources:2- prod_postgres_db3- prod_rest_api
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:
yamlCopied1python:2entrypoint: my_task.py
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:
yamlCopied1entrypoint: my_folder/my_task.py
python.envVars
object
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:
yamlCopied1envVars:2# From value3API_ENDPOINT:4value: api.myco.dev/5# From config variable6MY_SECRET:7config: MY_SECRET_CONFIG_VAR