.. _koji_directive:


koji_directive - download builds and tags from Koji
+++++++++++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 0.4

The koji directive interfaces with `Koji <http://koji.fedoraproject.org/>`_
to facilitate various Koji actions. You can either download all RPMs from
a specific build, or you can download all RPMs from all builds belonging
to a specific Koji tag.


Parameters
----------

.. raw:: html

    <table class="rawhtml" border=1 cellpadding=4>
    <tr>
    <th class="head">parameter</th>
    <th class="head">required</th>
    <th class="head">description</th>
    <th class="head">type</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    </tr>
            <tr>
    <td class="bold"><p>action</p></td>
    <td>yes</td>
    <td><p>choose whether to download a single build (<tt class="docutils literal">download</tt> value) or all builds belonging to a Koji tag (<tt class="docutils literal">download_tag</tt> value)</p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul><li><p>download</p></li><li><p>download_tag</p></li><li><p>download_latest_stable</p></li></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>arch</p></td>
    <td>yes</td>
    <td><p>a list of architectures for which to download RPMs for the requested
    build/tag. If you want to download RPMs for all arches, use <tt class="docutils literal">['all']</tt>.</p>
    <p>Note: <tt class="docutils literal">noarch</tt> RPMs are always automatically downloaded even when not
    requested, unless <tt class="docutils literal"><span class="pre">arch=[]</span></tt> and <tt class="docutils literal">src=True</tt>.</p></td>
    <td><p>list of str</p></td>
    <td></td>
    <td><ul><li><p>supported architectures</p></li><li><p>['all']</p></li></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>debuginfo</p></td>
    <td>no</td>
    <td><p>download also <tt class="docutils literal">debuginfo</tt> RPM files</p></td>
    <td><p>bool</p></td>
    <td><p>False</p></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>koji_build</p></td>
    <td>yes</td>
    <td><p>N(E)VR of a Koji build to download (for <tt class="docutils literal"><span class="pre">action=&quot;download&quot;</span></tt>) or to search
    the latest stable build for (for <tt class="docutils literal"><span class="pre">action=&quot;download_latest_stable&quot;</span></tt>). Not
    required for <tt class="docutils literal"><span class="pre">action=&quot;download_tag&quot;</span></tt>. Example: <tt class="docutils literal"><span class="pre">xchat-2.8.8-21.fc20</span></tt></p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>koji_tag</p></td>
    <td>yes</td>
    <td><p>name of a Koji tag to download all builds from. Only required when
    <tt class="docutils literal"><span class="pre">action=&quot;download_tag&quot;</span></tt>. Example: <tt class="docutils literal"><span class="pre">f20-updates-pending</span></tt></p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>src</p></td>
    <td>no</td>
    <td><p>download also <tt class="docutils literal">src</tt> RPM files</p></td>
    <td><p>bool</p></td>
    <td><p>False</p></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>target_dir</p></td>
    <td>no</td>
    <td><p>directory into which to download builds</p></td>
    <td><p>str</p></td>
    <td><p>${workdir}</p></td>
    <td><ul></ul></td>
    </tr>
        </table>

Return Values
-------------

A dictionary containing following items:

* `downloaded_rpms`: (list of str) a list of local filenames of the downloaded
  RPMs


Exceptions
----------

* :class:`.TaskotronRemoteError`: if downloading failed
* :class:`.TaskotronValueError`: if ``arch=[]`` and ``src=False``, therefore
  there is nothing to download



Examples
--------


Rpmlint needs to download a specific build from Koji, all architectures
including src.rpm::

  - name: download rpms from koji
    koji:
      action: download
      koji_build: ${koji_build}
      arch: ['all']
      src: True

Depcheck needs to download all builds in a specific Koji tag for the current
architecture::

  - name: download koji tag
    koji:
        action: download_tag
        koji_tag: ${koji_tag}
        arch: ${arch}
        target_dir: ${workdir}/downloaded_tag/

Abidiff needs to download the latest stable build of a package::

  - name: download rpms of the latest stable build of a given build from koji
    koji:
        action: download_latest_stable
        koji_build: ${koji_build}
        arch: ${arch}
        target_dir: ${workdir}/stable/