File: //usr/share/doc/python3-django-q/html/tasks.html
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tasks — Django Q2 1.6.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=86f27845" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<script src="_static/jquery.js?v=8dae8fb0"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=d6a008b6"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Groups" href="group.html" />
<link rel="prev" title="Brokers" href="brokers.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
Django Q2
</a>
<div class="version">
1.6
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html"> Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="configure.html"> Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="brokers.html"> Brokers</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#"> Tasks</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#async-task">async_task()</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#hook">hook</a></li>
<li class="toctree-l3"><a class="reference internal" href="#group">group</a></li>
<li class="toctree-l3"><a class="reference internal" href="#save">save</a></li>
<li class="toctree-l3"><a class="reference internal" href="#timeout">timeout</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ack-failure">ack_failure</a></li>
<li class="toctree-l3"><a class="reference internal" href="#sync">sync</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cached">cached</a></li>
<li class="toctree-l3"><a class="reference internal" href="#broker">broker</a></li>
<li class="toctree-l3"><a class="reference internal" href="#task-name">task_name</a></li>
<li class="toctree-l3"><a class="reference internal" href="#q-options">q_options</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#asynctask">AsyncTask</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cached-operations">Cached operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="#synchronous-testing">Synchronous testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#connection-pooling">Connection pooling</a></li>
<li class="toctree-l2"><a class="reference internal" href="#reference">Reference</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#django_q.async_task"><code class="docutils literal notranslate"><span class="pre">async_task()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.result"><code class="docutils literal notranslate"><span class="pre">result()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.fetch"><code class="docutils literal notranslate"><span class="pre">fetch()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.queue_size"><code class="docutils literal notranslate"><span class="pre">queue_size()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.delete_cached"><code class="docutils literal notranslate"><span class="pre">delete_cached()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.Task"><code class="docutils literal notranslate"><span class="pre">Task</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.id"><code class="docutils literal notranslate"><span class="pre">Task.id</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.name"><code class="docutils literal notranslate"><span class="pre">Task.name</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.func"><code class="docutils literal notranslate"><span class="pre">Task.func</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.hook"><code class="docutils literal notranslate"><span class="pre">Task.hook</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.args"><code class="docutils literal notranslate"><span class="pre">Task.args</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.kwargs"><code class="docutils literal notranslate"><span class="pre">Task.kwargs</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.result"><code class="docutils literal notranslate"><span class="pre">Task.result</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.started"><code class="docutils literal notranslate"><span class="pre">Task.started</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.stopped"><code class="docutils literal notranslate"><span class="pre">Task.stopped</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.success"><code class="docutils literal notranslate"><span class="pre">Task.success</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.time_taken"><code class="docutils literal notranslate"><span class="pre">Task.time_taken()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.group_result"><code class="docutils literal notranslate"><span class="pre">Task.group_result()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.group_count"><code class="docutils literal notranslate"><span class="pre">Task.group_count()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.group_delete"><code class="docutils literal notranslate"><span class="pre">Task.group_delete()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.get_result"><code class="docutils literal notranslate"><span class="pre">Task.get_result()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.get_result_group"><code class="docutils literal notranslate"><span class="pre">Task.get_result_group()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.get_task"><code class="docutils literal notranslate"><span class="pre">Task.get_task()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.get_task_group"><code class="docutils literal notranslate"><span class="pre">Task.get_task_group()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.get_group_count"><code class="docutils literal notranslate"><span class="pre">Task.get_group_count()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.Task.delete_group"><code class="docutils literal notranslate"><span class="pre">Task.delete_group()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.Success"><code class="docutils literal notranslate"><span class="pre">Success</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.Failure"><code class="docutils literal notranslate"><span class="pre">Failure</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#django_q.AsyncTask"><code class="docutils literal notranslate"><span class="pre">AsyncTask</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.id"><code class="docutils literal notranslate"><span class="pre">AsyncTask.id</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.started"><code class="docutils literal notranslate"><span class="pre">AsyncTask.started</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.func"><code class="docutils literal notranslate"><span class="pre">AsyncTask.func</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.args"><code class="docutils literal notranslate"><span class="pre">AsyncTask.args</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.kwargs"><code class="docutils literal notranslate"><span class="pre">AsyncTask.kwargs</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.broker"><code class="docutils literal notranslate"><span class="pre">AsyncTask.broker</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.sync"><code class="docutils literal notranslate"><span class="pre">AsyncTask.sync</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.save"><code class="docutils literal notranslate"><span class="pre">AsyncTask.save</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.hook"><code class="docutils literal notranslate"><span class="pre">AsyncTask.hook</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.group"><code class="docutils literal notranslate"><span class="pre">AsyncTask.group</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.cached"><code class="docutils literal notranslate"><span class="pre">AsyncTask.cached</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.run"><code class="docutils literal notranslate"><span class="pre">AsyncTask.run()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.result"><code class="docutils literal notranslate"><span class="pre">AsyncTask.result()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.fetch"><code class="docutils literal notranslate"><span class="pre">AsyncTask.fetch()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.result_group"><code class="docutils literal notranslate"><span class="pre">AsyncTask.result_group()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#django_q.AsyncTask.fetch_group"><code class="docutils literal notranslate"><span class="pre">AsyncTask.fetch_group()</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="group.html"> Groups</a></li>
<li class="toctree-l1"><a class="reference internal" href="iterable.html"> Iterable</a></li>
<li class="toctree-l1"><a class="reference internal" href="chain.html"> Chains</a></li>
<li class="toctree-l1"><a class="reference internal" href="schedules.html"> Schedules</a></li>
<li class="toctree-l1"><a class="reference internal" href="cluster.html"> Cluster</a></li>
<li class="toctree-l1"><a class="reference internal" href="monitor.html"> Monitor</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin.html"> Admin</a></li>
<li class="toctree-l1"><a class="reference internal" href="errors.html"> Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="signals.html"> Signals</a></li>
<li class="toctree-l1"><a class="reference internal" href="architecture.html"> Architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html"> Examples</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Django Q2</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Tasks</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/tasks.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="tasks">
<h1>Tasks<a class="headerlink" href="#tasks" title="Link to this heading"></a></h1>
<section id="async-task">
<span id="async"></span><h2>async_task()<a class="headerlink" href="#async-task" title="Link to this heading"></a></h2>
<p>Use <a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> from your code to quickly offload tasks to the <a class="reference internal" href="cluster.html#django_q.Cluster" title="django_q.Cluster"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cluster</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">async_task</span><span class="p">,</span> <span class="n">result</span>
<span class="c1"># create the task</span>
<span class="n">async_task</span><span class="p">(</span><span class="s1">'math.copysign'</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">)</span>
<span class="c1"># or with import and storing the id</span>
<span class="kn">import</span> <span class="nn">math.copysign</span>
<span class="n">task_id</span> <span class="o">=</span> <span class="n">async_task</span><span class="p">(</span><span class="n">copysign</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">)</span>
<span class="c1"># get the result</span>
<span class="n">task_result</span> <span class="o">=</span> <span class="n">result</span><span class="p">(</span><span class="n">task_id</span><span class="p">)</span>
<span class="c1"># result returns None if the task has not been executed yet</span>
<span class="c1"># you can wait for it</span>
<span class="n">task_result</span> <span class="o">=</span> <span class="n">result</span><span class="p">(</span><span class="n">task_id</span><span class="p">,</span> <span class="mi">200</span><span class="p">)</span>
<span class="c1"># but in most cases you will want to use a hook:</span>
<span class="n">async_task</span><span class="p">(</span><span class="s1">'math.modf'</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="n">hook</span><span class="o">=</span><span class="s1">'hooks.print_result'</span><span class="p">)</span>
<span class="c1"># hooks.py</span>
<span class="k">def</span> <span class="nf">print_result</span><span class="p">(</span><span class="n">task</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">task</span><span class="o">.</span><span class="n">result</span><span class="p">)</span>
</pre></div>
</div>
<p><a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> can take the following optional keyword arguments:</p>
<section id="hook">
<h3>hook<a class="headerlink" href="#hook" title="Link to this heading"></a></h3>
<p>The function to call after the task has been executed. This function gets passed the complete <a class="reference internal" href="#django_q.Task" title="django_q.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> object as its argument.</p>
</section>
<section id="group">
<h3>group<a class="headerlink" href="#group" title="Link to this heading"></a></h3>
<p>A group label. Check <a class="reference internal" href="group.html"><span class="doc">Groups</span></a> for group functions.</p>
</section>
<section id="save">
<h3>save<a class="headerlink" href="#save" title="Link to this heading"></a></h3>
<p>Overrides the result backend’s save setting for this task.</p>
</section>
<section id="timeout">
<h3>timeout<a class="headerlink" href="#timeout" title="Link to this heading"></a></h3>
<p>Overrides the cluster’s timeout setting for this task.</p>
<p>See <a class="reference internal" href="configure.html#retry"><span class="std std-ref">retry</span></a> for details how to set values for timeout.</p>
</section>
<section id="ack-failure">
<h3>ack_failure<a class="headerlink" href="#ack-failure" title="Link to this heading"></a></h3>
<p>Overrides the cluster’s <a class="reference internal" href="configure.html#ack-failures"><span class="std std-ref">ack_failures</span></a> setting for this task.</p>
</section>
<section id="sync">
<h3>sync<a class="headerlink" href="#sync" title="Link to this heading"></a></h3>
<p>Simulates a task execution synchronously. Useful for testing.
Can also be forced globally via the <a class="reference internal" href="configure.html#sync"><span class="std std-ref">sync</span></a> configuration option.</p>
</section>
<section id="cached">
<h3>cached<a class="headerlink" href="#cached" title="Link to this heading"></a></h3>
<p>Redirects the result to the cache backend instead of the database if set to <code class="docutils literal notranslate"><span class="pre">True</span></code> or to an integer indicating the cache timeout in seconds.
e.g. <code class="docutils literal notranslate"><span class="pre">cached=60</span></code>. Especially useful with large and group operations where you don’t need the all results in your
database and want to take advantage of the speed of your cache backend.</p>
</section>
<section id="broker">
<h3>broker<a class="headerlink" href="#broker" title="Link to this heading"></a></h3>
<p>A broker instance, in case you want to control your own connections.</p>
</section>
<section id="task-name">
<h3>task_name<a class="headerlink" href="#task-name" title="Link to this heading"></a></h3>
<p>Optionally overwrites the auto-generated task name.</p>
</section>
<section id="q-options">
<h3>q_options<a class="headerlink" href="#q-options" title="Link to this heading"></a></h3>
<p>None of the option keywords get passed on to the task function.
As an alternative you can also put them in
a single keyword dict named <code class="docutils literal notranslate"><span class="pre">q_options</span></code>. This enables you to use these keywords for your function call:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Async options in a dict</span>
<span class="n">opts</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'hook'</span><span class="p">:</span> <span class="s1">'hooks.print_result'</span><span class="p">,</span>
<span class="s1">'group'</span><span class="p">:</span> <span class="s1">'math'</span><span class="p">,</span>
<span class="s1">'timeout'</span><span class="p">:</span> <span class="mi">30</span><span class="p">}</span>
<span class="n">async_task</span><span class="p">(</span><span class="s1">'math.modf'</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="n">q_options</span><span class="o">=</span><span class="n">opts</span><span class="p">)</span>
</pre></div>
</div>
<p>Please note that this will override any other option keywords.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For tasks to be processed you will need to have a worker cluster running in the background using <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">manage.py</span> <span class="pre">qcluster</span></code>
or you need to configure Django Q2 to run in synchronous mode for testing using the <a class="reference internal" href="configure.html#sync"><span class="std std-ref">sync</span></a> option.</p>
</div>
</section>
</section>
<section id="asynctask">
<h2>AsyncTask<a class="headerlink" href="#asynctask" title="Link to this heading"></a></h2>
<p>Optionally you can use the <a class="reference internal" href="#django_q.AsyncTask" title="django_q.AsyncTask"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncTask</span></code></a> class to instantiate a task and keep everything in a single object.:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># AsyncTask class instance example</span>
<span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">AsyncTask</span>
<span class="c1"># instantiate an async task</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">AsyncTask</span><span class="p">(</span><span class="s1">'math.floor'</span><span class="p">,</span> <span class="mf">1.5</span><span class="p">,</span> <span class="n">group</span><span class="o">=</span><span class="s1">'math'</span><span class="p">)</span>
<span class="c1"># you can set or change keywords afterwards</span>
<span class="n">a</span><span class="o">.</span><span class="n">cached</span> <span class="o">=</span> <span class="kc">True</span>
<span class="c1"># run it</span>
<span class="n">a</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
<span class="c1"># wait indefinitely for the result and print it</span>
<span class="c1"># don't let the task return `None` or it will wait indefinitely</span>
<span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">result</span><span class="p">(</span><span class="n">wait</span><span class="o">=-</span><span class="mi">1</span><span class="p">))</span>
<span class="c1"># change the args</span>
<span class="n">a</span><span class="o">.</span><span class="n">args</span> <span class="o">=</span> <span class="p">(</span><span class="mf">2.5</span><span class="p">,)</span>
<span class="c1"># run it again</span>
<span class="n">a</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
<span class="c1"># wait max 10 seconds for the result and print it</span>
<span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">result</span><span class="p">(</span><span class="n">wait</span><span class="o">=</span><span class="mi">10</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="mi">1</span>
<span class="mi">2</span>
</pre></div>
</div>
<p>Once you change any of the parameters of the task after it has run, the result is invalidated and you will have to <a class="reference internal" href="#django_q.AsyncTask.run" title="django_q.AsyncTask.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">AsyncTask.run()</span></code></a> it again to retrieve a new result.</p>
</section>
<section id="cached-operations">
<h2>Cached operations<a class="headerlink" href="#cached-operations" title="Link to this heading"></a></h2>
<p>You can run your tasks results against the Django cache backend instead of the database backend by either using the global <a class="reference internal" href="configure.html#cached"><span class="std std-ref">cached</span></a> setting or by supplying the <code class="docutils literal notranslate"><span class="pre">cached</span></code> keyword to individual functions.
This can be useful if you are not interested in persistent results or if you run large group tasks where you only want the final result.
By using a cache backend like Redis or Memcached you can speed up access to your task results significantly compared to a relational database.</p>
<p>When you set <code class="docutils literal notranslate"><span class="pre">cached=True</span></code>, results will be saved permanently in the cache and you will have to rely on your backend’s cleanup strategies (like LRU) to
manage stale results.
You can also opt to set a manual timeout on the results, by setting e.g. <code class="docutils literal notranslate"><span class="pre">cached=60</span></code>. Meaning the result will be evicted from the cache after 60 seconds.
This works both globally or on individual async executions.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># simple cached example</span>
<span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">async_task</span><span class="p">,</span> <span class="n">result</span>
<span class="c1"># cache the result for 10 seconds</span>
<span class="nb">id</span> <span class="o">=</span> <span class="n">async_task</span><span class="p">(</span><span class="s1">'math.floor'</span><span class="p">,</span> <span class="mi">100</span><span class="p">,</span> <span class="n">cached</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># wait max 50ms for the result to appear in the cache</span>
<span class="n">result</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="n">wait</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span> <span class="n">cached</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># or fetch the task object</span>
<span class="n">task</span> <span class="o">=</span> <span class="n">fetch</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="n">cached</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># and then save it to the database</span>
<span class="n">task</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</div>
<p>As you can see you can easily turn a cached result into a permanent database result by calling <code class="docutils literal notranslate"><span class="pre">save()</span></code> on it.</p>
<p>This also works for group actions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># cached group example</span>
<span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">async_task</span><span class="p">,</span> <span class="n">result_group</span>
<span class="kn">from</span> <span class="nn">django_q.brokers</span> <span class="kn">import</span> <span class="n">get_broker</span>
<span class="c1"># set up a broker instance for better performance</span>
<span class="n">broker</span> <span class="o">=</span> <span class="n">get_broker</span><span class="p">()</span>
<span class="c1"># Async a hundred functions under a group label</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">100</span><span class="p">):</span>
<span class="n">async_task</span><span class="p">(</span><span class="s1">'math.frexp'</span><span class="p">,</span>
<span class="n">i</span><span class="p">,</span>
<span class="n">group</span><span class="o">=</span><span class="s1">'frexp'</span><span class="p">,</span>
<span class="n">cached</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
<span class="n">broker</span><span class="o">=</span><span class="n">broker</span><span class="p">)</span>
<span class="c1"># wait max 50ms for one hundred results to return</span>
<span class="n">result_group</span><span class="p">(</span><span class="s1">'frexp'</span><span class="p">,</span> <span class="n">wait</span><span class="o">=</span><span class="mi">50</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">cached</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>If you don’t need hooks, that exact same result can be achieved by using the more convenient <a class="reference internal" href="iterable.html#django_q.async_iter" title="django_q.async_iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_iter()</span></code></a>.</p>
</section>
<section id="synchronous-testing">
<h2>Synchronous testing<a class="headerlink" href="#synchronous-testing" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> can be instructed to execute a task immediately by setting the optional keyword <code class="docutils literal notranslate"><span class="pre">sync=True</span></code>.
The task will then be injected straight into a worker and the result saved by a monitor instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">async_task</span><span class="p">,</span> <span class="n">fetch</span>
<span class="c1"># create a synchronous task</span>
<span class="n">task_id</span> <span class="o">=</span> <span class="n">async_task</span><span class="p">(</span><span class="s1">'my.buggy.code'</span><span class="p">,</span> <span class="n">sync</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># the task will then be available immediately</span>
<span class="n">task</span> <span class="o">=</span> <span class="n">fetch</span><span class="p">(</span><span class="n">task_id</span><span class="p">)</span>
<span class="c1"># and can be examined</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">task</span><span class="o">.</span><span class="n">success</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'An error occurred: </span><span class="si">{}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">task</span><span class="o">.</span><span class="n">result</span><span class="p">))</span>
</pre></div>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>An<span class="w"> </span>error<span class="w"> </span>occurred:<span class="w"> </span>ImportError<span class="o">(</span><span class="s2">"No module named 'my'"</span>,<span class="o">)</span>
</pre></div>
</div>
<p>Note that <a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> will block until the task is executed and saved. This feature bypasses the broker and is intended for debugging and development.
Instead of setting <code class="docutils literal notranslate"><span class="pre">sync</span></code> on each individual <code class="docutils literal notranslate"><span class="pre">async_task</span></code> you can also configure <a class="reference internal" href="configure.html#sync"><span class="std std-ref">sync</span></a> as a global override.</p>
</section>
<section id="connection-pooling">
<h2>Connection pooling<a class="headerlink" href="#connection-pooling" title="Link to this heading"></a></h2>
<p>Django Q2 tries to pass broker instances around its parts as much as possible to save you from running out of connections.
When you are making individual calls to <a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> a lot though, it can help to set up a broker to reuse for <a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># broker connection economy example</span>
<span class="kn">from</span> <span class="nn">django_q.tasks</span> <span class="kn">import</span> <span class="n">async_task</span>
<span class="kn">from</span> <span class="nn">django_q.brokers</span> <span class="kn">import</span> <span class="n">get_broker</span>
<span class="n">broker</span> <span class="o">=</span> <span class="n">get_broker</span><span class="p">()</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">50</span><span class="p">):</span>
<span class="n">async_task</span><span class="p">(</span><span class="s1">'math.modf'</span><span class="p">,</span> <span class="mf">2.5</span><span class="p">,</span> <span class="n">broker</span><span class="o">=</span><span class="n">broker</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>If you are using <a class="reference external" href="https://github.com/niwinz/django-redis">django-redis</a> and the redis broker, you can <a class="reference internal" href="configure.html#django-redis"><span class="std std-ref">configure</span></a> Django Q2 to use its connection pool.</p>
</div>
</section>
<section id="reference">
<h2>Reference<a class="headerlink" href="#reference" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="django_q.async_task">
<span class="sig-name descname"><span class="pre">async_task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hook</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">group</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">save</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sync</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cached</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">broker</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">q_options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.async_task" title="Link to this definition"></a></dt>
<dd><blockquote>
<div><p>Puts a task in the cluster queue</p>
</div></blockquote>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>func</strong> (<em>object</em>) – The task function to execute</p></li>
<li><p><strong>args</strong> (<em>tuple</em>) – The arguments for the task function</p></li>
<li><p><strong>hook</strong> (<em>object</em>) – Optional function to call after execution</p></li>
<li><p><strong>group</strong> (<em>str</em>) – An optional group identifier</p></li>
<li><p><strong>timeout</strong> (<em>int</em>) – Overrides global cluster <a class="reference internal" href="configure.html#timeout"><span class="std std-ref">timeout</span></a>.</p></li>
<li><p><strong>save</strong> (<em>bool</em>) – Overrides global save setting for this task.</p></li>
<li><p><strong>ack_failure</strong> (<em>bool</em>) – Overrides the global <a class="reference internal" href="configure.html#ack-failures"><span class="std std-ref">ack_failures</span></a> setting for this task.</p></li>
<li><p><strong>sync</strong> (<em>bool</em>) – If set to True, async_task will simulate a task execution</p></li>
<li><p><strong>cached</strong> – Output the result to the cache backend. Bool or timeout in seconds</p></li>
<li><p><strong>broker</strong> – Optional broker connection from <a class="reference internal" href="brokers.html#brokers.get_broker" title="brokers.get_broker"><code class="xref py py-func docutils literal notranslate"><span class="pre">brokers.get_broker()</span></code></a></p></li>
<li><p><strong>q_options</strong> (<em>dict</em>) – Options dict, overrides option keywords</p></li>
<li><p><strong>kwargs</strong> (<em>dict</em>) – Keyword arguments for the task function</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The uuid of the task</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="django_q.result">
<span class="sig-name descname"><span class="pre">result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">task_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cached</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.result" title="Link to this definition"></a></dt>
<dd><p>Gets the result of a previously executed task</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>task_id</strong> (<em>str</em>) – the uuid or name of the task</p></li>
<li><p><strong>wait</strong> (<em>int</em>) – optional milliseconds to wait for a result. -1 for indefinite, but be sure the result will not be <cite>None</cite> otherwise it will wait indefinitely!</p></li>
<li><p><strong>cached</strong> (<em>bool</em>) – run this against the cache backend.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The result of the executed task</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="django_q.fetch">
<span class="sig-name descname"><span class="pre">fetch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">task_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cached</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.fetch" title="Link to this definition"></a></dt>
<dd><p>Returns a previously executed task</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>task_id</strong> (<em>str</em>) – the uuid or name of the task</p></li>
<li><p><strong>wait</strong> (<em>int</em>) – optional milliseconds to wait for a result. -1 for indefinite</p></li>
<li><p><strong>cached</strong> (<em>bool</em>) – run this against the cache backend.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A task object</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#django_q.Task" title="django_q.Task">Task</a></p>
</dd>
</dl>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.2.0.</span></p>
</div>
<p>Renamed from get_task</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="django_q.queue_size">
<span class="sig-name descname"><span class="pre">queue_size</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#django_q.queue_size" title="Link to this definition"></a></dt>
<dd><p>Returns the size of the broker queue.
Note that this does not count tasks currently being processed.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>The amount of task packages in the broker</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>int</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="django_q.delete_cached">
<span class="sig-name descname"><span class="pre">delete_cached</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">task_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">broker</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.delete_cached" title="Link to this definition"></a></dt>
<dd><p>Deletes a task from the cache backend</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>task_id</strong> (<em>str</em>) – the uuid of the task</p></li>
<li><p><strong>broker</strong> – an optional broker instance</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="django_q.Task">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Task</span></span><a class="headerlink" href="#django_q.Task" title="Link to this definition"></a></dt>
<dd><p>Database model describing an executed task</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.id">
<span class="sig-name descname"><span class="pre">id</span></span><a class="headerlink" href="#django_q.Task.id" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>An <code class="xref py py-func docutils literal notranslate"><span class="pre">uuid.uuid4()</span></code> identifier</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.name">
<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#django_q.Task.name" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The name of the task as a humanized version of the <a class="reference internal" href="#django_q.Task.id" title="django_q.Task.id"><code class="xref py py-attr docutils literal notranslate"><span class="pre">id</span></code></a></p>
<blockquote>
<div><div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is for convenience and can be used as a parameter for most functions that take a <cite>task_id</cite>.
Keep in mind that it is not guaranteed to be unique if you store very large amounts of tasks in the database.</p>
</div>
</div></blockquote>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.func">
<span class="sig-name descname"><span class="pre">func</span></span><a class="headerlink" href="#django_q.Task.func" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The function or reference that was executed</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.hook">
<span class="sig-name descname"><span class="pre">hook</span></span><a class="headerlink" href="#django_q.Task.hook" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The function to call after execution.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.args">
<span class="sig-name descname"><span class="pre">args</span></span><a class="headerlink" href="#django_q.Task.args" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Positional arguments for the function.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.kwargs">
<span class="sig-name descname"><span class="pre">kwargs</span></span><a class="headerlink" href="#django_q.Task.kwargs" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Keyword arguments for the function.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.result">
<span class="sig-name descname"><span class="pre">result</span></span><a class="headerlink" href="#django_q.Task.result" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The result object. Contains the error if any occur.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.started">
<span class="sig-name descname"><span class="pre">started</span></span><a class="headerlink" href="#django_q.Task.started" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The moment the task was created by an async command</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.stopped">
<span class="sig-name descname"><span class="pre">stopped</span></span><a class="headerlink" href="#django_q.Task.stopped" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The moment a worker finished this task</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.Task.success">
<span class="sig-name descname"><span class="pre">success</span></span><a class="headerlink" href="#django_q.Task.success" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Was the task executed without problems?</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.time_taken">
<span class="sig-name descname"><span class="pre">time_taken</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.time_taken" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Calculates the difference in seconds between started and stopped.</p>
<blockquote>
<div><div class="admonition note">
<p class="admonition-title">Note</p>
<p>Time taken represents the time a task spends in the cluster, this includes any time it may have waited in the queue.</p>
</div>
</div></blockquote>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.group_result">
<span class="sig-name descname"><span class="pre">group_result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.group_result" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a list of results from this task’s group.
Set failures to <code class="docutils literal notranslate"><span class="pre">True</span></code> to include failed results.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.group_count">
<span class="sig-name descname"><span class="pre">group_count</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.group_count" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a count of the number of task results in this task’s group.
Returns the number of failures when <code class="docutils literal notranslate"><span class="pre">failures=True</span></code></p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.group_delete">
<span class="sig-name descname"><span class="pre">group_delete</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tasks</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.group_delete" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Resets the group label on all the tasks in this task’s group.
If <code class="docutils literal notranslate"><span class="pre">tasks=True</span></code> it will also delete the tasks in this group from the database, including itself.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.get_result">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">task_id</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.get_result" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Gets a result directly by task uuid or name.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.get_result_group">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_result_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">group_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.get_result_group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a list of results from a task group.
Set failures to <code class="docutils literal notranslate"><span class="pre">True</span></code> to include failed results.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.get_task">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">task_id</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.get_task" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Fetches a single task object by uuid or name.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.get_task_group">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_task_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">group_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.get_task_group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Gets a queryset of tasks with this group id.
Set failures to <code class="docutils literal notranslate"><span class="pre">False</span></code> to exclude failed tasks.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.get_group_count">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_group_count</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">group_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.get_group_count" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a count of the number of tasks results in a group.
Returns the number of failures when <code class="docutils literal notranslate"><span class="pre">failures=True</span></code></p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.Task.delete_group">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">delete_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">group_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">objects</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.Task.delete_group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Deletes a group label only, by default.
If <code class="docutils literal notranslate"><span class="pre">objects=True</span></code> it will also delete the tasks in this group from the database.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="django_q.Success">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Success</span></span><a class="headerlink" href="#django_q.Success" title="Link to this definition"></a></dt>
<dd><p>A proxy model of <a class="reference internal" href="#django_q.Task" title="django_q.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> with the queryset filtered on <a class="reference internal" href="#django_q.Task.success" title="django_q.Task.success"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Task.success</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="django_q.Failure">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Failure</span></span><a class="headerlink" href="#django_q.Failure" title="Link to this definition"></a></dt>
<dd><p>A proxy model of <a class="reference internal" href="#django_q.Task" title="django_q.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> with the queryset filtered on <a class="reference internal" href="#django_q.Task.success" title="django_q.Task.success"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Task.success</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="django_q.AsyncTask">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">AsyncTask</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask" title="Link to this definition"></a></dt>
<dd><p>A class wrapper for the <a class="reference internal" href="#django_q.async_task" title="django_q.async_task"><code class="xref py py-func docutils literal notranslate"><span class="pre">async_task()</span></code></a> function.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>func</strong> (<em>object</em>) – The task function to execute</p></li>
<li><p><strong>args</strong> (<em>tuple</em>) – The arguments for the task function</p></li>
<li><p><strong>kwargs</strong> (<em>dict</em>) – Keyword arguments for the task function, including async_task options</p></li>
</ul>
</dd>
</dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.id">
<span class="sig-name descname"><span class="pre">id</span></span><a class="headerlink" href="#django_q.AsyncTask.id" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The task unique identifier. This will only be available after it has been <a class="reference internal" href="#django_q.AsyncTask.run" title="django_q.AsyncTask.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a></p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.started">
<span class="sig-name descname"><span class="pre">started</span></span><a class="headerlink" href="#django_q.AsyncTask.started" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Bool indicating if the task has been run with the current parameters</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.func">
<span class="sig-name descname"><span class="pre">func</span></span><a class="headerlink" href="#django_q.AsyncTask.func" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>The task function to execute</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.args">
<span class="sig-name descname"><span class="pre">args</span></span><a class="headerlink" href="#django_q.AsyncTask.args" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>A tuple of arguments for the task function</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.kwargs">
<span class="sig-name descname"><span class="pre">kwargs</span></span><a class="headerlink" href="#django_q.AsyncTask.kwargs" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Keyword arguments for the function. Can include any of the optional async_task keyword attributes directly or in a <cite>q_options</cite> dictionary.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.broker">
<span class="sig-name descname"><span class="pre">broker</span></span><a class="headerlink" href="#django_q.AsyncTask.broker" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Optional <a class="reference internal" href="brokers.html#Broker" title="Broker"><code class="xref py py-class docutils literal notranslate"><span class="pre">Broker</span></code></a> instance to use</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.sync">
<span class="sig-name descname"><span class="pre">sync</span></span><a class="headerlink" href="#django_q.AsyncTask.sync" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Run this task inline instead of asynchronous.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.save">
<span class="sig-name descname"><span class="pre">save</span></span><a class="headerlink" href="#django_q.AsyncTask.save" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Overrides the global save setting.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.hook">
<span class="sig-name descname"><span class="pre">hook</span></span><a class="headerlink" href="#django_q.AsyncTask.hook" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Optional function to call after a result is available. Takes the result <a class="reference internal" href="#django_q.Task" title="django_q.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> as the first argument.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.group">
<span class="sig-name descname"><span class="pre">group</span></span><a class="headerlink" href="#django_q.AsyncTask.group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Optional group identifier</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="django_q.AsyncTask.cached">
<span class="sig-name descname"><span class="pre">cached</span></span><a class="headerlink" href="#django_q.AsyncTask.cached" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Run the task against the cache result backend.</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.AsyncTask.run">
<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask.run" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Send the task to a worker cluster for execution</p>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.AsyncTask.result">
<span class="sig-name descname"><span class="pre">result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask.result" title="Link to this definition"></a></dt>
<dd><p>The task result. Always returns None if the task hasn’t been run with the current parameters.</p>
<blockquote>
<div><dl class="field-list simple">
<dt class="field-odd">param int wait<span class="colon">:</span></dt>
<dd class="field-odd"><p>the number of milliseconds to wait for a result. -1 for indefinite</p>
</dd>
</dl>
</div></blockquote>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.AsyncTask.fetch">
<span class="sig-name descname"><span class="pre">fetch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask.fetch" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns the full <a class="reference internal" href="#django_q.Task" title="django_q.Task"><code class="xref py py-class docutils literal notranslate"><span class="pre">Task</span></code></a> result instance.</p>
<blockquote>
<div><dl class="field-list simple">
<dt class="field-odd">param int wait<span class="colon">:</span></dt>
<dd class="field-odd"><p>the number of milliseconds to wait for a result. -1 for indefinite</p>
</dd>
</dl>
</div></blockquote>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.AsyncTask.result_group">
<span class="sig-name descname"><span class="pre">result_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">count</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask.result_group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a list of results from this task’s group.</p>
<blockquote>
<div><dl class="field-list simple">
<dt class="field-odd">param bool failures<span class="colon">:</span></dt>
<dd class="field-odd"><p>set this to <code class="docutils literal notranslate"><span class="pre">True</span></code> to include failed results</p>
</dd>
<dt class="field-even">param int wait<span class="colon">:</span></dt>
<dd class="field-even"><p>optional milliseconds to wait for a result or count. -1 for indefinite</p>
</dd>
<dt class="field-odd">param int count<span class="colon">:</span></dt>
<dd class="field-odd"><p>block until there are this many results in the group</p>
</dd>
</dl>
</div></blockquote>
<dl class="py method">
<dt class="sig sig-object py" id="django_q.AsyncTask.fetch_group">
<span class="sig-name descname"><span class="pre">fetch_group</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failures</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wait</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">count</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#django_q.AsyncTask.fetch_group" title="Link to this definition"></a></dt>
<dd></dd></dl>
<p>Returns a list of task results from this task’s group</p>
<blockquote>
<div><dl class="field-list simple">
<dt class="field-odd">param bool failures<span class="colon">:</span></dt>
<dd class="field-odd"><p>set this to <code class="docutils literal notranslate"><span class="pre">False</span></code> to exclude failed tasks</p>
</dd>
<dt class="field-even">param int wait<span class="colon">:</span></dt>
<dd class="field-even"><p>optional milliseconds to wait for a task or count. -1 for indefinite</p>
</dd>
<dt class="field-odd">param int count<span class="colon">:</span></dt>
<dd class="field-odd"><p>block until there are this many tasks in the group</p>
</dd>
</dl>
</div></blockquote>
</dd></dl>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="brokers.html" class="btn btn-neutral float-left" title="Brokers" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="group.html" class="btn btn-neutral float-right" title="Groups" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2015-2023, Ilan Steemers - 2022, Stan Triepels.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>