Microsoft TFS Python Library (TFS API Python client)

Introduction
Quickstart
Guide
- Compatibility
- Contribute

Introduction

Microsoft Team Foundation Server Python Library is a Microsoft TFS API Python client that can work with Microsoft TFS workflow and workitems.

This python library allows:

Installation

pip install dohq-tfs

Create connection

from tfs import TFSAPI

user="username"
password="password"

# Use DefaultCollection
client = TFSAPI("https://tfs.tfs.ru/tfs/", user=user, password=password)

# Use CustomCollection
client = TFSAPI("https://tfs.tfs.ru/tfs/", project="DefaultCollection", user=user, password=password)

# Set path to ProjectName in project parameter
client = TFSAPI("https://tfs.tfs.ru/tfs/", project="DefaultCollection/ProjectName", user=user, password=password)

workitem = client.get_workitem(100) # Test connection with Workitem id

Authorization

# DEFAULT - Use HTTP Basic Auth
client = TFSAPI("https://tfs.tfs.ru/tfs/", user=user, password=password)

# Use NTLM authorization
from requests_ntlm import HttpNtlmAuth
client = TFSAPI("https://tfs.tfs.ru/tfs/", user=user, password=password, auth_type=HttpNtlmAuth)

Timeout connection

You can set CONNECT and READ timeouts (read more)

from tfs import TFSAPI
client = TFSAPI("https://tfs.tfs.ru/tfs/", user=user, password=password, connect_timeout=30, read_timeout=None)

Workitem

# For single Workitem
workitem = client.get_workitem(100)

# For multiple
workitem = client.get_workitems([100,101,102]) # list
workitem = client.get_workitems("100,101,102") # string separated with comma

# Get all fields
print(workitem.field_names)

# Case insensetive. Remove space in field name
print(workitem['assignedTo']) 

# Workitem Parent Workitem
parent = workitem.parent
if parent: # Parent is None if Workitem hasn't Parent link
    print("Workitem with id={} have parent={}".format(workitem.id, parent.id))

# Workitem Childs Workitem
childs = workitem.childs
if childs: # Child is empty list if Workitem hasn't Child link
    print("Workitem with id={} have Childs={}".format(workitem.id, ",".join([x.id for x in childs])))

# Workitem revisions
revisions = workitem.revisions

Update workitem

# Update field
workitem['state'] = 'Complete' 

# Add comment
print(workitem.history)
workitem['History'] = "Omg, it is goos issue!"
print(workitem.history)

Workitem attachments

If workitem has attachments, you can download it and get info about.

attachments = workitem.attachments
attachment = attachments[0]
# Internal TFS UID
print(attachment.id) 

# Filename
print(attachment.name)

# TFS Download URL
print(attachment.url) 

# You can download file to folder
attachment.download('/home/user/folder') 

# All raw data
print(attachment.data)

Run Saved Queries

You can run Saved Queries and get Workitems

# Set path to ProjectName in project parameter
client = TFSAPI("https://tfs.tfs.ru/tfs/", project="DefaultCollection/ProjectName", user=user, password=password)

# Run New query 1 in Shared Queries folder
quiery = client.run_query('Shared Queries/New query 1')

# result content raw data
result = quiery.result
print(quiery.columns)
print(quiery.column_names)

# Get all found workitems
workitems = quiery.workitems

Run WIQL

You can run Work Item Query Language

# Set path to ProjectName in project parameter
client = TFSAPI("https://tfs.tfs.ru/tfs/", project="DefaultCollection/ProjectName", user=user, password=password)

# Run custom query
### NOTE: Fields in SELECT really ignored, wiql return Work Items with all fields
query = """SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.ChangedDate]
FROM workitems
WHERE
    [System.WorkItemType] = 'Bug'
ORDER BY [System.ChangedDate]"""

wiql = client.run_wiql(query)

# Get founded Work Item ids
ids = wiql.workitem_ids
print("Found WI with ids={}".format(",".join(ids)))

# Get RAW query data - python dict
raw = wiql.result

# Get all found workitems
workitems = wiql.workitems
print(workitems[0]['Title'])

Advanced

Advanced usage
Some others object available

Guide

If you use this library, put a star on this repository. This motivates us and other developers to develop the library :)

Compatibility

Tested with Python.3.4
TFS 2015
TFS 2017

Contribute

About contribute

401ode/tfs