Pivotal-Py is a very thin wrapper built on top of httplib2 to make requests against the Pivotal Tracker API.

Install from PyPI with easy_install or pip:

pip install pivotal-py

Pivotal-Py requires httplib2 0.6.0 or later.

This Pivotal Tracker API client uses the token to authenticate with Pivotal Tracker. You can get a token by going to your user profile and creating an API token.

Once you have an API token making requests against the APIs follows a simple pattern of chainable methods, for example:

import pivotal

pv = pivotal.Pivotal('TOKEN')

# Assuming a base URL of 'http://www.pivotaltracker.com/services/v3/'

# Perform a GET at /projects and processes content via ElementTree.
etree = pv.projects().get_etree()

# Perform the same GET at /projects but return the response and
# content direct from httplib2.
response, content = pv.projects().get()

Note: As seen above, there are two ways to get the content of a request:

1. Call get_etree() to return the content as ElementTree object.
2. Call get() to return the tuple containing both the response and content direct from httplib2.

Any positional arguments get pushed onto the URL:

# Perform a GET at /projects/[id]/stories where [id] is a project ID.
etree = pv.projects(id).stories().get_etree()

Any keyword arguments get mapped to the URL query string and appended at the end of the URL:

# Perform a GET at /projects/[id]/stories and filter stories by those that
# are not started.
etree = pv.projects(id).stories(filter='state:unstarted').get_etree()
# Results in a URL of: /projects/[id]/stories?filter=state%3Aunstarted

Note: POSTs are currently not implemented, but the plan is to implement a post method that takes a body argument which is the body of the POST:

# TODO: POST to /projects to create a new project
etree = pv.projects().post(xml_body)