Python wrapper for the Assembla API


Keywords
Assembla API
License
MIT
Install
pip install assembla==2.8.0

Documentation

Python wrapper for the Assembla API

An easy to use wrapper around the Assembla API.

Installation

Install assembla with pip:

$ pip install assembla

Connecting to Assembla's API requires your user account's authentication key and secret, which are accessible from https://www.assembla.com/user/edit/manage_clients.

Basic example

The following example connects to Assembla, retrieves a list of tickets for a space and then outputs information about each.

from assembla import API

assembla = API(
    key='8a71541e5fb2e4741120',
    secret='a260dc4448c81c907fc7c85ad09d31306c425417',
    # Use your API key/secret from https://www.assembla.com/user/edit/manage_clients
)

my_space = assembla.spaces(name='My Space')[0]

for ticket in my_space.tickets():
    print '#{0} - {1}'.format(ticket['number'], ticket['summary'])

# >>> #1 - My first ticket
# >>> #2 - My second ticket
# ...

User guide

The Assembla API wrapper uses a number of Python classes to represent the objects retrieved from Assembla, some of which possess the following methods and properties:

API

API instances are the primary facet of the Assembla API wrapper and are the starting point for interactions with the API. APIs are instantiated with authentication details (available from https://www.assembla.com/user/edit/manage_clients) and offer two methods of navigating Assembla's data:

API.stream()

Returns a list of Event instances indicating the activity stream you have access to. Keyword arguments can be provided to filter the results.

API.spaces()

Returns a list of Space instances which represent all the spaces that you have access to. Keyword arguments can be provided to filter the results.

Here's an example which prints a list of the spaces available:

from assembla import API

assembla = API(
    key='8a71541e5fb2e4741120',
    secret='a260dc4448c81c907fc7c85ad09d31306c425417',
    # Use your API key/secret from https://www.assembla.com/user/edit/manage_clients
)

for space in assembla.spaces():
    print space['name']

Space

See the Space object field reference for field names and explanations.

Spaces possess the following methods:

Space.tickets()

Returns a list of all Ticket instances inside the Space. Keyword arguments can be provided to filter the results.

Space.milestones()

Returns a list of all Milestone instances inside the Space. Keyword arguments can be provided to filter the results.

Space.components()

Returns a list of all Component instances inside the Space. Keyword arguments can be provided to filter the results.

Space.tools()

Returns a list of all SpaceTool instances inside the Space. Keyword arguments can be provided to filter the results.

Space.users()

Returns a list of all User instances with access to the Space. Keyword arguments can be provided to filter the results.

Space.tags()

Returns a list of all Tag instances inside the Space. Keyword arguments can be provided to filter the results.

Here is an example which prints a report of all the tickets in a Space which have the status 'New' and belong to a milestone called 'Alpha Release':

space = assembla.spaces(name='My Space')[0]

milestone = space.milestones(title='Alpha Release')[0]

tickets = space.tickets(
    milestone_id=milestone['id'],
    status='New'
)

print 'New tickets in "{0}".format(milestone['title'])
for ticket in tickets:
    print '#{0} - {1}'.format(ticket['number'], ticket['summary'])

# >>> New tickets in "Alpha Release"
# >>> #1 - My first ticket
# >>> #2 - My second ticket
# ...

Milestone

See the Milestone object field reference for field names and explanations.

Milestone instances possess the following method:

Milestone.tickets()

Returns a list of all Ticket instances which are connected to the Milestone. Keyword arguments can be provided to filter the results.

Here is an example which prints a report of all the tickets in a milestone:

milestone = space.milestones()[0]

for ticket in milestone.tickets():
    print '#{0} - {1}'.format(ticket['number'], ticket['summary'])

# >>> #1 - My first ticket
# >>> #2 - My second ticket
# ...

Ticket

See the Ticket object field reference for field names and explanations.

Ticket instances possess the following methods:

Ticket.milestone()

Returns an instance of the Milestone that the Ticket belongs to.

Ticket.user()

Returns an instance of the User that the Ticket is assigned to.

Ticket.component()

An instance of the Component that the Ticket is assigned to.

Ticket.comments()

Returns a list of the Ticket Comment instances relating to the Ticket.

Ticket.write()

Calling Ticket.write() sends the ticket back to Assembla. The ticket object must have a space attribute set to the corresponding Space object.

If the Ticket object has a 'number' key (i.e. if it already exists), the corresponding Ticket on Assembla is updated (using an HTTP PUT request), otherwise a new ticket is created in the space (using HTTP POST).

Ticket.write() returns the instance of the ticket. If a new ticket was created, the returned instance will have the number, id, and other server-generated fields populated.

Ticket.delete()

Calling Ticket.delete() deletes the ticket from Assembla. The ticket object must have a space attribute set to the corresponding Space object.

Ticket Comment

See the Ticket Comment object field reference for field names and explanations.

User

See the User object field reference for field names and explanations.

User instances possess the following method:

User.tickets()

Returns a list of all Ticket instances which are assigned to the User. Keyword arguments can be provided to filter the results.

Here is an example which prints a report of all the tickets assigned to a user named 'John Smith':

user = space.users(name='John Smith')[0]

for ticket in user.tickets():
    print '#{0} - {1}'.format(ticket['number'], ticket['summary'])

# >>> #1 - John's first ticket
# >>> #2 - John's second ticket
# ...

Component

See the Ticket Component object field reference for field names and explanations.

Space tool

See the Space tool object field reference for field names and explanations.

Wiki Page

See the Wiki Page object field reference for field names and explanations.

Wiki Page instances possess the following methods:

WikiPage.write()

Calling WikiPage.write() sends the page back to Assembla. The WikiPage object must have a space attribute set to the corresponding Space object.

If the WikiPage object has a 'id' key (i.e. if it already exists), the corresponding WikiPage on Assembla is updated (using an HTTP PUT request), otherwise a new ticket is created in the space (using HTTP POST).

WikiPage.write() returns the instance of the ticket. If a new ticket was created, the returned instance will have the id and other server-generated fields populated.

WikiPage.delete()

Calling WikiPage.delete() deletes the ticket from Assembla. The WikiPage object must have a space attribute set to the corresponding Space object.

Tag

See the Tag object field reference for field names and explanations.

Event

See the Event object field reference for field names and explanations.

Filtering objects with keyword arguments

Most data retrieval methods allow for filtering of the objects based on the data returned by Assembla. The keyword arguments to use correlate to the field names returned by Assembla, for example Tickets can be filtered with keyword arguments similar to field names specified in Assembla's Ticket Fields documentation

Using Space.tickets as an example of filtering with keyword arguments:

  • space.tickets(number=100) will return the ticket with the number 100.
  • space.tickets(status='New', assigned_to_id=100) will return new tickets assigned to a user with the id 100

Normal keyword filtering will only act on the data that Assembla returns. If you wish to take advantage of the pre-filtering that Assembla's API offers, an extra_params keyword argument can be provided. The argument should be a dictionary that contains extra parameters which will be passed along when the GET request is sent.

For example, to filter Stream events from a certain period:

assembla.stream(extra_params={
    'from': '2014-01-19 09:20'
})

Custom fields

An object's custom fields are retrieved similarly to most fields, the only difference is that they are nested within a dictionary named custom_fields.

Here's an example to get a custom field 'billing_code' from a ticket:

billing_code = ticket['custom_fields']['billing_code']

Caching

The API wrapper has an optional response caching system which is deactivated by default. Turning the caching system on will reduce the overhead on repeated requests, but can cause stale data to perpetuate for long-running processes. Turning the cache on is done by setting an API instance's cache_responses variable to True. The cache can be turned off by setting cache_responses to False.

Here is an example of how to instantiate the wrapper and activate the cache.

from assembla import API

assembla = API(
    # Auth details...
)

assembla.cache_responses = True

Colophon

A list of contributors is available on Github.

This project is licensed under The MIT License (MIT). Copyright (c) 2014, Mark Finger.

For more information about the license for this particular project read the LICENSE.txt file.