Welcome to circleci.py¶

circleci.py is a python wrapper around the CircleCI API.

Quickstart¶

Installation¶

Note

circleci.py requires python3

You can install the latest version of circleci.py with:

pip install circleci

Basic Usage¶

Make a new API token in the CircleCI application.

Import the CircleCI API and start using methods:

from circleci.api import Api

circleci = Api("$YOUR_TOKEN")

# get info about your user
circleci.get_user_info()

# get list of all of your projects
circleci.get_projects()

Tutorial¶

demo¶

The demo package shows some examples of how to use circleci.py

copyright:	2019 Lev Lazinskiy
license:	MIT, see LICENSE for more details.

demo.sdk¶

This module shows some examples of how to use the circleci.py sdk

demo.sdk.build_singleton¶

Demonstrate how to use the circleci.py SDK to make builds run one at a time.

The purpose of this script is to be executed early in a CircleCI job. It will check for running builds, if it finds any it will pause execution and poll at a 15 second interval. Once other jobs have finished it will continue execution. If no jobs are found, it will start execution.

import os
from circleci.api import Api
from circleci.sdk import SDK

ORG = "levlaz"
REPO = "circleci-sandbox"

circleci = Api(os.environ.get("CIRCLE_TOKEN"))
sdk = SDK(circleci)

if __name__ == "__main__":
    sdk.build_singleton(ORG, REPO)

Usage

Make sure a valid CIRCLE_TOKEN is set as an environment variable.
Replace ORG and REPO with your own values.
ORG can be either a username or an org name.
If you are using bitbucket you should add the vcs_type argument to build_singleton.
sdk.build_singleton(ORG, REPO, vcs_type='bitbucket')

Within a CircleCI job you can do something like this in order to execute this script. Assuming you have this build_singleton.py script checked into a directory called scripts in your code repository.

    - run:
        name: Build Singleton
        command: |
            sudo pip install circleci
            python scripts/build_singleton.py

If builds are running you will see the following output in CircleCI:

found running builds, sleeping for 15 seconds.
['https://circleci.com/gh/levlaz/circleci-sandbox/1148', 'https://circleci.com/gh/levlaz/circleci-sandbox/1147', 'https://circleci.com/gh/levlaz/circleci-sandbox/1146']
found running builds, sleeping for 15 seconds.
['https://circleci.com/gh/levlaz/circleci-sandbox/1146']
found running builds, sleeping for 15 seconds.
['https://circleci.com/gh/levlaz/circleci-sandbox/1146']

Once no more jobs are found, the job will begin to execute and you will see the following output in CircleCI:

no running builds found, beginning execution.

API Reference¶

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

API¶

Note

Unless otherwise noted all arguments are of the str type.

API Object¶

CircleCI API Module

copyright:	2017 by Lev Lazinskiy
license:	MIT, see LICENSE for more details.

class circleci.api.Api(token, url='https://circleci.com/api/v1.1')[source]¶

A python interface into the CircleCI API

Instantiate a new circleci.Api object.

Parameters:	url – The URL to the CircleCI instance. Defaults to https://circleci.com/api/v1.1. If you are running CircleCI server, the API is available at the same endpoint of your own installation url. i.e (https://circleci.yourcompany.com/api/v1.1). token – Your CircleCI API token.

_download(url, destdir=None, filename=None)[source]¶

File download helper.

Parameters:	url – The URL to the artifact. destdir – The optional destination directory. Defaults to None (curent working directory). filename – Optional file name. Defaults to the name of the artifact file.

_request(verb, endpoint, data=None)[source]¶

Request a url.

Parameters:	endpoint – The api endpoint we want to call. verb – POST, GET, or DELETE. params (dict) – Optional build parameters.
Raises:	requests.exceptions.HTTPError – When response code is not successful.
Returns:	A JSON object with the response from the API.

add_envvar(username, project, name, value, vcs_type='github')[source]¶

Adds an environment variable to a project

Parameters:	username – Org or user name. project – Case sensitive repo name. name – Name of the environment variable. value – Value of the environment variable. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/envvar

add_heroku_key(apikey)[source]¶

Adds your Heroku API key to CircleCI

Parameters:	apikey – Heroku API key.

Endpoint:: POST: /user/heroku-key

add_ssh_key(username, project, ssh_key, vcs_type='github', hostname=None)[source]¶

Create an ssh key

Used to access external systems that require SSH key-based authentication.

Note

The ssh_key must be unencrypted.

Parameters:	username – Org or user name. project – Case sensitive repo name. branch – Defaults to master. ssh_key – Private RSA key. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`. hostname – Optional hostname. If set, the key will only work for this hostname.

Endpoint:: POST: /project/:vcs-type/:username/:project/ssh-key

add_ssh_user(username, project, build_num, vcs_type='github')[source]¶

Adds a user to the build’s SSH permissions.

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/:build_num/ssh-users

cancel_build(username, project, build_num, vcs_type='github')[source]¶

Cancels the build.

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/:build_num/cancel

clear_cache(username, project, vcs_type='github')[source]¶

Clear cache for a project

Parameters:	username – Org or user name. project – Case sensitive repo name. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: DELETE: /project/:vcs-type/:username/:project/build-cache

create_checkout_key(username, project, key_type, vcs_type='github')[source]¶

Create a new checkout keys for a project

Parameters:	username – Org or user name. project – Case sensitive repo name. key_type – The type of key to create. Valid values are ‘deploy-key’ or ‘github-user-key’ vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.
Raises:	InvalidKeyError – When key_type is not a valid key type.

Endpoint:: POST: /project/:vcs-type/:username/:project/checkout-key

delete_checkout_key(username, project, fingerprint, vcs_type='github')[source]¶

Delete a checkout key.

Parameters:	username – Org or user name. project – Case sensitive repo name. fingerprint – The fingerprint of the checkout key. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: DELETE: /project/:vcs-type/:username/:project/checkout-key/:fingerprint

delete_envvar(username, project, name, vcs_type='github')[source]¶

Delete an environment variable

Parameters:	username – Org or user name. project – Case sensitive repo name. name – Name of the environment variable. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: DELETE /project/:vcs-type/:username/:project/envvar/:name

download_artifact(url, destdir=None, filename=None)[source]¶

Download an artifact from a url

Parameters:	url – The URL to the artifact. destdir – The optional destination directory. Defaults to None (curent working directory). filename – Optional file name. Defaults to the name of the artifact file.

follow_project(username, project, vcs_type='github')[source]¶

Follow a new project on CircleCI.

Parameters:	username – Org or user name. project – Case sensitive repo name. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/follow

get_artifacts(username, project, build_num, vcs_type='github')[source]¶

List the artifacts produced by a given build.

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: /project/:vcs-type/:username/:project/:build_num/artifacts

get_build_info(username, project, build_num, vcs_type='github')[source]¶

Full details for a single build.

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: /project/:vcs-type/:username/:project/:build_num

get_checkout_key(username, project, fingerprint, vcs_type='github')[source]¶

Get a checkout key.

Parameters:	username – Org or user name. project – Case sensitive repo name. fingerprint – The fingerprint of the checkout key. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: /project/:vcs-type/:username/:project/checkout-key/:fingerprint

get_envvar(username, project, name, vcs_type='github')[source]¶

Gets the hidden value of an environment variable

Parameters:	username – Org or user name. project – Case sensitive repo name. name – Name of the environment variable. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET /project/:vcs-type/:username/:project/envvar/:name

get_latest_artifact(username, project, branch=None, status_filter='completed', vcs_type='github')[source]¶

List the artifacts produced by the latest build on a given branch.

Note

This endpoint is a little bit flakey. If the “latest” build does not have any artifacts, rathern than returning an empty set, the API will 404.

Parameters:

username – org or user name
project – case sensitive repo name
branch – The branch you would like to look in for the latest build. Returns artifacts for latest build in entire project if omitted.
filter – Restricts which builds are returned. defaults to ‘completed’ valid filters: “completed”, “successful”, “failed”
vcs_type – defaults to github on circleci.com you can also pass in bitbucket

Raises:

InvalidFilterError – when filter is not a valid filter.

Endpoint:: GET: /project/:vcs-type/:username/:project/latest/artifacts

get_project_build_summary(username, project, limit=30, offset=0, status_filter=None, branch=None, vcs_type='github')[source]¶

Build summary for each of the last 30 builds for a single git repo.

Parameters:

username – Org or user name.
project – Case sensitive repo name.
limit (int) – The number of builds to return. Maximum 100, defaults to 30.
offset (int) – The API returns builds starting from this offset, defaults to 0.
status_filter – Restricts which builds are returned. Set to “completed”, “successful”, “running” or “failed”. Defaults to no filter.
branch – Narrow returned builds to a single branch.
vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.

Raises:

InvalidFilterError – when filter is not a valid filter.

Endpoint:: GET: /project/:vcs-type/:username/:project

get_projects()[source]¶

List of all the projects you’re following on CircleCI.

Endpoint:: GET: /projects

get_recent_builds(limit=30, offset=0)[source]¶

Build summary for each of the last 30 recent builds, ordered by build_num.

Parameters:	limit (int) – The number of builds to return. Maximum 100, defaults to 30. offset (int) – The API returns builds starting from this offset, defaults to 0.

Endpoint:: GET: /recent-builds

get_test_metadata(username, project, build_num, vcs_type='github')[source]¶

Provides test metadata for a build

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: /project/:vcs-type/:username/:project/:build_num/tests

get_user_info()[source]¶

Provides information about the signed in user.

Endpoint:: GET: /me

list_checkout_keys(username, project, vcs_type='github')[source]¶

List checkout keys for a project

Parameters:	username – Org or user name. project – Case sensitive repo name. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: project/:vcs-type/:username/:project/checkout-key

list_envvars(username, project, vcs_type='github')[source]¶

Provides list of environment variables for a project

Parameters:	username – Org or user name. project – Case sensitive repo name. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: GET: /project/:vcs-type/:username/:project/envvar

retry_build(username, project, build_num, ssh=False, vcs_type='github')[source]¶

Retries the build.

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num – Build number. ssh (bool) – Retry a build with SSH enabled. Defaults to False. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/:build_num/retry

trigger_build(username, project, branch='master', revision=None, tag=None, parallel=None, params=None, vcs_type='github')[source]¶

Triggers a new build.

Note

tag and revision are mutually exclusive.
parallel is ignored for builds running on CircleCI 2.0

Parameters:

username – Organization or user name.
project – Case sensitive repo name.
branch – The branch to build. Defaults to master.
revision – The specific git revision to build. Default is null and the head of the branch is used. Can not be used with the tag parameter.
tag – The git tag to build. Default is null. Cannot be used with the tag parameter.
parallel (int) – The number of containers to use to run the build. Default is null and the project default is used.
params (dict) – Optional build parameters.
vcs_type – Defaults to github. On circleci.com you can also pass in bitbucket.

Endpoint:: POST: project/:vcs-type/:username/:project/tree/:branch

Experimental API Object¶

CircleCI Experimental API Module

Warning

All methods here work against undocumented and unsupported aspects of the CircleCI API. Subject to change at any moment. Use at your own risk.

copyright:	2017 by Lev Lazinskiy
license:	MIT, see LICENSE for more details.

class circleci.experimental.Experimental(token, url='https://circleci.com/api/v1.1')[source]¶

Experimantal CircleCI API

Instantiate a new circleci.Api object.

Parameters:	url – The URL to the CircleCI instance. Defaults to https://circleci.com/api/v1.1. If you are running CircleCI server, the API is available at the same endpoint of your own installation url. i.e (https://circleci.yourcompany.com/api/v1.1). token – Your CircleCI API token.

retry_no_cache(username, project, build_num, vcs_type='github')[source]¶

Retries a build without cache

Parameters:	username – Org or user name. project – Case sensitive repo name. build_num (int) – Build number. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Endpoint:: POST: /project/:vcs-type/:username/:project/:build_num/retry

Errors¶

CircleCI API Error Module

copyright:	2017 by Lev Lazinskiy
license:	MIT, see LICENSE for more details

class circleci.error.CircleCIException(argument)[source]¶

Base class for CircleCI exceptions

Parameters:	argument – The argument that was passed into the function.

class circleci.error.BadVerbError(argument)[source]¶

Exception raises for bad HTTP verb

Parameters:	argument – The argument that was passed into the function.

message = "verb must be one of 'GET', 'POST', or 'DELETE'"¶

class circleci.error.BadKeyError(argument)[source]¶

Exception raises for bad Key Type

Parameters:	argument – The argument that was passed into the function.

message = "key must be one of 'deploy-key' or 'github-user-key'"¶

class circleci.error.InvalidFilterError(argument, filter_type)[source]¶

Exception raises for an invalid filter

Parameters:	argument – The argument that was passed into the function. filter_type – Filter for status or artifacts.

filter_message = "status_filter must be one of 'completed''successful', 'failed', or 'running'"¶

artifacts_message = "must be one of 'completed', 'successful', or 'failed'"¶

Utilities¶

Refernce for various utility modules in circleci.py

Utilities¶

version module¶

circleci.version¶

Helper file to set version in various places.

New in version 1.2.0.

circleci.version.VERSION = '1.2.2'¶: Current version of circleci.py.

circleci.version.get_short_version()[source]¶

Format “short” version in the form of X.Y

Return type:	`str`
Returns:	short version

SDK Reference¶

SDK¶

SDK Object¶

CircleCI SDK Module

New in version 1.2.0.

copyright:	2019 by Lev Lazinskiy
license:	MIT, see LICENSE for more details.

class circleci.sdk.SDK(apiclient, logger=None)[source]¶

CircleCI SDK

An SDK module that allows you to do interesting or complex things using the CircleCI API.

Instantiate a new circleci.SDK object.

Parameters:	apiclient (`Api`) – an instance of circleci.Api

build_singleton(username, project, vcs_type='github')[source]¶

Force builds for a specific project to run one at a time.

This method gets a build summary for a specific project to see all currently running builds. It filters out the current running build. It pauses execution until the project has no more running builds.

It will recheck for running builds every 15 seconds.

Parameters:	username – Org or user name. project – Case sensitive repo name. vcs_type – Defaults to github. On circleci.com you can also pass in `bitbucket`.

Changed in version 1.2.2: fixed bug where current build was counted toward running builds.

Developer Documentation¶

Installing Development Environment¶

Your life will be a lot better if you use a virtualenv when working with python.

Fork and Clone this repo
Install python-pip and virtualenv if you do not already have it.
Create a new virtualenv with virtualenv -p python3 env.
Actiavte the new virtualenv with source env/bin/activate.
Run make dev
Hack away!

Running Tests¶

Tests can be found in the tests directory.

You can run tests with make tests.

If you want to run a specific test file you can do so with:

python -m unittest tests/circle/test_$MODULE.py

This project has two main types of tests.

Unit tests. These are tests of specific functions using mocked API data.
Integration tests. These are tests that actually hit the CircleCI API. Unfortunately, due to the way that permissions work most of the currently written tests will only work properly for the levlaz user and token.

Code Coverage¶

This project attempts to have 100% code coverage. when you run make test code coverage is automatically ran. You can view the code coverage report locally by opening up the index.html file in the htmlcov directory that gets created when you run make test.

Documentation¶

This project uses sphinx for documentation. You can generate the latest docs locally by running make docs. You can then view them by opening up the index.html file in the docs/build/html directory.

Linting and Style¶

This project follows the PEP 8 style guidelines. You can install pylint in order to ensure that all of your code is compliant with this standard.

Changelog¶

Here you can see the full list of changes between each circleci.py release.

Version 1.2.2¶

Note

What happened to 1.2.0 and 1.2.1?

Due to a bug in the SDK, these releases has been unpublished from pypi. The bug was an issue in the build_singleton logic that did not exclude the current build, therefore putting us into an infinite loop. Ironically, I did not test this on CircleCI so this is why the bug was not found in testing. Since pypi does not allow re-publishing versions (for good reason) I had to unpublish 1.2.0 and 1.2.1

In the future, I may start to use the -dev publishing model to try to verify this behavior ahead of time.

Released on March 10, 2019

Add SDK module which allows folks to do intersting or complicated things using the API.
Add demo modules which shows some sample usage of the API and SDK.
Add version module which provides some helpers to get the correct version of circleci.py in various places.

Version 1.1.3¶

Released on November 19, 2018

Fix a bug where triggering a build with parameters was not working. Thanks to @hush-hush for the contribution.
Update CI configuration for CircleCI 2.1. Thanks to @felicianotech for the contribution.
Added smoke tests to test out all supported versions of Python3.

Version 1.1.2¶

Released on August 29, 2018

Minor patch release, which unpins the request library. Thanks to @r1b for the contribution.

Version 1.1.1¶

Released on October 29, 2017

100% Code Coverage
Add Sphinx and upload docs to readthedocs.org
Create CD pipeline to pypi when using git tags
Implement additional API endpoints
- Add Heroku Key #18
- Test Metadata #17
- Update trigger build to handle optional build parameters #12
- Get artifacts of latest build #4
- Update retry build to include retry with SSH #5
- Add ability to download artifacts #3
- Work with Env Vars
  
  List #13
  
  Add #14
  
  Get #15
  
  Delete #16

Version 1.1.0¶

Released on October 25, 2017

Basic project tooling put into place.
- Continuous Integration with CircleCI
- Packaging and uploading to PyPI
- Code Coverage
- Testing with unittest
Basic Documentation in place
Add support for using the API with a token with both circleci.com and CircleCI Server
Add support for most basic API endpoints that deal with projects and builds
Add Experimental API for using API methods that are undocumented

Attribution¶

circleci.py relies on the wonderful requests library for all HTTP requests. This library is licensed under the Apache License, Version 2.0.
A majority of the API doc strings are adapted from the official CircleCI API documentation which is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.