ci-diff-helper

Diff Helper for Continuous Integration (CI) Services.

For an open source project, running unit tests, system tests, torture tests, fuzz tests, integration tests, code quality checks, etc. can quickly become a large task.

In order to limit the amount of time and resources that these jobs require, this tool provides a way to determine which files have changed and provides a Python API for these changes. In addition, this library provides the corresponding commit SHA (or other artifact) that is used as the diffbase.

The library supports (planned)

Note

When configuring your CI environment, it may be useful to set the GITHUB_OAUTH_TOKEN environment variable (GH_TOKEN). By authenticating in GitHub API requests, rate limiting can be avoided. Unauthenticated requests will be subject to rate limiting across the entire CI system.

To use this in your project first install:

$ pip install --upgrade ci-diff-helper

Once you’ve done that, you can use some basic functions (in_travis(), in_travis_pr() and travis_branch()) to get information about your current environment.

>>> import ci_diff_helper
>>> ci_diff_helper.in_travis()
True
>>> ci_diff_helper.in_travis_pr()
True
>>> ci_diff_helper.travis_branch()
'master'

While these functions are convenient, they are “one-shot”, i.e. they compute the value and return it, but don’t cache the computed value.

Instead, a long-lived configuration object (Travis) is provided with the same functionality, but also caches the returned values and uses them to compute other useful values.

>>> import ci_diff_helper
>>> config = ci_diff_helper.Travis()
>>> config.active
True
>>> config.in_pr
True
>>> config.branch
'master'

In addition this configuration provides extra features for determining a diffbase.

>>> import ci_diff_helper
>>> config = ci_diff_helper.Travis()
>>> config.event_type
<TravisEventType.pull_request: 'pull_request'>
>>> config.slug
'organization/repository'
>>> config.pr
1234
>>> config.base
'master'

Not only is this object valuable during a pull request build, it can also be used to find relevant information in a “push” build:

>>> import ci_diff_helper
>>> config = ci_diff_helper.Travis()
>>> config.event_type
<TravisEventType.push: 'push'>
>>> config.pr is None
True
>>> config.base
'4ad7349dc7223ebc02175a16dc577a013044a538'

ci_diff_helper.environment_vars module

Comprehensive list of environment variables used in ci-diff-helper.

These environment variables are core this library. They are used to detect the current environment.

For more details, see the Travis env docs.

ci_diff_helper.environment_vars.GH_TOKEN = 'GITHUB_OAUTH_TOKEN'

GitHub OAuth 2.0 token.

This environment variable must be used to authenticate to the GitHub API. Making unauthenticated requests on a Continuous Integration server will typically be rate limited.

ci_diff_helper.environment_vars.IN_TRAVIS_ENV = 'TRAVIS'

Indicates if running in Travis.

ci_diff_helper.environment_vars.TRAVIS_BRANCH_ENV = 'TRAVIS_BRANCH'

Indicates the active Travis branch.

In a “push” build, this is the branch that was pushed while in a “pull request” build it is the branch that a pull request is against.

ci_diff_helper.environment_vars.TRAVIS_EVENT_TYPE_ENV = 'TRAVIS_EVENT_TYPE'

Indicates the type of build that is occurring.

ci_diff_helper.environment_vars.TRAVIS_PR_ENV = 'TRAVIS_PULL_REQUEST'

Indicates which Travis pull request we are in.

Is an integer when in a pull request or “false” when not.

ci_diff_helper.environment_vars.TRAVIS_RANGE_ENV = 'TRAVIS_COMMIT_RANGE'

The range of commits changed in the current build.

This is not particularly useful in a PR build.

ci_diff_helper.environment_vars.TRAVIS_SLUG_ENV = 'TRAVIS_REPO_SLUG'

The GitHub repository slug for the current Travis build.

A slug is of the form {organization}/{repository}.

ci_diff_helper.git_tools module

Helpers for interacting with git.

ci_diff_helper.git_tools.get_checked_in_files()[source]

Gets a list of files in the current git repository.

Effectively runs:

$ git ls-files ${GIT_ROOT}

and then finds the absolute path for each file returned.

Return type:list
Returns:List of all filenames checked into.
ci_diff_helper.git_tools.git_root()[source]

Return the root directory of the current git checkout.

Return type:str
Returns:Filesystem path to git checkout root.

ci_diff_helper.travis module

Set of utilities for dealing with Travis CI.

Since Travis only works with GitHub, the commands in this module are GitHub and git centric.

This module uses a selection of environment variables to detect the state of Travis configuration. See environment_vars for more details.

class ci_diff_helper.travis.Travis[source]

Bases: object

Represent Travis state and cache return values.

active

Indicates if currently running in Travis.

Return type:bool
base

The git object that current build is changed against.

The git object can be any of a branch name, tag or a commit SHA.

Return type:str
Raises:NotImplementedError – If not in a “pull request” or “push” build.
branch

Indicates if currently running in Travis.

Return type:bool
event_type

Indicates if currently running in Travis.

Return type:bool
in_pr

Indicates if currently running in Travis pull request.

This uses the TRAVIS_EVENT_TYPE environment variable to check if currently in a pull request. Though it doesn’t use the TRAVIS_PULL_REQUEST environment variable, checking that the value is set to an integer would be a perfectly valid approach.

Return type:bool
pr

The current Travis pull request (if any).

If there is no active pull request, returns None.

Return type:int
slug

The current slug in the Travis build.

Of the form {organization}/{repository}.

Return type:str
class ci_diff_helper.travis.TravisEventType[source]

Bases: enum.Enum

Enum representing all possible Travis event types.

api = <TravisEventType.api: 'api'>
cron = <TravisEventType.cron: 'cron'>
pull_request = <TravisEventType.pull_request: 'pull_request'>
push = <TravisEventType.push: 'push'>
ci_diff_helper.travis.in_travis()[source]

Detect if we are running in Travis.

See the Travis class for a more comprehensive way to determine the Travis configuration, with caching enabled. In particular, for this method, see Travis.active.

Return type:bool
Returns:Flag indicating if we are running on Travis.
ci_diff_helper.travis.in_travis_pr()[source]

Detect if we are running in a pull request on Travis.

See the Travis class for a more comprehensive way to determine the Travis configuration, with caching enabled. In particular, for this method, see Travis.in_pr.

Return type:bool
Returns:Flag indicating if we are in a pull request on Travis.
ci_diff_helper.travis.travis_branch()[source]

Get the current branch of the PR.

See the Travis class for a more comprehensive way to determine the Travis configuration, with caching enabled. In particular, for this method, see Travis.branch.

Note

This assumes we already know we are running in Travis during a PR.

Return type:str
Returns:The name of the branch the current pull request is changed against.