ci_diff_helper.travis module

Set of utilities for dealing with Travis CI.

This module provides a custom configuration type Travis for the Travis CI system.

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.

Travis Configuration Type

When running in Travis, you can automatically detect your current environment and get the configuration object:

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

To use the Travis configuration type directly:

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

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

>>> config = ci_diff_helper.Travis()
>>> config.event_type
<TravisEventType.pull_request: 'pull_request'>
>>> config.slug
'organization/repository'
>>> config.repo_url
'https://github.com/organization/repository'
>>> config.pr
1234
>>> config.tag is None
True
>>> 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:

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

Though the base property can be useful as a diffbase of a given commit, it may be inappropriate. In a “push” build, base will be computed from the TRAVIS_COMMIT_RANGE environment variable, and this value is not particularly reliable. Instead, merged_pr provides a way to determine the PR that was merged:

>>> config.is_merge
True
>>> config.merged_pr
1355

class ci_diff_helper.travis.Travis

Bases: ci_diff_helper._config_base.Config

Represent Travis state and cache return values.

active

bool – Indicates if currently running in the target CI system.

base

str – The git object that current build is changed against.

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

This can be used in combination with get_changed_files() to determine files that need to be linted, tested or inspected in some other way:

>>> config
<Travis (active=True)>
>>> config.base
'master'
>>> ci_diff_helper.get_changed_files('HEAD', config.base)
['/path/to/your/git_checkout/project/_supporting.py']

Note

This will throw an OSError on the very first “push” build for a branch. This is because Travis leaves the value empty in builds triggered by the initial commit of a new branch.

Warning

This property is only meant to be used in a “pull request” or “push” build.

branch

bool – Indicates the current branch in the target CI system.

This may indicate the active branch or the base branch of a pull request.

event_type

bool – Indicates if currently running in Travis.

in_pr

bool – 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.

is_merge

bool – Indicates if the HEAD commit is a merge commit.

merged_pr

int – The pull request corresponding to a merge commit at HEAD.

If not currently in a push build, returns None. If the HEAD commit is not a merge commit, returns None.

Note

This only uses the git checkout to determine the pull request ID. A more comprehensive check would involve veriying the ID by using the GitHub API.

Warning

This property is only meant to be used in a “pull request” or “push” build.

pr

int – The current Travis pull request (if any).

If there is no active pull request, returns None.

repo_url

str – The URL of the current repository being built.

Of the form https://github.com/{organization}/{repository}.

slug

str – The current slug in the Travis build.

Of the form {organization}/{repository}.

tag

str – The git tag of the current Travis build.

Note

We only expect the TRAVIS_TAG environment variable to be set during a tag “push” build, but we don’t verify that we are in a push build before checking for the tag.

class ci_diff_helper.travis.TravisEventType

Bases: enum.Enum

Enum representing all possible Travis event types.

api = 'api'

cron = 'cron'

pull_request = 'pull_request'

push = 'push'