API ¶

Contents

API
- PTracker
- Projects
- Memberships
- Iterations
- Stories
- Tasks

PTracker ¶

class pyvotal.PTracker(user=None, password=None, token=None, ssl=True)¶

Base api entry point

Parameters:	user – pivotal username (optional if token provided) password – pivotal password (optional if token provided) token – pivotal api token (optional if user and password provided) ssl – use https for api calls

If no token provided it would be requested using given username and password.

Membership()¶: Factory method. This method creates new Membership objects.

Project()¶: Factory method. This method creates new Project objects.

Story()¶: Factory method. This method creates new Story objects.

Task()¶: Factory method. This method creates new Task objects.

projects¶: ProjectManager to manipulate user`s projects.

token¶

User token, obtained via api or passed to PTracker constructor:

from pyvotal import PTracker

ptracker = PTracker(user='SomeUser', password='password')
print 'SomeUser token is', ptraker.token

Projects ¶

class pyvotal.projects.ProjectManager(client)¶

Class for projects retrieval. Available as PTracker.projects.

Note: you can not delete projects using v3 api.

add(project)¶

Adds new project to Pivotal Tracker. You can set no_owner attribute if you want to leave created project without owner

Parameters:	project – `Project`
Returns:	`Project`

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.Project()
project.name = "My project"
project.no_owner = True
project = ptracker.projects.add(project)

print project.id

all()¶

Returns all user`s projects.

Returns:	list of `Project` objects

from pyvotal import PTracker

ptracker = PTracker(token='token')

for project in ptracker.projects.all():
    print project.id, project.name

get(project_id)¶

Returns user`s project with given id

Parameters:	project_id – Integer project id
Returns:	`Project` object

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(31337)
print project.id, project.name

class pyvotal.projects.Integration(**values)¶

Parsed response from api with integration info. Available as Project.integrations

Available fields:

id	Integer
type	String
name	String
field_name	String
field_label	String
active	Boolean

class pyvotal.projects.Project(**values)¶

Parsed response from api with project info. Use PTracker.Project to create instances of this class.

Available fields:

id	Integer
name	String
iteraton_length	Integer
week_start_day	String
pont_scale	String
account	String
first_iteration_start_time	datetime
current_iteration_number	Integer
enable_tasks	Boolean
velocity_scheme	String
current_velocity	Integer
initial_velocity	Integer
number_of_done_iterations_to_show	Integer
labels	String
allow_attachments	Boolean
public	Boolean
use_https	Boolean
bugs_and_chores_are_estimatable	Boolean
commit_mode	Boolean
last_activity_at	datetime
integrations	list of `Integration`

Note: you should check field values for None as some of them may be missing.

iterations¶: IterationManager to manipulate project`s iterations.

memberships¶: MembershipManager to manipulate project`s memberships.

stories¶: StoryManager to manipulate project`s stories.

Memberships ¶

class pyvotal.memberships.MembershipManager(client, project_id)¶

Class for memberships retrieval. Available as Project.memberships.

add(membership)¶

Adds new member to project.

Parameters:	membership – `Membership`
Returns:	`Membership`

from pyvotal import PTracker

ptracker = PTracker(token='token')
membership = ptracker.Membership()
membership.role = 'Owner'
membership.person.email = 'test@example.com'
membership.person.name = 'Anatoly Kudinov'
membership.person.initials = 'AK'

project = ptracker.projects.get(1231)
membership = project.memberships.add(membership)

print membership.id

all()¶

Returns all project`s memberships

Returns:	list of `Membership` objects

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)

for membership in project.memberships.all():
    print membership.id, membership.role, membership.person.email

get(membership_id)¶

Returns project`s membership with given id.

Parameters:	membership_id – Integer membership id
Returns:	`Membership` object

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
membership = projects.memberships.get(1232)
print membership.id, membership.role, membership.person.email

delete(membership_id)¶

Deletes membership with given id

Parameters:	membership_id – Integer membership id
Returns:	Deleted `Membership` object

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
membership = projects.memberships.delete(1232)
print "Membership", membership.id, "deleted"

class pyvotal.memberships.Membership(**values)¶

Parsed response from api with membership info. Use PTracker.Membership to create instances of this class.

Available fields:

id	Integer
role	String
person	`Person`

is_member¶: True if person is project member.

is_owner¶: True if person is project owner.

is_viewer¶: True if person is project viewer.

class pyvotal.memberships.Person(**values)¶

Class represents person with project membership. Available fields:

email	String
name	String
initials	String

Iterations ¶

class pyvotal.iterations.IterationManager(client, project_id, *args)¶

Class for iterations retrieval. Available as Project.iterations

all(filter=None, limit=None, offset=None)¶

Returns project`s iterations, optionally filtered by group. For done iterations, offset should be negative, relative to the most recent done iteration

Parameters:	filter – Iterations group: done, current, backlog, or current_backlog. limit – Max number of iterations to return offset – Number of iterations to skip
Returns:	list of `Iteration` objects

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)

for iteration in project.iterations.all(filter='done', offset=-6):
    print iteration.id, iteration.number, iteration.finish

class pyvotal.iterations.Iteration(**values)¶

Parsed response from api with iteration info.

Available fields:

id	Integer
number	Integer
start	datetime
finish	datetime
team_strength	Float
stories	list of `Story`

Stories ¶

class pyvotal.stories.StoryManager(client, project_id, *args)¶

Class for stories management. Availeable as Project.stories

add(story)¶

Adds new story to project.

Parameters:	story – `Story`
Returns:	`Story`

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.type = "feature"
story.name = "New story"
project = ptracker.projects.get(1231)
story = project.stories.add(story)

print story.id

all(limit=None, offset=None, **kwargs)¶

Returns optionally filtered project`s stories.

Parameters:	limit – Max number of stories to return offset – Number of stories to skip kwargs – You can optionally pass filter options as described here https://www.pivotaltracker.com/help#howcanasearchberefined.
Returns:	list of `Story` objects

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)

for story in project.stories.all(type="Feature", state="unstarted", limit=10, offset=20):
    print story.id, story.name, story.description

get(story_id)¶

Returns project`s story with given id

Parameters:	story_id – Integer story id
Returns:	`Story` object

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
story = projects.stories.get(1232)
print story.id, story.name, story.description

delete(story_id)¶

Deletes story with given id.

Parameters:	story_id – Id of story to delete.
Returns:	Deleted `Story` object

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
story = projects.stories.delete(1232)
print "Story", story.id, story.name, "deleted"

deliver_all_finished()¶

Delivers all finished stories.

Returns:	list of delivered `Stories`

from pyvotal import PTracker

ptracker = PTracker(token='token')
project = ptracker.projects.get(1231)

for story in projects.stories.deliver_all_finished():
  print story.id, story.name, 'delivered'

class pyvotal.stories.Story(**values)¶

Parsed response from api with story info. Use PTracker.Story to create instances of this class.

Available fields:

id	Integer
project_id	Integer
story_type	String
url	String
estimate	Integer
current_state	String
description	String
name	String
requested_by	String
owned_by	String
created_at	datetime
accepted_at	datetime
labels	String
notes	list of `Note`
attachments	list of `Attachment`

Story could also have more fields depending on existing integrations in project. To get them use Project.integrations

add_attachment(name, fobj)¶

Adds attachment to story.

Parameters:	name – Attachment file name. fobj – File-like object to upload.

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
story = projects.stories.get(1232)

story.add_attachment("hosts", open("/etc/hosts"))

add_note(text)¶

Adds note to story.

Parameters:	text – Text to be added to story as note.
Returns:	Created `Note`.

from pyvotal import PTracker

ptracker = PTracker(token='token')

project = ptracker.projects.get(1231)
story = projects.stories.get(1232)

note = story.add_note("Usefull info")
print note.id, note.noted_at 

move_after(story)¶

Moves story after given.

Parameters:	story – Story id or `Story`.
Returns:	Updated `Story`.

from pyvotal import PTracker

ptracker = PTracker(token='token')
project = ptracker.projects.get(1231)

story = projects.stories.get(1232)
story.move_after(1233)

move_before(story)¶

Moves story before given.

Parameters:	story – Story id or `Story`.
Returns:	Updated `Story`.

from pyvotal import PTracker

ptracker = PTracker(token='token')
project = ptracker.projects.get(1231)

story = projects.stories.get(1232)
story.move_before(another_story)

save()¶

Saves changes to existing story back to pivotal.

from pyvotal import PTracker

ptracker = PTracker(token='token')
project = ptracker.projects.get(1231)

story = projects.stories.get(1232)
story.estimate = 3
story.save()

tasks¶: TaskManager to manipulate story`s tasks.

Tasks ¶

class pyvotal.tasks.TaskManager(client, project_id, story_id)¶

Class for tasks retrieval. Availeable as Story.tasks.

add(task)¶

Adds new task to story.

Parameters:	task – `Task`
Returns:	`Task`

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.id = story_id
story.project_id = project_id

task = ptracker.Task()
task.description = "clean shields"
task = story.tasks.add(task)
print "Task", task.id, "added"

all()¶

Returns story`s tasks.

Returns:	list of `Task` objects

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.id = story_id
story.project_id = project_id

for task in story.tasks.all():
    print task.id, task.description

get(task_id)¶

Returns story`s task with given id.

Parameters:	task_id – Integer task id
Returns:	`Task` object

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.id = story_id
story.project_id = project_id

task = story.tasks.get(task_id)
print task.id, task.description

delete(task_id)¶

Deletes task with given id

Parameters:	task_id – Id of task to delete.
Returns:	Deleted `Task` object

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.id = story_id
story.project_id = project_id

task = story.tasks.delete(task_id)
print "Task", task.id, task.description, "deleted"

class pyvotal.tasks.Task(**values)¶

Parsed response from api with task info. Use PTracker.Task to create instances of this class.

Available fields:

id	Integer
description	String
position	Integer
compelete	Boolean
created_at	datetime

save()¶

Saves changes to existing task back to pivotal.

from pyvotal import PTracker

ptracker = PTracker(token='token')
story = ptracker.Story()
story.id = story_id
story.project_id = project_id

task = story.tasks.get(task_id)
task.complete = True
task.save()

API ¶

PTracker ¶

Projects ¶

Memberships ¶

Iterations ¶

Stories ¶

Tasks ¶

Project Versions

Table Of Contents

Previous topic

This Page

Navigation

Project Versions

RTD Search

Previous topic

This Page

Quick search

Navigation