task-inputs.mdx

title	Python task inputs
sidebarTitle	Task inputs
description	Supported Python types for Tilebox workflow task inputs, including geospatial and raster types.
icon	list-check

Python tasks are data classes. Annotate each task field with one of the supported types below, and Tilebox reconstructs that type before the task runs.

This page applies to tasks executed by Python runners. For tasks submitted and executed across different languages, use an input schema supported by both SDKs. See Multi-language workflows.

The examples focus on task input declarations and omit the execute method.

Python standard library

These types require no extra packages:

• Values: str, int, float, bool, bytes, and bytearray
• Collections: list, tuple, dict, set, and frozenset
• Type annotations: Optional, Union, and Literal
• Structured values: data classes and Enum
• Dates and times: datetime, date, time, timedelta, and ZoneInfo
• Other values: UUID, Decimal, and PurePath subclasses such as Path

Example usage

from datetime import datetime
from pathlib import Path
from uuid import UUID

from tilebox.workflows import Task

class BuildSentinel2Mosaic(Task):
    scene_ids: list[UUID]
    bands: tuple[str, ...]
    acquired_after: datetime
    output_path: Path

Protocol buffers

protobuf provides generated message classes for strongly typed schemas and is installed with tilebox-workflows.

Tilebox supports Message and its generated subclasses.

Example usage

from google.protobuf.timestamp_pb2 import Timestamp
from tilebox.workflows import Task

class ProcessSceneAcquisition(Task):
    scene_id: str
    acquired_at: Timestamp

Tilebox Datasets

tilebox-datasets provides value types for dataset and job queries and is installed with tilebox-workflows.

Type	Use in a workflow
TimeInterval, IDInterval	Pass dataset or job query ranges to a task
SpatialFilter	Pass a dataset spatial query to a task; its geometry requires Shapely

Example usage

from tilebox.datasets.data.data_access import SpatialFilter
from tilebox.datasets.query import TimeInterval
from tilebox.workflows import Task

class QuerySentinel2Scenes(Task):
    collections: list[str]
    temporal_extent: TimeInterval
    spatial_extent: SpatialFilter

Shapely

shapely provides geometry types for vector features, footprints, and areas of interest.

• Single geometries: Geometry, Point, LineString, LinearRing, and Polygon
• Geometry collections: MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection

Example usage

from shapely import MultiPolygon
from tilebox.workflows import Task

class ComputeSentinel2CloudStatistics(Task):
    area_of_interest: MultiPolygon
    preceding_hours: int

Coordinate systems and raster transforms

affine provides two-dimensional affine transformation matrices. pyproj provides coordinate reference systems and coordinate transformations.

Type	Use in a workflow
Affine	Preserve the pixel-to-world transform for raster processing
pyproj.CRS	Pass a coordinate reference system without reducing it to a string

Example usage

from affine import Affine
from pyproj import CRS
from tilebox.workflows import Task

class ReprojectRasterTile(Task):
    source_crs: CRS
    target_crs: CRS
    source_transform: Affine

ODC Geo

odc-geo provides projection-aware geometry and raster grid types.

Type	Use in a workflow
CRS	Preserve an ODC coordinate reference system
Geometry, BoundingBox	Pass projection-aware geometries and bounds
XY, Resolution	Describe grid coordinates and spatial resolution
Index2d, Shape2d	Describe a grid index or shape
GeoBox	Preserve an aligned, georeferenced raster grid
GeoboxTiles, AnchorEnum	Partition and align a GeoBox for tiled processing

Example usage

from odc.geo import GeoBox
from tilebox.workflows import Task

class ReprojectSentinel2Product(Task):
    product_location: str
    source_grid: GeoBox
    target_grid: GeoBox

Raster windows

rasterio provides raster data access and processing. async-geotiff provides asynchronous GeoTIFF and Cloud Optimized GeoTIFF reads. Install either package separately when your workflow uses its window type.

Type	Use in a workflow
rasterio.windows.Window	Pass a rectangular pixel region to a task that uses rasterio
async_geotiff.Window	Pass a rectangular pixel region to an async GeoTIFF task

Example usage

from rasterio.windows import Window
from tilebox.workflows import Task

class ComputeHyperspectralChunkStatistics(Task):
    product_path: str
    window: Window
    output_key: str

Keep task inputs compact

Task inputs are part of the workflow graph and are not intended for large arrays, file contents, pandas DataFrames, clients, or open files. Store large data in object storage or the job cache, then pass a compact reference such as an ID, object prefix, cache key, time interval, geometry, or raster window.