Skip to content
A thin client for the Pivotal Tracker API
Python
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
examples
pivotal
.gitignore
CHANGES.rst
LICENSE.txt
MANIFEST.in
README.rst
setup.py

README.rst

Pivotal-Py

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

Installation

Install from PyPI with easy_install or pip:

pip install pivotal-py

Dependencies

Pivotal-Py requires httplib2 0.6.0 or later.

Usage

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)
Something went wrong with that request. Please try again.