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. 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).

from taiga import TaigaAPI

api = TaigaAPI()

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

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

from taiga import TaigaAPI

api = TaigaAPI(token='mytoken')

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

from taiga import TaigaAPI

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

To use LDAP or other authentication backends, use auth_type argument

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

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

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

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)

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

Create a new user story

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

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

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

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

Create a swimlane

newlane = new_project.add_swimlane('New Swimlane')

Create an issue

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

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

List elements

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

You can also specify filters

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

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

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

Specify the page size

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

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

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

Any instance can be updated and deleted

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:

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:

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