---
sidebarDepth: 2
editLink: false
---
# Task Utilities
---

## Functions
|top-level functions: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|
|:----|
 | <div class='method-sig' id='prefect-utilities-tasks-tags'><p class="prefect-class">prefect.utilities.tasks.tags</p>(*tags)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L207">[source]</a></span></div>
<p class="methods">Context manager for setting task tags.<br><br>**Args**:     <ul class="args"><li class="args">`*tags ([str])`: a list of tags to apply to the tasks created within         the context manager</li></ul> **Example**: <br><pre class="language-python"><code class="language-python"><span class="token decorator">@task</span><br><span class="token keyword">def</span> <span class="token function">add</span><span class="token punctuation">(</span>x<span class="token punctuation">,</span> y<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">return</span> x <span class="token operator">+</span> y<br><br><span class="token keyword">with</span> Flow<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">My Flow</span><span class="token string">"</span><span class="token punctuation">)</span> <span class="token keyword">as</span> f<span class="token punctuation">:</span><br>    <span class="token keyword">with</span> tags<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">math</span><span class="token string">"</span><span class="token punctuation">,</span> <span class="token string">"</span><span class="token string">function</span><span class="token string">"</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>        result <span class="token operator">=</span> add<span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">5</span><span class="token punctuation">)</span><br><br><span class="token builtin">print</span><span class="token punctuation">(</span>result<span class="token operator">.</span>tags<span class="token punctuation">)</span> <span class="token comment"># {"function", "math"}</span><br></code></pre><br></p>|
 | <div class='method-sig' id='prefect-utilities-tasks-as-task'><p class="prefect-class">prefect.utilities.tasks.as_task</p>(x, flow=None)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L235">[source]</a></span></div>
<p class="methods">Wraps a function, collection, or constant with the appropriate Task type. If a constant or collection of constants is passed, a `Constant` task is returned.<br><br>**Args**:     <ul class="args"><li class="args">`x (object)`: any Python object to convert to a prefect Task     </li><li class="args">`flow (Flow, optional)`: Flow to which the prefect Task will be bound</li></ul> **Returns**:     <ul class="args"><li class="args">a prefect Task representing the passed object</li></ul></p>|
 | <div class='method-sig' id='prefect-utilities-tasks-pause-task'><p class="prefect-class">prefect.utilities.tasks.pause_task</p>(message=None, duration=None)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L295">[source]</a></span></div>
<p class="methods">Utility function for pausing a task during execution to wait for manual intervention. Note that the _entire task_ will be rerun if the user decides to run this task again! The only difference is that this utility will _not_ raise a `PAUSE` signal. To bypass a `PAUSE` signal being raised, put the task into a Resume state.<br><br>**Args**:     <ul class="args"><li class="args">`message (str)`: an optional message for the Pause state.     </li><li class="args">`duration (timedelta)`: an optional pause duration; otherwise infinite (well, 10 years)</li></ul> **Example**:     <br><pre class="language-python"><code class="language-python">    <span class="token keyword">from</span> prefect <span class="token keyword">import</span> Flow<br>    <span class="token keyword">from</span> prefect.utilities.tasks <span class="token keyword">import</span> task<span class="token punctuation">,</span> pause_task<br><br>    <span class="token decorator">@task</span><br>    <span class="token keyword">def</span> <span class="token function">add</span><span class="token punctuation">(</span>x<span class="token punctuation">,</span> y<span class="token punctuation">)</span><span class="token punctuation">:</span><br>        z <span class="token operator">=</span> y <span class="token operator">-</span> x  <span class="token comment">## this code will be rerun after resuming from the pause!</span><br>        <span class="token keyword">if</span> z <span class="token operator">==</span> <span class="token number">0</span><span class="token punctuation">:</span> <span class="token comment">## this code will be rerun after resuming from the pause!</span><br>            pause_task<span class="token punctuation">(</span><span class="token punctuation">)</span><br>        <span class="token keyword">return</span> x <span class="token operator">+</span> y<br><br>    <span class="token keyword">with</span> Flow<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">My Flow</span><span class="token string">"</span><span class="token punctuation">)</span> <span class="token keyword">as</span> f<span class="token punctuation">:</span><br>        res <span class="token operator">=</span> add<span class="token punctuation">(</span><span class="token number">4</span><span class="token punctuation">,</span> <span class="token number">4</span><span class="token punctuation">)</span><br><br>    state <span class="token operator">=</span> f<span class="token operator">.</span>run<span class="token punctuation">(</span><span class="token punctuation">)</span><br>    state<span class="token operator">.</span>result<span class="token punctuation">[</span>res<span class="token punctuation">]</span> <span class="token comment"># a Paused state</span><br><br>    state <span class="token operator">=</span> f<span class="token operator">.</span>run<span class="token punctuation">(</span>task_states<span class="token operator">=</span><span class="token punctuation">{</span>res<span class="token punctuation">:</span> Resume<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">}</span><span class="token punctuation">)</span><br>    state<span class="token operator">.</span>result<span class="token punctuation">[</span>res<span class="token punctuation">]</span> <span class="token comment"># a Success state</span><br>    <br></code></pre><br></p>|
 | <div class='method-sig' id='prefect-utilities-tasks-task'><p class="prefect-class">prefect.utilities.tasks.task</p>(fn=None, **task_init_kwargs)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L353">[source]</a></span></div>
<p class="methods">A decorator for creating Tasks from functions.<br><br>**Args**:     <ul class="args"><li class="args">`fn (Callable)`: the decorated function     </li><li class="args">`**task_init_kwargs (Any)`: keyword arguments that will be passed to the `Task`         constructor on initialization.</li></ul> **Returns**:     <ul class="args"><li class="args">`FunctionTask`: A instance of a FunctionTask</li></ul> **Raises**:     <ul class="args"><li class="args">`ValueError`: if the provided function violates signature requirements         for Task run methods</li></ul> Usage:<br><br><br><pre class="language-python"><code class="language-python"><span class="token decorator">@task</span><span class="token punctuation">(</span>name<span class="token operator">=</span><span class="token string">'</span><span class="token string">hello</span><span class="token string">'</span><span class="token punctuation">,</span> retries<span class="token operator">=</span><span class="token number">3</span><span class="token punctuation">)</span><br><span class="token keyword">def</span> <span class="token function">hello</span><span class="token punctuation">(</span>name<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token builtin">print</span><span class="token punctuation">(</span><span class="token string">'</span><span class="token string">hello, </span><span class="token string">{}</span><span class="token string">'</span><span class="token operator">.</span>format<span class="token punctuation">(</span>name<span class="token punctuation">)</span><span class="token punctuation">)</span><br><br><span class="token keyword">with</span> Flow<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">My Flow</span><span class="token string">"</span><span class="token punctuation">)</span> <span class="token keyword">as</span> flow<span class="token punctuation">:</span><br>    t1 <span class="token operator">=</span> hello<span class="token punctuation">(</span><span class="token string">'</span><span class="token string">foo</span><span class="token string">'</span><span class="token punctuation">)</span><br>    t2 <span class="token operator">=</span> hello<span class="token punctuation">(</span><span class="token string">'</span><span class="token string">bar</span><span class="token string">'</span><span class="token punctuation">)</span><br></code></pre><br><br><br>The decorator is best suited to Prefect's functional API, but can also be used with the imperative API.<br><br><br><pre class="language-python"><code class="language-python"><span class="token decorator">@task</span><br><span class="token keyword">def</span> <span class="token function">fn_without_args</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">return</span> <span class="token number">1</span><br><br><span class="token decorator">@task</span><br><span class="token keyword">def</span> <span class="token function">fn_with_args</span><span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">return</span> x<br><br><span class="token comment"># both tasks work inside a functional flow context</span><br><span class="token keyword">with</span> Flow<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">My Flow</span><span class="token string">"</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>    fn_without_args<span class="token punctuation">(</span><span class="token punctuation">)</span><br>    fn_with_args<span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><br></code></pre><br></p>|
 | <div class='method-sig' id='prefect-utilities-tasks-defaults-from-attrs'><p class="prefect-class">prefect.utilities.tasks.defaults_from_attrs</p>(*attr_args)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L413">[source]</a></span></div>
<p class="methods">Helper decorator for dealing with Task classes with attributes that serve as defaults for `Task.run`.  Specifically, this decorator allows the author of a Task to identify certain keyword arguments to the run method which will fall back to `self.ATTR_NAME` if not explicitly provided to `self.run`.  This pattern allows users to create a Task "template", whose default settings can be created at initialization but overrided in individual instances when the Task is called.<br><br>**Args**:     <ul class="args"><li class="args">`*attr_args (str)`: a splatted list of strings specifying which         kwargs should fallback to attributes, if not provided at runtime. Note that         the strings provided here must match keyword arguments in the `run` call signature,         as well as the names of attributes of this Task.</li></ul> **Returns**:     <ul class="args"><li class="args">`Callable`: the decorated / altered `Task.run` method</li></ul> **Example**: <br><pre class="language-python"><code class="language-python"><span class="token keyword">class</span> <span class="token class-name">MyTask</span><span class="token punctuation">(</span>Task<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">def</span> <span class="token function">__init__</span><span class="token punctuation">(</span><span class="token builtin">self</span><span class="token punctuation">,</span> a<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">,</span> b<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>        <span class="token builtin">self</span><span class="token operator">.</span>a <span class="token operator">=</span> a<br>        <span class="token builtin">self</span><span class="token operator">.</span>b <span class="token operator">=</span> b<br><br>    <span class="token decorator">@defaults_from_attrs</span><span class="token punctuation">(</span><span class="token string">'</span><span class="token string">a</span><span class="token string">'</span><span class="token punctuation">,</span> <span class="token string">'</span><span class="token string">b</span><span class="token string">'</span><span class="token punctuation">)</span><br>    <span class="token keyword">def</span> <span class="token function">run</span><span class="token punctuation">(</span><span class="token builtin">self</span><span class="token punctuation">,</span> a<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">,</span> b<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>        <span class="token keyword">return</span> a<span class="token punctuation">,</span> b<br><br>task <span class="token operator">=</span> MyTask<span class="token punctuation">(</span>a<span class="token operator">=</span><span class="token number">1</span><span class="token punctuation">,</span> b<span class="token operator">=</span><span class="token number">2</span><span class="token punctuation">)</span><br><br>task<span class="token operator">.</span>run<span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token comment"># (1, 2)</span><br>task<span class="token operator">.</span>run<span class="token punctuation">(</span>a<span class="token operator">=</span><span class="token number">99</span><span class="token punctuation">)</span> <span class="token comment"># (99, 2)</span><br>task<span class="token operator">.</span>run<span class="token punctuation">(</span>a<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">,</span> b<span class="token operator">=</span><span class="token keyword">None</span><span class="token punctuation">)</span> <span class="token comment"># (None, None)</span><br></code></pre><br></p>|
 | <div class='method-sig' id='prefect-utilities-tasks-apply-map'><p class="prefect-class">prefect.utilities.tasks.apply_map</p>(func, *args, flow=None, **kwargs)<span class="source"><a href="https://github.com/PrefectHQ/prefect/blob/master/src/prefect/utilities/tasks.py#L28">[source]</a></span></div>
<p class="methods">Map a function that adds tasks to a flow elementwise across one or more tasks.  Arguments that should _not_ be mapped over should be wrapped with `prefect.unmapped`. Nested arguments that should be unnested before mapping over should be wrapped with `prefect.flatten`<br><br>This can be useful when wanting to create complicated mapped pipelines (e.g. ones using control flow components like `case`).<br><br>**Args**:     <ul class="args"><li class="args">`func (Callable)`: a function that adds tasks to a flow     </li><li class="args">`*args`: task arguments to map over     </li><li class="args">`flow (Flow, optional)`: The flow to use, defaults to the current flow         in context if no flow is specified. If specified, `func` must accept         a `flow` keyword argument.     </li><li class="args">`**kwargs`: keyword task arguments to map over</li></ul> **Returns**:     <ul class="args"><li class="args">`Any`: the output of `func`, if any</li></ul> **Example**:<br><br><br><pre class="language-python"><code class="language-python"><span class="token keyword">from</span> prefect <span class="token keyword">import</span> task<span class="token punctuation">,</span> case<span class="token punctuation">,</span> apply_map<br><span class="token keyword">from</span> prefect.tasks.control_flow <span class="token keyword">import</span> merge<br><br><span class="token decorator">@task</span><br><span class="token keyword">def</span> <span class="token function">inc</span><span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">return</span> x <span class="token operator">+</span> <span class="token number">1</span><br><br><span class="token decorator">@task</span><br><span class="token keyword">def</span> <span class="token function">is_even</span><span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">return</span> x <span class="token operator">%</span> <span class="token number">2</span> <span class="token operator">==</span> <span class="token number">0</span><br><br><span class="token keyword">def</span> <span class="token function">inc_if_even</span><span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">:</span><br>    <span class="token keyword">with</span> case<span class="token punctuation">(</span>is_even<span class="token punctuation">(</span>x<span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token keyword">True</span><span class="token punctuation">)</span><span class="token punctuation">:</span><br>        x2 <span class="token operator">=</span> inc<span class="token punctuation">(</span>x<span class="token punctuation">)</span><br>    <span class="token keyword">return</span> merge<span class="token punctuation">(</span>x<span class="token punctuation">,</span> x2<span class="token punctuation">)</span><br><br><span class="token keyword">with</span> Flow<span class="token punctuation">(</span><span class="token string">"</span><span class="token string">example</span><span class="token string">"</span><span class="token punctuation">)</span> <span class="token keyword">as</span> flow<span class="token punctuation">:</span><br>    apply_map<span class="token punctuation">(</span>inc_if_even<span class="token punctuation">,</span> <span class="token builtin">range</span><span class="token punctuation">(</span><span class="token number">10</span><span class="token punctuation">)</span><span class="token punctuation">)</span><br></code></pre><br></p>|

<p class="auto-gen">This documentation was auto-generated from commit <a href='https://github.com/PrefectHQ/prefect/commit/n/a'>n/a</a> </br>on February 23, 2022 at 19:26 UTC</p>