Skip to content

Tasks manifest

Build and check manifest

fractal-task-tools includes a set of task models to be used in the task_list.py module. An example may look like 

from fractal_task_tools.task_models import ConverterCompoundTask


AUTHORS = "Name1 Surname1, Name2 Surname2"
DOCS_LINK = "https://example.org"
TASK_LIST = [
    ConverterCompoundTask(
        name="Convert Cellvoyager to OME-Zarr",
        executable_init="tasks/cellvoyager_to_ome_zarr_init.py",
        executable="tasks/cellvoyager_to_ome_zarr_compute.py",
        meta_init={"cpus_per_task": 1, "mem": 4000},
        meta={"cpus_per_task": 1, "mem": 4000},
        category="Conversion",
        modality="HCS",
        tags=["Yokogawa", "Cellvoyager", "2D", "3D"],
        docs_info="file:task_info/convert_cellvoyager_to_ome_zarr.md",
    ),
]

Where:

  1. More details about the different Fractal task types are available at the task-types page.
  2. The AUTHORS variable is optional. If unset, fractal-task-tools looks at the pyproject.toml in the current directory (if any) and tries to parse authors' names from it. If also the second approach fails, no authors will be set in the manifest.
  3. The DOCS_LINK variable is optional

Once the task_list.py module is defined, fractal-task-tools also includes a command-line interface for creating and checking a manifest file.

The create command can be used as in 

fractal-manifest create --package my-task-package
and it writes the manifest to a file called __FRACTAL_MANIFEST__.json, in the root folder where the package my-task-package is installed.

The check command can be used as in 

fractal-manifest check --package my-task-package
and it verifies that the on-disk manifest is up-to-date, which is useful e.g. as a continuous-integration step:

JSON Schemas

Each task listed in the manifest is associated to a JSON Schema that represents its arguments (or two schemas, if the task has both a non-parallel and a parallel unit). These schemas are stored in the args_schema_non_parallel and args_schema_parallel properties of each task.

This kind of schemas are not used at task runtime (where the validity of task arguments is typically enforced by the @pydantic.validate_call decorator), but they form the basis for constructing the fractal-web user interface that lets a user edit task arguments.

The args_schema_version property, which is set at the manifest level, determines a set of constraints on the task-arguments schemas. What is described below applies to the current one as of fractal-task-tools=0.5.0, named args_schema_version = "fractal_schema_v1".

NOTE: This version has relevant breaking changes with respect to the previous version (args_schema_version = "pydantic_v2"), which was supported until fractal-task-tools=0.4.*.

Restrictions on JSON Schemas

A set of patterns are forbidden in Fractal task, to simplify the generation of task-arguments user interface in fractal-web.

The list of forbidden values is as follows (note: this is currently evolving, and the ground truth is in the _specs.py module):

  • E01: Property names cannot be in the forbidden ones.
  • E02: The definitions keyword is not supported, in favor of $defs.
  • E03: enum with non-homogeneous possible values (e.g. an integer and a string) are not supported.
  • E04: Underdefined schemas like the ones generated by the typing.Any Python type hint are not supported.
  • E05: Boolean properties without a default are not supported.
  • E06: Key-value objects with boolean values are not supported.
  • E07: Empty strings are not supported in default values of string, array, or object properties.
  • E08: Boolean items of a Python tuple are not supported.
  • E10: Nullable booleans are not supported.
  • E11: Nullable enums are not supported.
  • E12: Nullable enums represented as $ref are not supported.
  • E13: anyOf of non-null primitive types are not supported.
  • E14: anyOf with more than one $ref item is not supported.
  • E15: anyOf with more than two items is not supported.
  • E20: oneOf for the items of an array is not supported unless discriminator is present.
  • E21: oneOf with no discriminator is not supported.
  • E22: oneOf items which are not $refs are not supported.

A set of valid examples is available at https://github.com/fractal-analytics-platform/example-fractal-task-arguments.

NOTE: All the restrictions above are evaluated based on the JSON Schema for the task arguments, independently on the corresponding Python-function call signature. If the conversion from Python type hints to a JSON Schema is not fully precise, this may lead to edge cases which are not fully supported. One such example is the usage of argument: dict[int, int] in Python, where the JSON schema would not express the integer type of the keys. In this case, the user may set argument = {"non-integer": 1} in the JSON-Schema-based task-arguments user interface, even though this would be invalid for the Python function.