dlt._workspace.deployment.decorators

JobFactory Objects

class JobFactory(Generic[TJobFunParams, TJobResult])

View source on GitHub

Callable wrapper for a decorated job function.

Stores job metadata and provides config injection, async support, and trigger properties for job chaining. Preserves the decorated function's parameter types and return type via ParamSpec/TypeVar.

completed

@property
def completed() -> tuple[TTrigger, TTrigger]

View source on GitHub

Tuple of (success, fail) triggers — fires on any outcome.

is_matching_interval_fresh

@property
def is_matching_interval_fresh() -> TFreshnessConstraint

View source on GitHub

Downstream interval must be fully covered by this job's completed intervals.

is_fresh

@property
def is_fresh() -> TFreshnessConstraint

View source on GitHub

This job's overall interval (intersected with downstream's) must be complete.

bind

def bind(f: AnyFun) -> "JobFactory[TJobFunParams, TJobResult]"

View source on GitHub

Binds wrapper to the original function. Called once by the decorator.

to_job_definition

def to_job_definition() -> TJobDefinition

View source on GitHub

Builds a TJobDefinition manifest dict from this wrapper's metadata.

job

def job(func: Optional[AnyFun] = None,
        name: str = None,
        section: str = None,
        trigger: Union[str, TTrigger, Sequence[Union[str, TTrigger]]] = None,
        execute: Optional[TExecuteSpec] = None,
        expose: Optional[TJobExposeSpec] = None,
        require: Optional[TRequireSpec] = None,
        deliver: Optional[TDeliverTarget] = None,
        interval: Optional[TIntervalSpec] = None,
        freshness: Union[None, str, TFreshnessConstraint,
                         Sequence[Union[str, TFreshnessConstraint]]] = None,
        allow_external_schedulers: bool = False,
        refresh: TRefreshPolicy = "auto",
        spec: Type[BaseConfiguration] = None) -> Any

View source on GitHub

Marks a function as a deployable batch job.

Arguments:

• func - The function to decorate.

• name - Job name. Defaults to the function name.

• section - Config section. Defaults to the module name.

• trigger - One or more trigger strings or TTrigger values.

• execute - Execution constraints. Accepts TExecuteSpec with: timeout (seconds, human string like "4h", or TTimeoutSpec dict), concurrency (max concurrent runs, defaults to 1; pass None to remove the limit).

• expose - UI presentation. Accepts TJobExposeSpec with: tags (grouping labels), starred (top-level UI visibility), manual (False to disable manual triggering).

• require - Runtime resource requirements. Accepts TRequireSpec with: dependency_groups, profile (workspace profile), machine (machine spec), region (runner placement).

• deliver - A @dlt.source, standalone @dlt.resource, or called source instance for delivery association.

• interval - Overall time range for interval-based scheduling.

• freshness - Upstream freshness constraints. Accepts a single constraint string, TFreshnessConstraint, or a list of them.

• allow_external_schedulers - When True, intervals and state are managed by the scheduler rather than the job itself.

• refresh - Refresh-signal propagation policy. auto (default) passes through if this run had refresh=True. always always clears direct downstream prev_completed_run on success. block never propagates. Ignored for interval-store jobs.

• spec - Optional configuration spec class.

Returns:

• JobFactory - Preserves the original function's signature and return type.

interactive

def interactive(func: Optional[AnyFun] = None,
                name: str = None,
                section: str = None,
                interface: TInterfaceType = "gui",
                idle_timeout: Union[None, float, str] = None,
                execute: Optional[TExecuteSpec] = None,
                expose: Optional[TJobExposeSpec] = None,
                require: Optional[TRequireSpec] = None,
                spec: Type[BaseConfiguration] = None) -> Any

View source on GitHub

Marks a function as a deployable interactive job.

Interactive jobs are long-running processes that expose an HTTP endpoint. The runtime assigns a port and proxies traffic to the job.

Arguments:

• func - The function to decorate.
• name - Job name. Defaults to the function name.
• section - Config section. Defaults to the module name.
• interface - What the job exposes: "gui", "rest_api", or "mcp".
• idle_timeout - Idle timeout as seconds or human string (e.g. "24h").
• execute - Execution constraints. Accepts TExecuteSpec with: timeout and concurrency. Concurrency defaults to 1 for interactive jobs.
• expose - UI presentation. Accepts TJobExposeSpec with: tags, starred, manual. The interface argument is merged into expose automatically.
• require - Runtime resource requirements. Accepts TRequireSpec with: dependency_groups, profile, machine, region.
• spec - Optional configuration spec class.

Returns:

• JobFactory - Preserves the original function's signature and return type.

pipeline_run

def pipeline_run(
    pipeline: Union[str, SupportsPipeline],
    name: str = None,
    section: str = None,
    trigger: Union[str, TTrigger, Sequence[Union[str, TTrigger]]] = None,
    execute: Optional[TExecuteSpec] = None,
    expose: Optional[TJobExposeSpec] = None,
    require: Optional[TRequireSpec] = None,
    interval: Optional[TIntervalSpec] = None,
    freshness: Union[None, str, TFreshnessConstraint,
                     Sequence[Union[str, TFreshnessConstraint]]] = None,
    allow_external_schedulers: bool = False,
    refresh: TRefreshPolicy = "auto",
    spec: Type[BaseConfiguration] = None
) -> Callable[[Callable[TJobFunParams, TJobResult]], JobFactory[TJobFunParams,
                                                                TJobResult]]

View source on GitHub

Creates a job bound to a specific pipeline.

The decorated function runs as a batch job that operates on the named pipeline. The pipeline association is stored in the manifest's deliver spec, and the job is categorized as "pipeline" in the UI.

Arguments:

• pipeline - Pipeline name (str) or SupportsPipeline instance.

• name - Pipeline run name. Defaults to the function name.

• section - Config section for pipeline run. Defaults to the module name.

• trigger - One or more trigger strings or TTrigger values.

• execute - Execution constraints (TExecuteSpec): timeout, concurrency.

• expose - UI presentation (TJobExposeSpec): tags, starred, manual.

• require - Resource requirements (TRequireSpec): dependency_groups, profile, machine, region.

• interval - Overall time range for interval-based scheduling.

• freshness - Upstream freshness constraints.

• allow_external_schedulers - When True, intervals managed by scheduler.

• refresh - Refresh-signal propagation policy. auto (default) passes through if this run had refresh=True. always always clears direct downstream prev_completed_run on success. block never propagates. Ignored for interval-store jobs.

• spec - Optional configuration spec class.

Returns:

A decorator that wraps the function in a JobFactory.