Getting started

Installation

Install from PyPI using pip:

pip install pycodebase

Alternatively you can install the latest development version directly from GitHub:

pip install https://github.com/davidwtbuxton/pycodebase/archive/master.zip

Connecting to Codebase

You will need a Codebase API username and key.

import codebase

secrets = ('example/alice', 'topsecret')
client = codebase.Client(secrets)

Instead of specifying your username / key in your program, you can create an INI file and then give the path to that file when creating the client.

The INI file should look like this:

[api]
username = example/alice
key = topsecret

Then create the client with the path to the INI file. The filename can be a full path, a relative path or be relative to your home directory:

import codebase

secrets_filename = '~/.codebase.ini'
client = codebase.Client.with_secrets(secrets_filename)

Common API operations

Once you have created a client with valid secrets, you are ready to interact with the Codebase API. Note that most client methods return a generator of results, and that API requests are made lazily (for example if results are paginated, the next request isn’t made until your code accesses results on the second page).

Listing projects

Get information for all the projects in the account.

projects = client.get_projects()

for proj in projects:
    print 'Name', proj['name']
    print 'ID', proj['project_id']
    print 'Permalink', proj['permalink']

Finding a project’s tickets

To interact with a project you refer to the project using its permalink. If the project’s ticket page is https://example.codebasehq.com/projects/foo/tickets/ then its permalink is foo.

tickets = client.get_tickets('foo')

for ticket in tickets:
    print 'Ticket ID', ticket['ticket_id']
    print 'Status', ticket['status']['name']
    print 'Summary', ticket['summary']
    print 'Last updated', ticket['updated_at']

get_tickets accepts several keyword arguments for searching for tickets:

ticket = client.get_tickets('foo', status='open')

Updating a ticket

Adding a note to an existing ticket is easy. You need to know the project’s permalink and a valid ticket ID:

summary = 'This appears as a new note. _Markdown is supported!_'
client.create_ticket_note(project='foo', ticket_id=1234, summary=summary)

Changing the status or assigned user for a ticket is more complicated. You use the same create_ticket_note method, but you must know the ID for fields such as the status or the category.

Suppose your project has 3 statuses: “New”, “In progress” and “Completed”. First we get the statuses and their IDs:

status_names_and_ids = {}
statuses = client.get_ticket_statuses('foo')

for status in statuses:
    status_name = status['name']
    status_id = status['id']

    status_names_and_ids[status_name] = status_id

Now we have a map of the status names and their object IDs, we can create a new note to change a ticket status to “Completed”:

completed_id = status_names_and_ids['Completed']
client.create_ticket_note(project='foo', ticket_id=1234, status_id=completed_id)