Client reference

class codebase.Client(*args, **kwargs)

Codebase API client class that allows some ticket properties to be referenced by name instead of the object ID.

Note that most methods return a generator of results. API requests are lazy, so a request isn’t made until the first result is accessed, and if the results are paginated then additional requests are made only when you access results from subsequent pages.

Most of the Codebase API methods return 20 results per page. Some API methods (such as the API to get all the projects associated with an account) are not paginated and return all results in one page.

create_ticket(project, **kwargs)

Create a new ticket.

See the API documentation on tickets and milestones for details.

create_ticket_note(project, ticket_id, **kwargs)

Create a new note on a ticket in a project.

See the API documentation on updating tickets for details.

use_cache(project, kwargs)

For some ticket classifiers (what Codebase calls organisational objects, such as status, category, etc.), return a new dict with the classifier’s name replaced by the classifier’s ID.

This works by making an API call to get ticket statuses, etc. and caching the results for quick lookup. The cache can be cleared with Client.reset_cache().

class codebase.BaseClient

Codebase API client class.

add_my_key(description, key)

Add a new SSH key for the current authenticated user.

add_user_key(username, description, key)

Add a new SSH key for a user.

See the documentation for public keys for details of the key format. See get_user_keys() for the username format.

Parameters:

• username (str) – the user’s Codebase username
• description (str) – a short description for the key
• key (str) – the text of the public SSH key

create_deployment(project, repo, branch, revision, environment, servers)

Creates a new deployment.

You can create a deployment even if the named repo does not exist, but then the deployment will not appear when listing deployments.

Parameters:

• project (str) – permalink for a project
• repo (str) – permalink for a repository in the project
• branch (str) – git branch name
• revision (str) – git revision ID
• environment – a name (e.g. “live” or “staging”)
• servers (str) – comma-separated list of server names

create_milestone(project, name, deadline=None, description=None, estimated_time=None, parent_id=None, responsible_user_id=None, start_at=None, status=None)

Create a new milestone.

See the API documentation on milestones for details.

Note

The Codebase API allows multiple milestones to have the same name, and this method does not check for duplicates.

Parameters:

• project (str) – permalink for a project
• name (str) – new milestone’s name
• deadline (str|datetime.date) – the date of this milestone’s deadline
• description (str) – a long description for the new milestone
• estimated_time (int) – the estimated time for the milestone
• parent_id (str) – the ID of this milestone’s parent milestone
• responsible_user_id (str) – the id of the user responsible for the milestone
• start_at (str|datetime.date) – the date this milestone begins
• status (str) – the milestone status. One of “active”, “completed” or “cancelled”

Return type:

dict

create_ticket(project, assignee_id=None, category_id=None, description=None, milestone_id=None, priority_id=None, reporter_id=None, status_id=None, summary=None, type=None, upload_tokens=None)

Create a new ticket.

See the API documentation on tickets and milestones for details.

create_ticket_note(project, ticket_id, assignee_id=None, category_id=None, content=None, milestone_id=None, priority_id=None, private=None, status_id=None, summary=None, time_added=None, upload_tokens=None)

Create a new note on a ticket in a project.

See the API documentation on updating tickets for details.

get_activity(raw=True, since=None)

Get all events on the account.

Parameters:

• raw (bool) – show all details
• since (datetime.datetime) – exclude activity before this date

Return type:

generator

get_commits(project, repo, ref)

Get commits in a project’s repository for the given reference.

Parameters:

• project (str) – permalink for a project
• repo (str) – permalink for a repository in the project
• ref (str) – branch, tag or commit reference

Return type:

generator

get_deployments(project, repo)

Get the deployments recorded for a project.

Parameters:

• project (str) – permalink for a project
• repo (str) – permalink for a repository in the project

Return type:

generator

get_file_contents(project, repo, ref, file_path)

Get a file’s content.

Parameters:

• project (str) – permalink for a project
• repo (str) – permalink for a repository in the project
• ref (str) – branch, tag or commit reference
• file_path (str) – path of the file

Return type:

string

get_milestones(project)

Get the milestones for a project.

Parameters:project (str) – permalink for a project Return type:generator

get_my_keys()

Get the public SSH keys for the current authenticated user.

get_project_activity(project, raw=True, since=None)

Get events for a project.

Parameters:

• project (str) – permalink for a project
• raw (bool) – show all details
• since (datetime.datetime) – exclude activity before this date

Return type:

generator

get_project_users(project)

Get the users assigned to a project.

Parameters:project (str) – permalink for a project Return type:generator

get_projects()

Get all the projects on an account.

Return type:generator

get_repositories(project)

Get the code repositories for a project.

Parameters:project (str) – permalink for a project Return type:generator

get_ticket_categories(project)

Get all ticket category choices in a project.

Parameters:project (str) – permalink for a project Return type:generator

get_ticket_notes(project, ticket_id)

Get all notes for a ticket in a project.

Parameters:

• project (str) – permalink for a project
• ticket_id (int) – a ticket number

Return type:

generator

get_ticket_priorities(project)

Get all ticket priorities in a project.

Parameters:project (str) – permalink for a project Return type:generator

get_ticket_statuses(project)

Get all status choices in a project.

Parameters:project (str) – permalink for a project Return type:generator

get_ticket_types(project)

Get all ticket types in a project.

Parameters:project (str) – permalink for a project Return type:generator

get_tickets(project, assignee=None, status=None, category=None, type=None, priority=None, milestone=None)

Get all tickets on a project, or search for tickets.

Search terms can be a string, or a list of strings.

Parameters:

• project (str) – permalink for a project
• assignee (str|list) – search for tickets assigned to a user
• status (str|list) – ticket status, e.g. “open”
• category (str|list) – ticket category, e.g. “General”
• type (str|list) – ticket type, e.g. “Bug”
• priority (str|list) – ticket priority, e.g. “High”
• milestone (str|list) – milestone, e.g. “Sprint 3”

Return type:

generator

get_user_keys(username)

Get public SSH keys for a user.

The username should be the sort version of a Codebase username. If your API username is “example/alice” then the username is “alice”.

Parameters:username (str) – the user’s Codebase username

get_users()

Get all users for this account.

Return type:generator

update_milestone(project, milestone_id, deadline=None, description=None, estimated_time=None, name=None, parent_id=None, responsible_user_id=None, start_at=None, status=None)

Update an existing milestone.

upload_files(files)

Upload files.

Each file in the list can be one of:

• A file-like object open for reading.
• A pair of (filename, file-like object).
• A pair of (filename, byte-string).

Returns a generator of upload info dictionaries. The ‘identifier’ key for an uploaded file can be used in the upload_tokens argument when creating a ticket or note.

Parameters:files (list) – list of files to upload Return type:generator

classmethod with_secrets(filename)

Create a new instance of Client.

The API username / key are read from a file. A filename like ‘~/.secrets’ is expanded to with a home directory.

The file must be in INI format, with a section named “api” and properties for “username” and “key” within the section.

[api]
username = example/alice
key = topsecret

Parameters:filename (str) – path to INI file