circleclient

Python client library for CircleCI API.

circleclient is a Python client library used for accessing CircleCI API to retrieve information about builds. It can also be used to start and stop builds. Full list of implemented features can be found in the usage section.

Main Features

  • Start build
  • Cancel build
  • Retry build
  • Run parametrized builds
  • Retrieve information about user
  • Retrieve information about build(s)
  • List followed repositories
  • List build artifacts
  • Clear build cache

Contents:

Installation

At the command line either via pip:

$ pip install circleclient

If you have virtualenvwrapper installed:

$ mkvirtualenv circleclient
$ pip install circleclient

Or, if you have virtualenv installed:

$ virtualenv circleclient-venv
$ source circleclient-venv/bin/activate
$ pip install circleclient

Usage

Retrieve information about User

import os
from circleclient import circleclient


token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retrieve User data
client.user.info()

List projects followed by the user

import os
from circleclient import circleclient


token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retrieve information about projects
client.projects.list_projects()

Trigger new build

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Trigger build
client.build.trigger('<username>', '<project_name>', '<branch>')

Trigger new parametrized build

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Trigger parametrized build
client.build.trigger('<username>', '<project_name>', '<branch>', '<PARAM1>'='<VAL1>')

Cancel running build

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Cancel build
client.build.cancel('<username>', '<project_name>', '<build_number>')

Retry build

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retry build
client.build.retry('<username>', '<project_name>', '<build_number>')

List build artifacts

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# List build artifacts
client.build.artifacts('<username>', '<project_name>', '<build_number>')

Retrieve build status

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retrieve build status
client.build.status('<username>', '<project_name>', '<build_number>')

Retrieve information about builds across all projects

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retrieve build status
# Default limit=30, offset=0
client.build.recent_all_projects(limit=<int>, offset=0)
client.build.recent_all_projects()

Retrieve information about recent build(s)

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(token)

# Retrieve build status
# Default limit=30, offset=0, branch=None
client.build.recent('<username>', '<project>', limit='<int>', offset='<int>')

# Retrieve last 10 builds of branch master
client.build.recent('<username>', '<project>', limit=10, branch='master')

# Retrieve last build of branch develop
client.build.recent('<username>', '<project>', branch='develop')

Clear build cache

import os
from circleclient import circleclient

token = os.environ['API_TOKEN']
client = circleclient.CircleClient(api_token=token)

# Clear build cache
client.cache.clear(username='<username>', project='<project_name>')

Contributing

Contributing Code

  • A good patch:

    • is clear
    • works across all supported versions of Python
    • follows the existing style of the code base (PEP-8)
    • has docstrings (we use Goole style docstrings)
    • has comments included as needed

  • A test case that demonstrates the previous flaw that now passes with the included patch

  • If it adds/changes a public API, it must also include documentation for those changes

Reporting An Issue/Feature

Credits

Development Lead

Contributors

History

0.1.6 (2015-09-04)

  • Updated documentation

0.1.5 (2015-31-03)

  • Filter recent builds by build status: completed, successful, failed, running

0.1.4 (2014-21-09)

  • Retrieving information about single and multiple builds.
  • Retrieving a limited number of builds with optional offset.
  • Retrieving build information about specific branch.

0.1.3 (2014-25-07)

  • Add support for parametrized builds
  • Add support for listing build artifacts

0.1.2 (2014-07-07)

  • Add support for clearing cache

0.1.1 (2014-30-06)

  • Add support for retrying builds

0.1.0 (2014-29-06)

  • First release on PyPI.

Feedback

If you have any suggestions or questions about circleclient feel free to email me at qba73@postpro.net.

If you encounter any errors or problems with circleclient, please let me know! Open an Issue at the GitHub http://github.com/qba73/circleclient main repository.