Skip to content

checkmate

FastAPI endpoint functions for managing multi-stage sequential tasks.

Attributes

RESOURCE_CHECKMATE module-attribute 

RESOURCE_CHECKMATE = 'CheckMate'

checkmate_router module-attribute 

checkmate_router = APIRouter(
    prefix=format_path(RESOURCE_CHECKMATE),
    tags=[RESOURCE_CHECKMATE],
    responses=DEFAULT_HTTP_ERROR_RESPONSES,
)

since_query_param module-attribute 

since_query_param = Query(
    default=None,
    title="Since",
    description="Filter results where RDBMS update timestamp is greater than or equal to the provided ISO8601 timestamp. Note that max_results is still applied after filtering.",
    examples=["2024-11-04T00:00:00Z", "2024-11-04"],
)

Classes

Functions

cancel_tasks async 

cancel_tasks(
    fastapi_request: Request,
    request: CancelTaskRequestV1 = CancelTaskRequestV1(),
    since: datetime | None = Depends(_get_since),
    queue: str | None = _queue_query_param,
    sort: Literal["asc", "desc"] = _sort_query_param,
    max_results: int | None = _max_results_query_param,
    dry_run: bool = _dry_run_query_param,
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Performs a cancel operation on a list of tasks based on either explicit task_ids or filtering criteria.

clean_tasks async 

clean_tasks(
    fastapi_request: Request,
    dry_run: bool = _dry_run_query_param,
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Clean task metadata.

This endpoint removes task object metadata from persistence storage when it meets the criteria.

get_task async 

get_task(
    fastapi_request: Request,
    task_id: str = Path(..., description=comment),
    include_metadata: bool = Query(
        default=True,
        title="Include Metadata",
        description="Include task metadata in results if it is available. Enabling this could significantly increase the payload size and latency since all persistence store metadata is returned for each task.",
    ),
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Get managed task details

invoke_task async 

invoke_task(
    fastapi_request: Request,
    task_id: str = Path(..., description=comment),
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Invoke / Execute an existing CheckMate task.

list_tasks async 

list_tasks(
    fastapi_request: Request,
    cleaned: bool | None = _cleaned_query_param,
    status: StageStatus | None = _status_query_param,
    since: datetime | None = since_query_param,
    queue: str | None = _queue_query_param,
    tags: List[str] | None = _tags_query_param,
    sort: Literal["asc", "desc"] = _sort_query_param,
    max_results: int | None = _max_results_query_param,
    include_metadata: bool = Query(
        default=False,
        title="Include Metadata",
        description="Include task metadata in results if it is available. Enabling this could significantly increase the payload size and latency since all persistence store metadata is returned for each task.",
    ),
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Retrieves a list of managed tasks from the RDBMS and possibly the persistence store based on the provided filters.

task_status async 

task_status(
    fastapi_request: Request,
    task_id: str = Path(..., description=comment),
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
) -> JSONResponse

Check the status of an existing CheckMate task.

The intended use case for this endpoint is for external task orchestrations systems to monitor that status of a long-running task execution. To this end, task status is reflected in HTTP response code so client’s don’t need to parse JSON.

Responses

201: The task completed successfully. 202: The task is likely running. 500: Task execution failed.

unlock_tasks async 

unlock_tasks(
    fastapi_request: Request,
    request: UnlockTaskRequestV1 = UnlockTaskRequestV1(),
    status: StageStatus | None = _status_query_param,
    since: datetime | None = Depends(_get_since),
    sort: Literal["asc", "desc"] = _sort_query_param,
    max_results: int | None = _max_results_query_param,
    queue: str | None = _queue_query_param,
    dry_run: bool = _dry_run_query_param,
    job_pool: ThreadPoolExecutor = Depends(
        job_pool_dependency
    ),
)

Performs a unlock operation on a list of tasks based on either explicit task_ids or filtering criteria.