.. :usage:

=======
Install
=======

::

    pip install python-taiga


=====================
Getting Started
=====================

Getting started with the Taiga API couldn't be easier: create a ``TaigaAPI`` and you're ready to go.

.. note:: python-taiga is a python wrapper for the `Taiga REST API <http://taigaio.github.io/taiga-doc/dist/api.html>`_.
          Any data structure, argument and response matches exactly the Taiga REST API, so refer to it for any usage.


*********************
API Credentials
*********************

The ``TaigaAPI`` needs your Taiga credentials. You can pass these
directly to the auth method (see the code below).

.. code:: python

    from taiga import TaigaAPI

    api = TaigaAPI()

    api.auth(
        username='user',
        password='psw'
    )

Alternately, you can pass a token to the constructor ``TaigaAPI``
constructor.

.. code:: python

    from taiga import TaigaAPI

    api = TaigaAPI(token='mytoken')

You can also specify a different host if you use Taiga somewhere else

.. code:: python

    from taiga import TaigaAPI

    api = TaigaAPI(
        host='http://taiga.my.host.org'
    )

To use LDAP or other authentication backends, use ``auth_type`` argument

.. code:: python

    from taiga import TaigaAPI

    api = TaigaAPI(
        host='http://taiga.my.host.org',
        auth_type='ldap'
    )

To ignore SSL certificate verification (use at your own risk!) use ``tls_verify`` argument

.. code:: python

    from taiga import TaigaAPI

    api = TaigaAPI(
        host='http://taiga.my.host.org',
        tls_verify=False
    )

******************************************************
Get projects, user stories, task and issues
******************************************************

You can get projects, user stories, tasks and issues using the primary
key or using slug/ref

.. code:: python

    new_project = api.projects.get_by_slug('nephila')
    print (new_project.get_issue_by_ref(1036))
    print (new_project.get_userstory_by_ref(1111))
    print (new_project.get_task_by_ref(1112))

******************************************************
Create a project
******************************************************

.. code:: python

    new_project = api.projects.create('TEST PROJECT', 'TESTING API')

******************************************************
Duplicate an existing project
******************************************************

If you have a project, you can duplicate it (duplicates most of the settings,
but not the user stories or tasks)

.. code:: python

    old_project = api.projects.get_by_slug('nephila')
    new_project = old_project.duplicate('TEST PROJECT', 'TESTING API')

******************************************************
Create a new user story
******************************************************

.. code:: python

    userstory = new_project.add_user_story(
        'New Story', description='Blablablabla'
    )

You can also create a milestone and pass it to a story

.. code:: python

    jan_feb_milestone = new_project.add_milestone(
        'MILESTONE 1', '2015-01-26', '2015-02-26'
    )

    userstory = new_project.add_user_story(
        'New Story', description='Blablablabla',
        milestone=jan_feb_milestone.id
    )

To add a task to your user story just run

.. code:: python

    userstory.add_task(
        'New Task 2',
        new_project.task_statuses[0].id
    )

******************************************************
Create a swimlane
******************************************************

.. code:: python

    newlane = new_project.add_swimlane('New Swimlane')

******************************************************
Create an issue
******************************************************

.. code:: python

    newissue = new_project.add_issue(
        'New Issue',
        new_project.priorities.get(name='High').id,
        new_project.issue_statuses.get(name='New').id,
        new_project.issue_types.get(name='Bug').id,
        new_project.severities.get(name='Minor').id,
        description='Bug #5'
    )

******************************************************
Create a custom attribute
******************************************************

.. code:: python

    new_project.add_issue_attribute(
        'Device', description='(iPad, iPod, iPhone, Desktop, etc.)'
    )
    newissue.set_attribute('1', 'Desktop')

******************************************************
List elements
******************************************************

.. code:: python

    projects = api.projects.list()
    stories = api.user_stories.list()

You can also specify filters

.. code:: python

    tasks = api.tasks.list(project=1)

By default list returns all objects, eventually getting the
paginated results behind the scenes.

Pagination
===========

Pagination is controlled by three parameters as explained below:

+--------------------+------------------------------+---------------+--------------------------------------------------------+
|``pagination``      | ``page_size`` (default: 100) | ``page``      | Output                                                 |
+====================+==============================+===============+========================================================+
| ``True`` (default) | ``<integer>``                | ``None``      | All results retrieved by using paginated results and   |
|                    |                              |               | loading them behind the scenes, using given page       |
|                    |                              |               | size (higher page size could yield better performances)|
+--------------------+------------------------------+---------------+--------------------------------------------------------+
| ``True`` (default) | ``<integer>``                | ``<integer>`` | Only results for the given page of the given size      |
|                    |                              |               | are retrieved                                          |
+--------------------+------------------------------+---------------+--------------------------------------------------------+
| ``False``          | ``unused``                   | ``unused``    | Current behavior: all results, ignoring pagination     |
+--------------------+------------------------------+---------------+--------------------------------------------------------+


.. note:: non numerical or false `page_size` values is casted to the default value

Examples
===========

**No pagination**

.. code:: python

   tasks = api.tasks.list(paginate=False)

.. warning:: be aware that the unpaginated results may exceed
             the data the parser can handle and may result in an error.

**Retrieve a single page**

.. code:: python

   tasks_page_1 = api.tasks.list(page=1)  # Will only return page 1

**Specify the page size**

.. code:: python

   tasks_page_1 = api.tasks.list(page=1, page_size=200)  # Will 200 results from page 1


******************************************************
Attach a file
******************************************************

You can attach files to issues, user stories and tasks

.. code:: python

    newissue.attach('README.md', description='Read the README in Issue')

******************************************************
Play with instances
******************************************************

Instances can have actions, for example you can star a project just
calling

.. code:: python

    new_project = api.projects.create('TEST PROJECT', 'TESTING API')
    new_project.star()

Any instance can be updated and deleted

.. code:: python

    new_project.name = 'New name for my project'
    new_project.update()
    new_project.delete()

******************************************************
Search
******************************************************

Search function returns a SearchResult object, containing tasks, user
stories and issues:

.. code:: python

    projects = api.projects.list()
    search_result = api.search(projects[0].id, 'NEW')
    for user_story in search_result.user_stories:
        print (user_story)

******************************************************
History
******************************************************

You can access the history of issues, tasks, userstories and wiki pages:

.. code:: python

    history = api.history.user_story.get(user_story.id)