Skip to content

prefect.tasks

Module containing the base workflow task class and decorator - for most use cases, using the @task decorator is preferred.

Task

Bases: Generic[P, R]

A Prefect task definition.

Note

We recommend using the @task decorator for most use-cases.

Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function creates a new task run.

To preserve the input and output types, we use the generic type variables P and R for "Parameters" and "Returns" respectively.

Parameters:

Name Type Description Default
fn Callable[P, R]

The function defining the task.

required
name str

An optional name for the task; if not provided, the name will be inferred from the given function.

None
description str

An optional string description for the task.

None
tags Iterable[str]

An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a prefect.tags context at task runtime.

None
version str

An optional string specifying the version of this task definition

None
cache_key_fn Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]

An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.

None
cache_expiration timedelta

An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.

None
task_run_name Optional[Union[Callable[[], str], str]]

An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.

None
retries Optional[int]

An optional number of times to retry on task run failure.

None
retry_delay_seconds Optional[Union[float, int, List[float], Callable[[int], List[float]]]]

Optionally configures how long to wait before retrying the task after failure. This is only applicable if retries is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.

None
retry_jitter_factor Optional[float]

An optional factor that defines the factor to which a retry can be jittered in order to avoid a "thundering herd".

None
persist_result Optional[bool]

An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to None, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.

None
result_storage Optional[ResultStorage]

An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.

None
result_storage_key Optional[str]

An optional key to store the result in storage at when persisted. Defaults to a unique identifier.

None
result_serializer Optional[ResultSerializer]

An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.

None
timeout_seconds Union[int, float]

An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.

None
log_prints Optional[bool]

If set, print statements in the task will be redirected to the Prefect logger for the task run. Defaults to None, which indicates that the value from the flow should be used.

False
refresh_cache Optional[bool]

If set, cached results for the cache key are not used. Defaults to None, which indicates that a cached result from a previous execution with matching cache key is used.

None
on_failure Optional[List[Callable[[Task, TaskRun, State], None]]]

An optional list of callables to run when the task enters a failed state.

None
on_completion Optional[List[Callable[[Task, TaskRun, State], None]]]

An optional list of callables to run when the task enters a completed state.

None
viz_return_value Optional[Any]

An optional value to return when the task dependency tree is visualized.

None
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
@PrefectObjectRegistry.register_instances
class Task(Generic[P, R]):
    """
    A Prefect task definition.

    !!! note
        We recommend using [the `@task` decorator][prefect.tasks.task] for most use-cases.

    Wraps a function with an entrypoint to the Prefect engine. Calling this class within a flow function
    creates a new task run.

    To preserve the input and output types, we use the generic type variables P and R for "Parameters" and
    "Returns" respectively.

    Args:
        fn: The function defining the task.
        name: An optional name for the task; if not provided, the name will be inferred
            from the given function.
        description: An optional string description for the task.
        tags: An optional set of tags to be associated with runs of this task. These
            tags are combined with any tags defined by a `prefect.tags` context at
            task runtime.
        version: An optional string specifying the version of this task definition
        cache_key_fn: An optional callable that, given the task run context and call
            parameters, generates a string key; if the key matches a previous completed
            state, that state result will be restored instead of running the task again.
        cache_expiration: An optional amount of time indicating how long cached states
            for this task should be restorable; if not provided, cached states will
            never expire.
        task_run_name: An optional name to distinguish runs of this task; this name can be provided
            as a string template with the task's keyword arguments as variables,
            or a function that returns a string.
        retries: An optional number of times to retry on task run failure.
        retry_delay_seconds: Optionally configures how long to wait before retrying the
            task after failure. This is only applicable if `retries` is nonzero. This
            setting can either be a number of seconds, a list of retry delays, or a
            callable that, given the total number of retries, generates a list of retry
            delays. If a number of seconds, that delay will be applied to all retries.
            If a list, each retry will wait for the corresponding delay before retrying.
            When passing a callable or a list, the number of configured retry delays
            cannot exceed 50.
        retry_jitter_factor: An optional factor that defines the factor to which a retry
            can be jittered in order to avoid a "thundering herd".
        persist_result: An optional toggle indicating whether the result of this task
            should be persisted to result storage. Defaults to `None`, which indicates
            that Prefect should choose whether the result should be persisted depending on
            the features being used.
        result_storage: An optional block to use to persist the result of this task.
            Defaults to the value set in the flow the task is called in.
        result_storage_key: An optional key to store the result in storage at when persisted.
            Defaults to a unique identifier.
        result_serializer: An optional serializer to use to serialize the result of this
            task for persistence. Defaults to the value set in the flow the task is
            called in.
        timeout_seconds: An optional number of seconds indicating a maximum runtime for
            the task. If the task exceeds this runtime, it will be marked as failed.
        log_prints: If set, `print` statements in the task will be redirected to the
            Prefect logger for the task run. Defaults to `None`, which indicates
            that the value from the flow should be used.
        refresh_cache: If set, cached results for the cache key are not used.
            Defaults to `None`, which indicates that a cached result from a previous
            execution with matching cache key is used.
        on_failure: An optional list of callables to run when the task enters a failed state.
        on_completion: An optional list of callables to run when the task enters a completed state.
        viz_return_value: An optional value to return when the task dependency tree is visualized.
    """

    # NOTE: These parameters (types, defaults, and docstrings) should be duplicated
    #       exactly in the @task decorator
    def __init__(
        self,
        fn: Callable[P, R],
        name: str = None,
        description: str = None,
        tags: Iterable[str] = None,
        version: str = None,
        cache_key_fn: Callable[
            ["TaskRunContext", Dict[str, Any]], Optional[str]
        ] = None,
        cache_expiration: datetime.timedelta = None,
        task_run_name: Optional[Union[Callable[[], str], str]] = None,
        retries: Optional[int] = None,
        retry_delay_seconds: Optional[
            Union[
                float,
                int,
                List[float],
                Callable[[int], List[float]],
            ]
        ] = None,
        retry_jitter_factor: Optional[float] = None,
        persist_result: Optional[bool] = None,
        result_storage: Optional[ResultStorage] = None,
        result_serializer: Optional[ResultSerializer] = None,
        result_storage_key: Optional[str] = None,
        cache_result_in_memory: bool = True,
        timeout_seconds: Union[int, float] = None,
        log_prints: Optional[bool] = False,
        refresh_cache: Optional[bool] = None,
        on_completion: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
        on_failure: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
        viz_return_value: Optional[Any] = None,
    ):
        # Validate if hook passed is list and contains callables
        hook_categories = [on_completion, on_failure]
        hook_names = ["on_completion", "on_failure"]
        for hooks, hook_name in zip(hook_categories, hook_names):
            if hooks is not None:
                if not hooks:
                    raise ValueError(f"Empty list passed for '{hook_name}'")
                try:
                    hooks = list(hooks)
                except TypeError:
                    raise TypeError(
                        f"Expected iterable for '{hook_name}'; got"
                        f" {type(hooks).__name__} instead. Please provide a list of"
                        f" hooks to '{hook_name}':\n\n"
                        f"@flow({hook_name}=[hook1, hook2])\ndef"
                        " my_flow():\n\tpass"
                    )

                for hook in hooks:
                    if not callable(hook):
                        raise TypeError(
                            f"Expected callables in '{hook_name}'; got"
                            f" {type(hook).__name__} instead. Please provide a list of"
                            f" hooks to '{hook_name}':\n\n"
                            f"@flow({hook_name}=[hook1, hook2])\ndef"
                            " my_flow():\n\tpass"
                        )

        if not callable(fn):
            raise TypeError("'fn' must be callable")

        self.description = description or inspect.getdoc(fn)
        update_wrapper(self, fn)
        self.fn = fn
        self.isasync = inspect.iscoroutinefunction(self.fn)

        if not name:
            if not hasattr(self.fn, "__name__"):
                self.name = type(self.fn).__name__
            else:
                self.name = self.fn.__name__
        else:
            self.name = name

        if task_run_name is not None:
            if not isinstance(task_run_name, str) and not callable(task_run_name):
                raise TypeError(
                    "Expected string or callable for 'task_run_name'; got"
                    f" {type(task_run_name).__name__} instead."
                )
        self.task_run_name = task_run_name

        self.version = version
        self.log_prints = log_prints

        raise_for_reserved_arguments(self.fn, ["return_state", "wait_for"])

        self.tags = set(tags if tags else [])

        if not hasattr(self.fn, "__qualname__"):
            self.task_key = to_qualified_name(type(self.fn))
        else:
            self.task_key = to_qualified_name(self.fn)

        self.cache_key_fn = cache_key_fn
        self.cache_expiration = cache_expiration
        self.refresh_cache = refresh_cache

        # TaskRunPolicy settings
        # TODO: We can instantiate a `TaskRunPolicy` and add Pydantic bound checks to
        #       validate that the user passes positive numbers here

        self.retries = (
            retries if retries is not None else PREFECT_TASK_DEFAULT_RETRIES.value()
        )
        if retry_delay_seconds is None:
            retry_delay_seconds = PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS.value()

        if callable(retry_delay_seconds):
            self.retry_delay_seconds = retry_delay_seconds(retries)
        else:
            self.retry_delay_seconds = retry_delay_seconds

        if isinstance(self.retry_delay_seconds, list) and (
            len(self.retry_delay_seconds) > 50
        ):
            raise ValueError("Can not configure more than 50 retry delays per task.")

        if retry_jitter_factor is not None and retry_jitter_factor < 0:
            raise ValueError("`retry_jitter_factor` must be >= 0.")

        self.retry_jitter_factor = retry_jitter_factor

        self.persist_result = persist_result
        self.result_storage = result_storage
        self.result_serializer = result_serializer
        self.result_storage_key = result_storage_key
        self.cache_result_in_memory = cache_result_in_memory
        self.timeout_seconds = float(timeout_seconds) if timeout_seconds else None
        # Warn if this task's `name` conflicts with another task while having a
        # different function. This is to detect the case where two or more tasks
        # share a name or are lambdas, which should result in a warning, and to
        # differentiate it from the case where the task was 'copied' via
        # `with_options`, which should not result in a warning.
        registry = PrefectObjectRegistry.get()

        if registry and any(
            other
            for other in registry.get_instances(Task)
            if other.name == self.name and id(other.fn) != id(self.fn)
        ):
            try:
                file = inspect.getsourcefile(self.fn)
                line_number = inspect.getsourcelines(self.fn)[1]
            except TypeError:
                file = "unknown"
                line_number = "unknown"

            warnings.warn(
                f"A task named {self.name!r} and defined at '{file}:{line_number}' "
                "conflicts with another task. Consider specifying a unique `name` "
                "parameter in the task definition:\n\n "
                "`@task(name='my_unique_name', ...)`"
            )
        self.on_completion = on_completion
        self.on_failure = on_failure
        self.viz_return_value = viz_return_value

    def with_options(
        self,
        *,
        name: str = None,
        description: str = None,
        tags: Iterable[str] = None,
        cache_key_fn: Callable[
            ["TaskRunContext", Dict[str, Any]], Optional[str]
        ] = None,
        task_run_name: Optional[Union[Callable[[], str], str]] = None,
        cache_expiration: datetime.timedelta = None,
        retries: Optional[int] = NotSet,
        retry_delay_seconds: Union[
            float,
            int,
            List[float],
            Callable[[int], List[float]],
        ] = NotSet,
        retry_jitter_factor: Optional[float] = NotSet,
        persist_result: Optional[bool] = NotSet,
        result_storage: Optional[ResultStorage] = NotSet,
        result_serializer: Optional[ResultSerializer] = NotSet,
        result_storage_key: Optional[str] = NotSet,
        cache_result_in_memory: Optional[bool] = None,
        timeout_seconds: Union[int, float] = None,
        log_prints: Optional[bool] = NotSet,
        refresh_cache: Optional[bool] = NotSet,
        on_completion: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
        on_failure: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
        viz_return_value: Optional[Any] = None,
    ):
        """
        Create a new task from the current object, updating provided options.

        Args:
            name: A new name for the task.
            description: A new description for the task.
            tags: A new set of tags for the task. If given, existing tags are ignored,
                not merged.
            cache_key_fn: A new cache key function for the task.
            cache_expiration: A new cache expiration time for the task.
            task_run_name: An optional name to distinguish runs of this task; this name can be provided
                as a string template with the task's keyword arguments as variables,
                or a function that returns a string.
            retries: A new number of times to retry on task run failure.
            retry_delay_seconds: Optionally configures how long to wait before retrying
                the task after failure. This is only applicable if `retries` is nonzero.
                This setting can either be a number of seconds, a list of retry delays,
                or a callable that, given the total number of retries, generates a list
                of retry delays. If a number of seconds, that delay will be applied to
                all retries. If a list, each retry will wait for the corresponding delay
                before retrying. When passing a callable or a list, the number of
                configured retry delays cannot exceed 50.
            retry_jitter_factor: An optional factor that defines the factor to which a
                retry can be jittered in order to avoid a "thundering herd".
            persist_result: A new option for enabling or disabling result persistence.
            result_storage: A new storage type to use for results.
            result_serializer: A new serializer to use for results.
            result_storage_key: A new key for the persisted result to be stored at.
            timeout_seconds: A new maximum time for the task to complete in seconds.
            log_prints: A new option for enabling or disabling redirection of `print` statements.
            refresh_cache: A new option for enabling or disabling cache refresh.
            on_completion: A new list of callables to run when the task enters a completed state.
            on_failure: A new list of callables to run when the task enters a failed state.
            viz_return_value: An optional value to return when the task dependency tree is visualized.

        Returns:
            A new `Task` instance.

        Examples:

            Create a new task from an existing task and update the name

            >>> @task(name="My task")
            >>> def my_task():
            >>>     return 1
            >>>
            >>> new_task = my_task.with_options(name="My new task")

            Create a new task from an existing task and update the retry settings

            >>> from random import randint
            >>>
            >>> @task(retries=1, retry_delay_seconds=5)
            >>> def my_task():
            >>>     x = randint(0, 5)
            >>>     if x >= 3:  # Make a task that fails sometimes
            >>>         raise ValueError("Retry me please!")
            >>>     return x
            >>>
            >>> new_task = my_task.with_options(retries=5, retry_delay_seconds=2)

            Use a task with updated options within a flow

            >>> @task(name="My task")
            >>> def my_task():
            >>>     return 1
            >>>
            >>> @flow
            >>> my_flow():
            >>>     new_task = my_task.with_options(name="My new task")
            >>>     new_task()
        """
        return Task(
            fn=self.fn,
            name=name or self.name,
            description=description or self.description,
            tags=tags or copy(self.tags),
            cache_key_fn=cache_key_fn or self.cache_key_fn,
            cache_expiration=cache_expiration or self.cache_expiration,
            task_run_name=task_run_name,
            retries=retries if retries is not NotSet else self.retries,
            retry_delay_seconds=(
                retry_delay_seconds
                if retry_delay_seconds is not NotSet
                else self.retry_delay_seconds
            ),
            retry_jitter_factor=(
                retry_jitter_factor
                if retry_jitter_factor is not NotSet
                else self.retry_jitter_factor
            ),
            persist_result=(
                persist_result if persist_result is not NotSet else self.persist_result
            ),
            result_storage=(
                result_storage if result_storage is not NotSet else self.result_storage
            ),
            result_storage_key=(
                result_storage_key
                if result_storage_key is not NotSet
                else self.result_storage_key
            ),
            result_serializer=(
                result_serializer
                if result_serializer is not NotSet
                else self.result_serializer
            ),
            cache_result_in_memory=(
                cache_result_in_memory
                if cache_result_in_memory is not None
                else self.cache_result_in_memory
            ),
            timeout_seconds=(
                timeout_seconds if timeout_seconds is not None else self.timeout_seconds
            ),
            log_prints=(log_prints if log_prints is not NotSet else self.log_prints),
            refresh_cache=(
                refresh_cache if refresh_cache is not NotSet else self.refresh_cache
            ),
            on_completion=on_completion or self.on_completion,
            on_failure=on_failure or self.on_failure,
            viz_return_value=viz_return_value or self.viz_return_value,
        )

    @overload
    def __call__(
        self: "Task[P, NoReturn]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> None:
        # `NoReturn` matches if a type can't be inferred for the function which stops a
        # sync function from matching the `Coroutine` overload
        ...

    @overload
    def __call__(
        self: "Task[P, T]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> T:
        ...

    @overload
    def __call__(
        self: "Task[P, T]",
        *args: P.args,
        return_state: Literal[True],
        **kwargs: P.kwargs,
    ) -> State[T]:
        ...

    def __call__(
        self,
        *args: P.args,
        return_state: bool = False,
        wait_for: Optional[Iterable[PrefectFuture]] = None,
        **kwargs: P.kwargs,
    ):
        """
        Run the task and return the result. If `return_state` is True returns
        the result is wrapped in a Prefect State which provides error handling.
        """
        from prefect.engine import enter_task_run_engine
        from prefect.task_runners import SequentialTaskRunner

        # Convert the call args/kwargs to a parameter dict
        parameters = get_call_parameters(self.fn, args, kwargs)

        return_type = "state" if return_state else "result"

        task_run_tracker = get_task_viz_tracker()
        if task_run_tracker:
            return track_viz_task(
                self.isasync, self.name, parameters, self.viz_return_value
            )

        return enter_task_run_engine(
            self,
            parameters=parameters,
            wait_for=wait_for,
            task_runner=SequentialTaskRunner(),
            return_type=return_type,
            mapped=False,
        )

    @overload
    def _run(
        self: "Task[P, NoReturn]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> PrefectFuture[None, Sync]:
        # `NoReturn` matches if a type can't be inferred for the function which stops a
        # sync function from matching the `Coroutine` overload
        ...

    @overload
    def _run(
        self: "Task[P, Coroutine[Any, Any, T]]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> Awaitable[State[T]]:
        ...

    @overload
    def _run(
        self: "Task[P, T]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> State[T]:
        ...

    def _run(
        self,
        *args: P.args,
        wait_for: Optional[Iterable[PrefectFuture]] = None,
        **kwargs: P.kwargs,
    ) -> Union[State, Awaitable[State]]:
        """
        Run the task and return the final state.
        """
        from prefect.engine import enter_task_run_engine
        from prefect.task_runners import SequentialTaskRunner

        # Convert the call args/kwargs to a parameter dict
        parameters = get_call_parameters(self.fn, args, kwargs)

        return enter_task_run_engine(
            self,
            parameters=parameters,
            wait_for=wait_for,
            return_type="state",
            task_runner=SequentialTaskRunner(),
            mapped=False,
        )

    @overload
    def submit(
        self: "Task[P, NoReturn]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> PrefectFuture[None, Sync]:
        # `NoReturn` matches if a type can't be inferred for the function which stops a
        # sync function from matching the `Coroutine` overload
        ...

    @overload
    def submit(
        self: "Task[P, Coroutine[Any, Any, T]]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> Awaitable[PrefectFuture[T, Async]]:
        ...

    @overload
    def submit(
        self: "Task[P, T]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> PrefectFuture[T, Sync]:
        ...

    @overload
    def submit(
        self: "Task[P, T]",
        *args: P.args,
        return_state: Literal[True],
        **kwargs: P.kwargs,
    ) -> State[T]:
        ...

    def submit(
        self,
        *args: Any,
        return_state: bool = False,
        wait_for: Optional[Iterable[PrefectFuture]] = None,
        **kwargs: Any,
    ) -> Union[PrefectFuture, Awaitable[PrefectFuture]]:
        """
        Submit a run of the task to a worker.

        Must be called within a flow function. If writing an async task, this call must
        be awaited.

        Will create a new task run in the backing API and submit the task to the flow's
        task runner. This call only blocks execution while the task is being submitted,
        once it is submitted, the flow function will continue executing. However, note
        that the `SequentialTaskRunner` does not implement parallel execution for sync tasks
        and they are fully resolved on submission.

        Args:
            *args: Arguments to run the task with
            return_state: Return the result of the flow run wrapped in a
                Prefect State.
            wait_for: Upstream task futures to wait for before starting the task
            **kwargs: Keyword arguments to run the task with

        Returns:
            If `return_state` is False a future allowing asynchronous access to
                the state of the task
            If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to
                the state of the task

        Examples:

            Define a task

            >>> from prefect import task
            >>> @task
            >>> def my_task():
            >>>     return "hello"

            Run a task in a flow

            >>> from prefect import flow
            >>> @flow
            >>> def my_flow():
            >>>     my_task.submit()

            Wait for a task to finish

            >>> @flow
            >>> def my_flow():
            >>>     my_task.submit().wait()

            Use the result from a task in a flow

            >>> @flow
            >>> def my_flow():
            >>>     print(my_task.submit().result())
            >>>
            >>> my_flow()
            hello

            Run an async task in an async flow

            >>> @task
            >>> async def my_async_task():
            >>>     pass
            >>>
            >>> @flow
            >>> async def my_flow():
            >>>     await my_async_task.submit()

            Run a sync task in an async flow

            >>> @flow
            >>> async def my_flow():
            >>>     my_task.submit()

            Enforce ordering between tasks that do not exchange data
            >>> @task
            >>> def task_1():
            >>>     pass
            >>>
            >>> @task
            >>> def task_2():
            >>>     pass
            >>>
            >>> @flow
            >>> def my_flow():
            >>>     x = task_1.submit()
            >>>
            >>>     # task 2 will wait for task_1 to complete
            >>>     y = task_2.submit(wait_for=[x])

        """

        from prefect.engine import enter_task_run_engine

        # Convert the call args/kwargs to a parameter dict
        parameters = get_call_parameters(self.fn, args, kwargs)
        return_type = "state" if return_state else "future"

        task_viz_tracker = get_task_viz_tracker()
        if task_viz_tracker:
            raise VisualizationUnsupportedError(
                "`task.submit()` is not currently supported by `flow.visualize()`"
            )

        return enter_task_run_engine(
            self,
            parameters=parameters,
            wait_for=wait_for,
            return_type=return_type,
            task_runner=None,  # Use the flow's task runner
            mapped=False,
        )

    @overload
    def map(
        self: "Task[P, NoReturn]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> List[PrefectFuture[None, Sync]]:
        # `NoReturn` matches if a type can't be inferred for the function which stops a
        # sync function from matching the `Coroutine` overload
        ...

    @overload
    def map(
        self: "Task[P, Coroutine[Any, Any, T]]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> Awaitable[List[PrefectFuture[T, Async]]]:
        ...

    @overload
    def map(
        self: "Task[P, T]",
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> List[PrefectFuture[T, Sync]]:
        ...

    @overload
    def map(
        self: "Task[P, T]",
        *args: P.args,
        return_state: Literal[True],
        **kwargs: P.kwargs,
    ) -> List[State[T]]:
        ...

    def map(
        self,
        *args: Any,
        return_state: bool = False,
        wait_for: Optional[Iterable[PrefectFuture]] = None,
        **kwargs: Any,
    ) -> Any:
        """
        Submit a mapped run of the task to a worker.

        Must be called within a flow function. If writing an async task, this
        call must be awaited.

        Must be called with at least one iterable and all iterables must be
        the same length. Any arguments that are not iterable will be treated as
        a static value and each task run will receive the same value.

        Will create as many task runs as the length of the iterable(s) in the
        backing API and submit the task runs to the flow's task runner. This
        call blocks if given a future as input while the future is resolved. It
        also blocks while the tasks are being submitted, once they are
        submitted, the flow function will continue executing. However, note
        that the `SequentialTaskRunner` does not implement parallel execution
        for sync tasks and they are fully resolved on submission.

        Args:
            *args: Iterable and static arguments to run the tasks with
            return_state: Return a list of Prefect States that wrap the results
                of each task run.
            wait_for: Upstream task futures to wait for before starting the
                task
            **kwargs: Keyword iterable arguments to run the task with

        Returns:
            A list of futures allowing asynchronous access to the state of the
            tasks

        Examples:

            Define a task

            >>> from prefect import task
            >>> @task
            >>> def my_task(x):
            >>>     return x + 1

            Create mapped tasks

            >>> from prefect import flow
            >>> @flow
            >>> def my_flow():
            >>>     my_task.map([1, 2, 3])

            Wait for all mapped tasks to finish

            >>> @flow
            >>> def my_flow():
            >>>     futures = my_task.map([1, 2, 3])
            >>>     for future in futures:
            >>>         future.wait()
            >>>     # Now all of the mapped tasks have finished
            >>>     my_task(10)

            Use the result from mapped tasks in a flow

            >>> @flow
            >>> def my_flow():
            >>>     futures = my_task.map([1, 2, 3])
            >>>     for future in futures:
            >>>         print(future.result())
            >>> my_flow()
            2
            3
            4

            Enforce ordering between tasks that do not exchange data
            >>> @task
            >>> def task_1(x):
            >>>     pass
            >>>
            >>> @task
            >>> def task_2(y):
            >>>     pass
            >>>
            >>> @flow
            >>> def my_flow():
            >>>     x = task_1.submit()
            >>>
            >>>     # task 2 will wait for task_1 to complete
            >>>     y = task_2.map([1, 2, 3], wait_for=[x])

            Use a non-iterable input as a constant across mapped tasks
            >>> @task
            >>> def display(prefix, item):
            >>>    print(prefix, item)
            >>>
            >>> @flow
            >>> def my_flow():
            >>>     display.map("Check it out: ", [1, 2, 3])
            >>>
            >>> my_flow()
            Check it out: 1
            Check it out: 2
            Check it out: 3

            Use `unmapped` to treat an iterable argument as a constant
            >>> from prefect import unmapped
            >>>
            >>> @task
            >>> def add_n_to_items(items, n):
            >>>     return [item + n for item in items]
            >>>
            >>> @flow
            >>> def my_flow():
            >>>     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])
            >>>
            >>> my_flow()
            [[11, 21], [12, 22], [13, 23]]
        """

        from prefect.engine import enter_task_run_engine

        # Convert the call args/kwargs to a parameter dict; do not apply defaults
        # since they should not be mapped over
        parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)
        return_type = "state" if return_state else "future"

        task_viz_tracker = get_task_viz_tracker()
        if task_viz_tracker:
            raise VisualizationUnsupportedError(
                "`task.map()` is not currently supported by `flow.visualize()`"
            )

        return enter_task_run_engine(
            self,
            parameters=parameters,
            wait_for=wait_for,
            return_type=return_type,
            task_runner=None,
            mapped=True,
        )

map

Submit a mapped run of the task to a worker.

Must be called within a flow function. If writing an async task, this call must be awaited.

Must be called with at least one iterable and all iterables must be the same length. Any arguments that are not iterable will be treated as a static value and each task run will receive the same value.

Will create as many task runs as the length of the iterable(s) in the backing API and submit the task runs to the flow's task runner. This call blocks if given a future as input while the future is resolved. It also blocks while the tasks are being submitted, once they are submitted, the flow function will continue executing. However, note that the SequentialTaskRunner does not implement parallel execution for sync tasks and they are fully resolved on submission.

Parameters:

Name Type Description Default
*args Any

Iterable and static arguments to run the tasks with

()
return_state bool

Return a list of Prefect States that wrap the results of each task run.

False
wait_for Optional[Iterable[PrefectFuture]]

Upstream task futures to wait for before starting the task

None
**kwargs Any

Keyword iterable arguments to run the task with

{}

Returns:

Type Description
Any

A list of futures allowing asynchronous access to the state of the

Any

tasks

Define a task

>>> from prefect import task
>>> @task
>>> def my_task(x):
>>>     return x + 1

Create mapped tasks

>>> from prefect import flow
>>> @flow
>>> def my_flow():
>>>     my_task.map([1, 2, 3])

Wait for all mapped tasks to finish

>>> @flow
>>> def my_flow():
>>>     futures = my_task.map([1, 2, 3])
>>>     for future in futures:
>>>         future.wait()
>>>     # Now all of the mapped tasks have finished
>>>     my_task(10)

Use the result from mapped tasks in a flow

>>> @flow
>>> def my_flow():
>>>     futures = my_task.map([1, 2, 3])
>>>     for future in futures:
>>>         print(future.result())
>>> my_flow()
2
3
4

Enforce ordering between tasks that do not exchange data
>>> @task
>>> def task_1(x):
>>>     pass
>>>
>>> @task
>>> def task_2(y):
>>>     pass
>>>
>>> @flow
>>> def my_flow():
>>>     x = task_1.submit()
>>>
>>>     # task 2 will wait for task_1 to complete
>>>     y = task_2.map([1, 2, 3], wait_for=[x])

Use a non-iterable input as a constant across mapped tasks
>>> @task
>>> def display(prefix, item):
>>>    print(prefix, item)
>>>
>>> @flow
>>> def my_flow():
>>>     display.map("Check it out: ", [1, 2, 3])
>>>
>>> my_flow()
Check it out: 1
Check it out: 2
Check it out: 3

Use `unmapped` to treat an iterable argument as a constant
>>> from prefect import unmapped
>>>
>>> @task
>>> def add_n_to_items(items, n):
>>>     return [item + n for item in items]
>>>
>>> @flow
>>> def my_flow():
>>>     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])
>>>
>>> my_flow()
[[11, 21], [12, 22], [13, 23]]
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
def map(
    self,
    *args: Any,
    return_state: bool = False,
    wait_for: Optional[Iterable[PrefectFuture]] = None,
    **kwargs: Any,
) -> Any:
    """
    Submit a mapped run of the task to a worker.

    Must be called within a flow function. If writing an async task, this
    call must be awaited.

    Must be called with at least one iterable and all iterables must be
    the same length. Any arguments that are not iterable will be treated as
    a static value and each task run will receive the same value.

    Will create as many task runs as the length of the iterable(s) in the
    backing API and submit the task runs to the flow's task runner. This
    call blocks if given a future as input while the future is resolved. It
    also blocks while the tasks are being submitted, once they are
    submitted, the flow function will continue executing. However, note
    that the `SequentialTaskRunner` does not implement parallel execution
    for sync tasks and they are fully resolved on submission.

    Args:
        *args: Iterable and static arguments to run the tasks with
        return_state: Return a list of Prefect States that wrap the results
            of each task run.
        wait_for: Upstream task futures to wait for before starting the
            task
        **kwargs: Keyword iterable arguments to run the task with

    Returns:
        A list of futures allowing asynchronous access to the state of the
        tasks

    Examples:

        Define a task

        >>> from prefect import task
        >>> @task
        >>> def my_task(x):
        >>>     return x + 1

        Create mapped tasks

        >>> from prefect import flow
        >>> @flow
        >>> def my_flow():
        >>>     my_task.map([1, 2, 3])

        Wait for all mapped tasks to finish

        >>> @flow
        >>> def my_flow():
        >>>     futures = my_task.map([1, 2, 3])
        >>>     for future in futures:
        >>>         future.wait()
        >>>     # Now all of the mapped tasks have finished
        >>>     my_task(10)

        Use the result from mapped tasks in a flow

        >>> @flow
        >>> def my_flow():
        >>>     futures = my_task.map([1, 2, 3])
        >>>     for future in futures:
        >>>         print(future.result())
        >>> my_flow()
        2
        3
        4

        Enforce ordering between tasks that do not exchange data
        >>> @task
        >>> def task_1(x):
        >>>     pass
        >>>
        >>> @task
        >>> def task_2(y):
        >>>     pass
        >>>
        >>> @flow
        >>> def my_flow():
        >>>     x = task_1.submit()
        >>>
        >>>     # task 2 will wait for task_1 to complete
        >>>     y = task_2.map([1, 2, 3], wait_for=[x])

        Use a non-iterable input as a constant across mapped tasks
        >>> @task
        >>> def display(prefix, item):
        >>>    print(prefix, item)
        >>>
        >>> @flow
        >>> def my_flow():
        >>>     display.map("Check it out: ", [1, 2, 3])
        >>>
        >>> my_flow()
        Check it out: 1
        Check it out: 2
        Check it out: 3

        Use `unmapped` to treat an iterable argument as a constant
        >>> from prefect import unmapped
        >>>
        >>> @task
        >>> def add_n_to_items(items, n):
        >>>     return [item + n for item in items]
        >>>
        >>> @flow
        >>> def my_flow():
        >>>     return add_n_to_items.map(unmapped([10, 20]), n=[1, 2, 3])
        >>>
        >>> my_flow()
        [[11, 21], [12, 22], [13, 23]]
    """

    from prefect.engine import enter_task_run_engine

    # Convert the call args/kwargs to a parameter dict; do not apply defaults
    # since they should not be mapped over
    parameters = get_call_parameters(self.fn, args, kwargs, apply_defaults=False)
    return_type = "state" if return_state else "future"

    task_viz_tracker = get_task_viz_tracker()
    if task_viz_tracker:
        raise VisualizationUnsupportedError(
            "`task.map()` is not currently supported by `flow.visualize()`"
        )

    return enter_task_run_engine(
        self,
        parameters=parameters,
        wait_for=wait_for,
        return_type=return_type,
        task_runner=None,
        mapped=True,
    )

submit

Submit a run of the task to a worker.

Must be called within a flow function. If writing an async task, this call must be awaited.

Will create a new task run in the backing API and submit the task to the flow's task runner. This call only blocks execution while the task is being submitted, once it is submitted, the flow function will continue executing. However, note that the SequentialTaskRunner does not implement parallel execution for sync tasks and they are fully resolved on submission.

Parameters:

Name Type Description Default
*args Any

Arguments to run the task with

()
return_state bool

Return the result of the flow run wrapped in a Prefect State.

False
wait_for Optional[Iterable[PrefectFuture]]

Upstream task futures to wait for before starting the task

None
**kwargs Any

Keyword arguments to run the task with

{}

Returns:

Type Description
Union[PrefectFuture, Awaitable[PrefectFuture]]

If return_state is False a future allowing asynchronous access to the state of the task

Union[PrefectFuture, Awaitable[PrefectFuture]]

If return_state is True a future wrapped in a Prefect State allowing asynchronous access to the state of the task

Define a task

>>> from prefect import task
>>> @task
>>> def my_task():
>>>     return "hello"

Run a task in a flow

>>> from prefect import flow
>>> @flow
>>> def my_flow():
>>>     my_task.submit()

Wait for a task to finish

>>> @flow
>>> def my_flow():
>>>     my_task.submit().wait()

Use the result from a task in a flow

>>> @flow
>>> def my_flow():
>>>     print(my_task.submit().result())
>>>
>>> my_flow()
hello

Run an async task in an async flow

>>> @task
>>> async def my_async_task():
>>>     pass
>>>
>>> @flow
>>> async def my_flow():
>>>     await my_async_task.submit()

Run a sync task in an async flow

>>> @flow
>>> async def my_flow():
>>>     my_task.submit()

Enforce ordering between tasks that do not exchange data
>>> @task
>>> def task_1():
>>>     pass
>>>
>>> @task
>>> def task_2():
>>>     pass
>>>
>>> @flow
>>> def my_flow():
>>>     x = task_1.submit()
>>>
>>>     # task 2 will wait for task_1 to complete
>>>     y = task_2.submit(wait_for=[x])
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
def submit(
    self,
    *args: Any,
    return_state: bool = False,
    wait_for: Optional[Iterable[PrefectFuture]] = None,
    **kwargs: Any,
) -> Union[PrefectFuture, Awaitable[PrefectFuture]]:
    """
    Submit a run of the task to a worker.

    Must be called within a flow function. If writing an async task, this call must
    be awaited.

    Will create a new task run in the backing API and submit the task to the flow's
    task runner. This call only blocks execution while the task is being submitted,
    once it is submitted, the flow function will continue executing. However, note
    that the `SequentialTaskRunner` does not implement parallel execution for sync tasks
    and they are fully resolved on submission.

    Args:
        *args: Arguments to run the task with
        return_state: Return the result of the flow run wrapped in a
            Prefect State.
        wait_for: Upstream task futures to wait for before starting the task
        **kwargs: Keyword arguments to run the task with

    Returns:
        If `return_state` is False a future allowing asynchronous access to
            the state of the task
        If `return_state` is True a future wrapped in a Prefect State allowing asynchronous access to
            the state of the task

    Examples:

        Define a task

        >>> from prefect import task
        >>> @task
        >>> def my_task():
        >>>     return "hello"

        Run a task in a flow

        >>> from prefect import flow
        >>> @flow
        >>> def my_flow():
        >>>     my_task.submit()

        Wait for a task to finish

        >>> @flow
        >>> def my_flow():
        >>>     my_task.submit().wait()

        Use the result from a task in a flow

        >>> @flow
        >>> def my_flow():
        >>>     print(my_task.submit().result())
        >>>
        >>> my_flow()
        hello

        Run an async task in an async flow

        >>> @task
        >>> async def my_async_task():
        >>>     pass
        >>>
        >>> @flow
        >>> async def my_flow():
        >>>     await my_async_task.submit()

        Run a sync task in an async flow

        >>> @flow
        >>> async def my_flow():
        >>>     my_task.submit()

        Enforce ordering between tasks that do not exchange data
        >>> @task
        >>> def task_1():
        >>>     pass
        >>>
        >>> @task
        >>> def task_2():
        >>>     pass
        >>>
        >>> @flow
        >>> def my_flow():
        >>>     x = task_1.submit()
        >>>
        >>>     # task 2 will wait for task_1 to complete
        >>>     y = task_2.submit(wait_for=[x])

    """

    from prefect.engine import enter_task_run_engine

    # Convert the call args/kwargs to a parameter dict
    parameters = get_call_parameters(self.fn, args, kwargs)
    return_type = "state" if return_state else "future"

    task_viz_tracker = get_task_viz_tracker()
    if task_viz_tracker:
        raise VisualizationUnsupportedError(
            "`task.submit()` is not currently supported by `flow.visualize()`"
        )

    return enter_task_run_engine(
        self,
        parameters=parameters,
        wait_for=wait_for,
        return_type=return_type,
        task_runner=None,  # Use the flow's task runner
        mapped=False,
    )

with_options

Create a new task from the current object, updating provided options.

Parameters:

Name Type Description Default
name str

A new name for the task.

None
description str

A new description for the task.

None
tags Iterable[str]

A new set of tags for the task. If given, existing tags are ignored, not merged.

None
cache_key_fn Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]

A new cache key function for the task.

None
cache_expiration timedelta

A new cache expiration time for the task.

None
task_run_name Optional[Union[Callable[[], str], str]]

An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.

None
retries Optional[int]

A new number of times to retry on task run failure.

NotSet
retry_delay_seconds Union[float, int, List[float], Callable[[int], List[float]]]

Optionally configures how long to wait before retrying the task after failure. This is only applicable if retries is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.

NotSet
retry_jitter_factor Optional[float]

An optional factor that defines the factor to which a retry can be jittered in order to avoid a "thundering herd".

NotSet
persist_result Optional[bool]

A new option for enabling or disabling result persistence.

NotSet
result_storage Optional[ResultStorage]

A new storage type to use for results.

NotSet
result_serializer Optional[ResultSerializer]

A new serializer to use for results.

NotSet
result_storage_key Optional[str]

A new key for the persisted result to be stored at.

NotSet
timeout_seconds Union[int, float]

A new maximum time for the task to complete in seconds.

None
log_prints Optional[bool]

A new option for enabling or disabling redirection of print statements.

NotSet
refresh_cache Optional[bool]

A new option for enabling or disabling cache refresh.

NotSet
on_completion Optional[List[Callable[[Task, TaskRun, State], None]]]

A new list of callables to run when the task enters a completed state.

None
on_failure Optional[List[Callable[[Task, TaskRun, State], None]]]

A new list of callables to run when the task enters a failed state.

None
viz_return_value Optional[Any]

An optional value to return when the task dependency tree is visualized.

None

Returns:

Type Description

A new Task instance.

Create a new task from an existing task and update the name

>>> @task(name="My task")
>>> def my_task():
>>>     return 1
>>>
>>> new_task = my_task.with_options(name="My new task")

Create a new task from an existing task and update the retry settings

>>> from random import randint
>>>
>>> @task(retries=1, retry_delay_seconds=5)
>>> def my_task():
>>>     x = randint(0, 5)
>>>     if x >= 3:  # Make a task that fails sometimes
>>>         raise ValueError("Retry me please!")
>>>     return x
>>>
>>> new_task = my_task.with_options(retries=5, retry_delay_seconds=2)

Use a task with updated options within a flow

>>> @task(name="My task")
>>> def my_task():
>>>     return 1
>>>
>>> @flow
>>> my_flow():
>>>     new_task = my_task.with_options(name="My new task")
>>>     new_task()
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
def with_options(
    self,
    *,
    name: str = None,
    description: str = None,
    tags: Iterable[str] = None,
    cache_key_fn: Callable[
        ["TaskRunContext", Dict[str, Any]], Optional[str]
    ] = None,
    task_run_name: Optional[Union[Callable[[], str], str]] = None,
    cache_expiration: datetime.timedelta = None,
    retries: Optional[int] = NotSet,
    retry_delay_seconds: Union[
        float,
        int,
        List[float],
        Callable[[int], List[float]],
    ] = NotSet,
    retry_jitter_factor: Optional[float] = NotSet,
    persist_result: Optional[bool] = NotSet,
    result_storage: Optional[ResultStorage] = NotSet,
    result_serializer: Optional[ResultSerializer] = NotSet,
    result_storage_key: Optional[str] = NotSet,
    cache_result_in_memory: Optional[bool] = None,
    timeout_seconds: Union[int, float] = None,
    log_prints: Optional[bool] = NotSet,
    refresh_cache: Optional[bool] = NotSet,
    on_completion: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
    on_failure: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
    viz_return_value: Optional[Any] = None,
):
    """
    Create a new task from the current object, updating provided options.

    Args:
        name: A new name for the task.
        description: A new description for the task.
        tags: A new set of tags for the task. If given, existing tags are ignored,
            not merged.
        cache_key_fn: A new cache key function for the task.
        cache_expiration: A new cache expiration time for the task.
        task_run_name: An optional name to distinguish runs of this task; this name can be provided
            as a string template with the task's keyword arguments as variables,
            or a function that returns a string.
        retries: A new number of times to retry on task run failure.
        retry_delay_seconds: Optionally configures how long to wait before retrying
            the task after failure. This is only applicable if `retries` is nonzero.
            This setting can either be a number of seconds, a list of retry delays,
            or a callable that, given the total number of retries, generates a list
            of retry delays. If a number of seconds, that delay will be applied to
            all retries. If a list, each retry will wait for the corresponding delay
            before retrying. When passing a callable or a list, the number of
            configured retry delays cannot exceed 50.
        retry_jitter_factor: An optional factor that defines the factor to which a
            retry can be jittered in order to avoid a "thundering herd".
        persist_result: A new option for enabling or disabling result persistence.
        result_storage: A new storage type to use for results.
        result_serializer: A new serializer to use for results.
        result_storage_key: A new key for the persisted result to be stored at.
        timeout_seconds: A new maximum time for the task to complete in seconds.
        log_prints: A new option for enabling or disabling redirection of `print` statements.
        refresh_cache: A new option for enabling or disabling cache refresh.
        on_completion: A new list of callables to run when the task enters a completed state.
        on_failure: A new list of callables to run when the task enters a failed state.
        viz_return_value: An optional value to return when the task dependency tree is visualized.

    Returns:
        A new `Task` instance.

    Examples:

        Create a new task from an existing task and update the name

        >>> @task(name="My task")
        >>> def my_task():
        >>>     return 1
        >>>
        >>> new_task = my_task.with_options(name="My new task")

        Create a new task from an existing task and update the retry settings

        >>> from random import randint
        >>>
        >>> @task(retries=1, retry_delay_seconds=5)
        >>> def my_task():
        >>>     x = randint(0, 5)
        >>>     if x >= 3:  # Make a task that fails sometimes
        >>>         raise ValueError("Retry me please!")
        >>>     return x
        >>>
        >>> new_task = my_task.with_options(retries=5, retry_delay_seconds=2)

        Use a task with updated options within a flow

        >>> @task(name="My task")
        >>> def my_task():
        >>>     return 1
        >>>
        >>> @flow
        >>> my_flow():
        >>>     new_task = my_task.with_options(name="My new task")
        >>>     new_task()
    """
    return Task(
        fn=self.fn,
        name=name or self.name,
        description=description or self.description,
        tags=tags or copy(self.tags),
        cache_key_fn=cache_key_fn or self.cache_key_fn,
        cache_expiration=cache_expiration or self.cache_expiration,
        task_run_name=task_run_name,
        retries=retries if retries is not NotSet else self.retries,
        retry_delay_seconds=(
            retry_delay_seconds
            if retry_delay_seconds is not NotSet
            else self.retry_delay_seconds
        ),
        retry_jitter_factor=(
            retry_jitter_factor
            if retry_jitter_factor is not NotSet
            else self.retry_jitter_factor
        ),
        persist_result=(
            persist_result if persist_result is not NotSet else self.persist_result
        ),
        result_storage=(
            result_storage if result_storage is not NotSet else self.result_storage
        ),
        result_storage_key=(
            result_storage_key
            if result_storage_key is not NotSet
            else self.result_storage_key
        ),
        result_serializer=(
            result_serializer
            if result_serializer is not NotSet
            else self.result_serializer
        ),
        cache_result_in_memory=(
            cache_result_in_memory
            if cache_result_in_memory is not None
            else self.cache_result_in_memory
        ),
        timeout_seconds=(
            timeout_seconds if timeout_seconds is not None else self.timeout_seconds
        ),
        log_prints=(log_prints if log_prints is not NotSet else self.log_prints),
        refresh_cache=(
            refresh_cache if refresh_cache is not NotSet else self.refresh_cache
        ),
        on_completion=on_completion or self.on_completion,
        on_failure=on_failure or self.on_failure,
        viz_return_value=viz_return_value or self.viz_return_value,
    )

exponential_backoff

A task retry backoff utility that configures exponential backoff for task retries. The exponential backoff design matches the urllib3 implementation.

Parameters:

Name Type Description Default
backoff_factor float

the base delay for the first retry, subsequent retries will increase the delay time by powers of 2.

required

Returns:

Type Description
Callable[[int], List[float]]

a callable that can be passed to the task constructor

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def exponential_backoff(backoff_factor: float) -> Callable[[int], List[float]]:
    """
    A task retry backoff utility that configures exponential backoff for task retries.
    The exponential backoff design matches the urllib3 implementation.

    Arguments:
        backoff_factor: the base delay for the first retry, subsequent retries will
            increase the delay time by powers of 2.

    Returns:
        a callable that can be passed to the task constructor
    """

    def retry_backoff_callable(retries: int) -> List[float]:
        # no more than 50 retry delays can be configured on a task
        retries = min(retries, 50)

        return [backoff_factor * max(0, 2**r) for r in range(retries)]

    return retry_backoff_callable

task

Decorator to designate a function as a task in a Prefect workflow.

This decorator may be used for asynchronous or synchronous functions.

Parameters:

Name Type Description Default
name str

An optional name for the task; if not provided, the name will be inferred from the given function.

None
description str

An optional string description for the task.

None
tags Iterable[str]

An optional set of tags to be associated with runs of this task. These tags are combined with any tags defined by a prefect.tags context at task runtime.

None
version str

An optional string specifying the version of this task definition

None
cache_key_fn Callable[[TaskRunContext, Dict[str, Any]], Optional[str]]

An optional callable that, given the task run context and call parameters, generates a string key; if the key matches a previous completed state, that state result will be restored instead of running the task again.

None
cache_expiration timedelta

An optional amount of time indicating how long cached states for this task should be restorable; if not provided, cached states will never expire.

None
task_run_name Optional[Union[Callable[[], str], str]]

An optional name to distinguish runs of this task; this name can be provided as a string template with the task's keyword arguments as variables, or a function that returns a string.

None
retries int

An optional number of times to retry on task run failure

None
retry_delay_seconds Union[float, int, List[float], Callable[[int], List[float]]]

Optionally configures how long to wait before retrying the task after failure. This is only applicable if retries is nonzero. This setting can either be a number of seconds, a list of retry delays, or a callable that, given the total number of retries, generates a list of retry delays. If a number of seconds, that delay will be applied to all retries. If a list, each retry will wait for the corresponding delay before retrying. When passing a callable or a list, the number of configured retry delays cannot exceed 50.

None
retry_jitter_factor Optional[float]

An optional factor that defines the factor to which a retry can be jittered in order to avoid a "thundering herd".

None
persist_result Optional[bool]

An optional toggle indicating whether the result of this task should be persisted to result storage. Defaults to None, which indicates that Prefect should choose whether the result should be persisted depending on the features being used.

None
result_storage Optional[ResultStorage]

An optional block to use to persist the result of this task. Defaults to the value set in the flow the task is called in.

None
result_storage_key Optional[str]

An optional key to store the result in storage at when persisted. Defaults to a unique identifier.

None
result_serializer Optional[ResultSerializer]

An optional serializer to use to serialize the result of this task for persistence. Defaults to the value set in the flow the task is called in.

None
timeout_seconds Union[int, float]

An optional number of seconds indicating a maximum runtime for the task. If the task exceeds this runtime, it will be marked as failed.

None
log_prints Optional[bool]

If set, print statements in the task will be redirected to the Prefect logger for the task run. Defaults to None, which indicates that the value from the flow should be used.

None
refresh_cache Optional[bool]

If set, cached results for the cache key are not used. Defaults to None, which indicates that a cached result from a previous execution with matching cache key is used.

None
on_failure Optional[List[Callable[[Task, TaskRun, State], None]]]

An optional list of callables to run when the task enters a failed state.

None
on_completion Optional[List[Callable[[Task, TaskRun, State], None]]]

An optional list of callables to run when the task enters a completed state.

None
viz_return_value Any

An optional value to return when the task dependency tree is visualized.

None

Returns:

Type Description

A callable Task object which, when called, will submit the task for execution.

Examples:

Define a simple task

>>> @task
>>> def add(x, y):
>>>     return x + y

Define an async task

>>> @task
>>> async def add(x, y):
>>>     return x + y

Define a task with tags and a description

>>> @task(tags={"a", "b"}, description="This task is empty but its my first!")
>>> def my_task():
>>>     pass

Define a task with a custom name

>>> @task(name="The Ultimate Task")
>>> def my_task():
>>>     pass

Define a task that retries 3 times with a 5 second delay between attempts

>>> from random import randint
>>>
>>> @task(retries=3, retry_delay_seconds=5)
>>> def my_task():
>>>     x = randint(0, 5)
>>>     if x >= 3:  # Make a task that fails sometimes
>>>         raise ValueError("Retry me please!")
>>>     return x

Define a task that is cached for a day based on its inputs

>>> from prefect.tasks import task_input_hash
>>> from datetime import timedelta
>>>
>>> @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))
>>> def my_task():
>>>     return "hello"
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
def task(
    __fn=None,
    *,
    name: str = None,
    description: str = None,
    tags: Iterable[str] = None,
    version: str = None,
    cache_key_fn: Callable[["TaskRunContext", Dict[str, Any]], Optional[str]] = None,
    cache_expiration: datetime.timedelta = None,
    task_run_name: Optional[Union[Callable[[], str], str]] = None,
    retries: int = None,
    retry_delay_seconds: Union[
        float,
        int,
        List[float],
        Callable[[int], List[float]],
    ] = None,
    retry_jitter_factor: Optional[float] = None,
    persist_result: Optional[bool] = None,
    result_storage: Optional[ResultStorage] = None,
    result_storage_key: Optional[str] = None,
    result_serializer: Optional[ResultSerializer] = None,
    cache_result_in_memory: bool = True,
    timeout_seconds: Union[int, float] = None,
    log_prints: Optional[bool] = None,
    refresh_cache: Optional[bool] = None,
    on_completion: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
    on_failure: Optional[List[Callable[["Task", TaskRun, State], None]]] = None,
    viz_return_value: Any = None,
):
    """
    Decorator to designate a function as a task in a Prefect workflow.

    This decorator may be used for asynchronous or synchronous functions.

    Args:
        name: An optional name for the task; if not provided, the name will be inferred
            from the given function.
        description: An optional string description for the task.
        tags: An optional set of tags to be associated with runs of this task. These
            tags are combined with any tags defined by a `prefect.tags` context at
            task runtime.
        version: An optional string specifying the version of this task definition
        cache_key_fn: An optional callable that, given the task run context and call
            parameters, generates a string key; if the key matches a previous completed
            state, that state result will be restored instead of running the task again.
        cache_expiration: An optional amount of time indicating how long cached states
            for this task should be restorable; if not provided, cached states will
            never expire.
        task_run_name: An optional name to distinguish runs of this task; this name can be provided
            as a string template with the task's keyword arguments as variables,
            or a function that returns a string.
        retries: An optional number of times to retry on task run failure
        retry_delay_seconds: Optionally configures how long to wait before retrying the
            task after failure. This is only applicable if `retries` is nonzero. This
            setting can either be a number of seconds, a list of retry delays, or a
            callable that, given the total number of retries, generates a list of retry
            delays. If a number of seconds, that delay will be applied to all retries.
            If a list, each retry will wait for the corresponding delay before retrying.
            When passing a callable or a list, the number of configured retry delays
            cannot exceed 50.
        retry_jitter_factor: An optional factor that defines the factor to which a retry
            can be jittered in order to avoid a "thundering herd".
        persist_result: An optional toggle indicating whether the result of this task
            should be persisted to result storage. Defaults to `None`, which indicates
            that Prefect should choose whether the result should be persisted depending on
            the features being used.
        result_storage: An optional block to use to persist the result of this task.
            Defaults to the value set in the flow the task is called in.
        result_storage_key: An optional key to store the result in storage at when persisted.
            Defaults to a unique identifier.
        result_serializer: An optional serializer to use to serialize the result of this
            task for persistence. Defaults to the value set in the flow the task is
            called in.
        timeout_seconds: An optional number of seconds indicating a maximum runtime for
            the task. If the task exceeds this runtime, it will be marked as failed.
        log_prints: If set, `print` statements in the task will be redirected to the
            Prefect logger for the task run. Defaults to `None`, which indicates
            that the value from the flow should be used.
        refresh_cache: If set, cached results for the cache key are not used.
            Defaults to `None`, which indicates that a cached result from a previous
            execution with matching cache key is used.
        on_failure: An optional list of callables to run when the task enters a failed state.
        on_completion: An optional list of callables to run when the task enters a completed state.
        viz_return_value: An optional value to return when the task dependency tree is visualized.

    Returns:
        A callable `Task` object which, when called, will submit the task for execution.

    Examples:
        Define a simple task

        >>> @task
        >>> def add(x, y):
        >>>     return x + y

        Define an async task

        >>> @task
        >>> async def add(x, y):
        >>>     return x + y

        Define a task with tags and a description

        >>> @task(tags={"a", "b"}, description="This task is empty but its my first!")
        >>> def my_task():
        >>>     pass

        Define a task with a custom name

        >>> @task(name="The Ultimate Task")
        >>> def my_task():
        >>>     pass

        Define a task that retries 3 times with a 5 second delay between attempts

        >>> from random import randint
        >>>
        >>> @task(retries=3, retry_delay_seconds=5)
        >>> def my_task():
        >>>     x = randint(0, 5)
        >>>     if x >= 3:  # Make a task that fails sometimes
        >>>         raise ValueError("Retry me please!")
        >>>     return x

        Define a task that is cached for a day based on its inputs

        >>> from prefect.tasks import task_input_hash
        >>> from datetime import timedelta
        >>>
        >>> @task(cache_key_fn=task_input_hash, cache_expiration=timedelta(days=1))
        >>> def my_task():
        >>>     return "hello"
    """

    if __fn:
        return cast(
            Task[P, R],
            Task(
                fn=__fn,
                name=name,
                description=description,
                tags=tags,
                version=version,
                cache_key_fn=cache_key_fn,
                cache_expiration=cache_expiration,
                task_run_name=task_run_name,
                retries=retries,
                retry_delay_seconds=retry_delay_seconds,
                retry_jitter_factor=retry_jitter_factor,
                persist_result=persist_result,
                result_storage=result_storage,
                result_storage_key=result_storage_key,
                result_serializer=result_serializer,
                cache_result_in_memory=cache_result_in_memory,
                timeout_seconds=timeout_seconds,
                log_prints=log_prints,
                refresh_cache=refresh_cache,
                on_completion=on_completion,
                on_failure=on_failure,
                viz_return_value=viz_return_value,
            ),
        )
    else:
        return cast(
            Callable[[Callable[P, R]], Task[P, R]],
            partial(
                task,
                name=name,
                description=description,
                tags=tags,
                version=version,
                cache_key_fn=cache_key_fn,
                cache_expiration=cache_expiration,
                task_run_name=task_run_name,
                retries=retries,
                retry_delay_seconds=retry_delay_seconds,
                retry_jitter_factor=retry_jitter_factor,
                persist_result=persist_result,
                result_storage=result_storage,
                result_storage_key=result_storage_key,
                result_serializer=result_serializer,
                cache_result_in_memory=cache_result_in_memory,
                timeout_seconds=timeout_seconds,
                log_prints=log_prints,
                refresh_cache=refresh_cache,
                on_completion=on_completion,
                on_failure=on_failure,
                viz_return_value=viz_return_value,
            ),
        )

task_input_hash

A task cache key implementation which hashes all inputs to the task using a JSON or cloudpickle serializer. If any arguments are not JSON serializable, the pickle serializer is used as a fallback. If cloudpickle fails, this will return a null key indicating that a cache key could not be generated for the given inputs.

Parameters:

Name Type Description Default
context TaskRunContext

the active TaskRunContext

required
arguments Dict[str, Any]

a dictionary of arguments to be passed to the underlying task

required

Returns:

Type Description
Optional[str]

a string hash if hashing succeeded, else None

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/tasks.py
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def task_input_hash(
    context: "TaskRunContext", arguments: Dict[str, Any]
) -> Optional[str]:
    """
    A task cache key implementation which hashes all inputs to the task using a JSON or
    cloudpickle serializer. If any arguments are not JSON serializable, the pickle
    serializer is used as a fallback. If cloudpickle fails, this will return a null key
    indicating that a cache key could not be generated for the given inputs.

    Arguments:
        context: the active `TaskRunContext`
        arguments: a dictionary of arguments to be passed to the underlying task

    Returns:
        a string hash if hashing succeeded, else `None`
    """
    return hash_objects(
        # We use the task key to get the qualified name for the task and include the
        # task functions `co_code` bytes to avoid caching when the underlying function
        # changes
        context.task.task_key,
        context.task.fn.__code__.co_code.hex(),
        arguments,
    )