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)


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 automatically detect your current environment and get a configuration object with information about your environment:

>>> import ci_diff_helper
>>> config = ci_diff_helper.get_config()
>>> config
<CircleCI (active=True)>

Common Configuration Properties

Long-lived configuration objects are provided as an interface for CI system information. These config objects cache the returned values for each property and use them to compute other useful values.

Each such configuration type (e.g. AppVeyor, CircleCI, Travis) has a common set of properties.

>>> config
<CircleCI (active=True)>
>>> config.branch
>>> config.tag is None

All configuration types can also be used to detect if a merge commit is currently being built:

>>> config.is_merge

git tools

The helpers git_root(), get_checked_in_files() and get_changed_files() are provided as tools for a git-based project.

The most relevant of these for finding diffs is get_changed_files(). For example, to find changed files between a current checkout and an upstream branch:

>>> ci_diff_helper.get_changed_files('HEAD', 'upstream/master')

In addition, being able to get the root of the current git checkout may be needed to collect files, execute scripts, etc. Getting all checked in files can be useful for things like test collection, file linting, etc.

>>> ci_diff_helper.git_root()
>>> ci_diff_helper.get_checked_in_files()

Get configuration for the current environment.

Returns:A configuration class for the current environment.
Return type:Union [ AppVeyor, CircleCI, Travis ]
Raises:OSError – If no (unique) environment is active.