flash_services package

Module contents

The services that can be shown on a Flash dashboard.

flash_services.SERVICES = {'buddy': <class 'flash_services.buddy.Buddy'>, 'circleci': <class 'flash_services.circleci.CircleCI'>, 'codeship': <class 'flash_services.codeship.Codeship'>, 'coveralls': <class 'flash_services.coveralls.Coveralls'>, 'gh_actions': <class 'flash_services.github.GitHubActions'>, 'gh_issues': <class 'flash_services.github.GitHubIssues'>, 'ghe_actions': <class 'flash_services.github.GitHubEnterpriseActions'>, 'ghe_issues': <class 'flash_services.github.GitHubEnterpriseIssues'>, 'github': <class 'flash_services.github.GitHub'>, 'github_enterprise': <class 'flash_services.github.GitHubEnterprise'>, 'jenkins': <class 'flash_services.jenkins.Jenkins'>, 'tracker': <class 'flash_services.tracker.Tracker'>, 'travis': <class 'flash_services.travis.TravisOS'>, 'travis_pro': <class 'flash_services.travis.TravisPro'>}

The services available to the application.

Type:dict

flash_services.define_services(config)

Define the service settings for the current app.

Parameters:config (list) – The service configuration required. Returns:Configured services. Return type:collections.OrderedDict Raises:ValueError – If a non-existent service is requested.

Submodules

flash_services.auth module

Mix-in classes for implementing service authentication.

class flash_services.auth.AuthMixin

Bases: object

Root class for all authentication mix-ins.

PROVIDED = {}

REQUIRED = {}

class flash_services.auth.BasicAuthHeaderMixin(*, username, password, **kwargs)

Bases: flash_services.auth.HeaderMixin

Mix-in class for HTTP Basic auth.

PROVIDED = {'api_token'}

REQUIRED = {'password', 'username'}

class flash_services.auth.BearerAuthHeaderMixin(*, api_token, **kwargs)

Bases: flash_services.auth.HeaderMixin

Mix-in class for bearer token authentication.

PROVIDED = {}

REQUIRED = {'api_token'}

class flash_services.auth.HeaderMixin(*, api_token, **kwargs)

Bases: flash_services.auth.TokenAuthMixin

Mix-in class for implementing header authentication.

AUTH_HEADER = 'Authorization'

The name of the request header.

Type:str

PROVIDED = {}

REQUIRED = {'api_token'}

headers

Add authentication header.

class flash_services.auth.TokenAuthMixin(*, api_token, **kwargs)

Bases: flash_services.auth.AuthMixin

Mix-in class for implementing token authentication.

PROVIDED = {}

REQUIRED = {'api_token'}

TOKEN_ENV_VAR = None

The environment variable holding the token.

Type:str

class flash_services.auth.Unauthenticated

Bases: flash_services.auth.AuthMixin

No-op mix-in class for unauthenticated services.

PROVIDED = {}

REQUIRED = {}

class flash_services.auth.UrlParamMixin(*, api_token, **kwargs)

Bases: flash_services.auth.TokenAuthMixin

Mix-in class for implementing URL parameter authentication.

AUTH_PARAM = None

The name of the URL parameter.

Type:str

PROVIDED = {}

REQUIRED = {'api_token'}

url_params

flash_services.buddy module

Defines the Buddy CI service integration.

class flash_services.buddy.Buddy(*, domain, pipeline_id, project_name, **kwargs)

Bases: flash_services.auth.BearerAuthHeaderMixin, flash_services.core.ContinuousIntegrationService

Show the current build status on Buddy.

Parameters:

• api_token (str) – A valid token for the Buddy API.
• domain (str) – The domain of the Buddy project.
• pipeline_id (int) – The ID of the Buddy pipeline.
• project_name (str) – The name of the Buddy project.

ENDPOINT = '/workspaces/{domain}/projects/{project_name}/pipelines/{pipeline_id}/executions'

FRIENDLY_NAME = 'Buddy'

OUTCOMES = {'FAILED': 'failed', 'INPROGRESS': 'working', 'SUCCESSFUL': 'passed', 'TERMINATED': 'cancelled'}

PROVIDED = {}

REQUIRED = {'api_token', 'domain', 'pipeline_id', 'project_name'}

ROOT = 'https://api.buddy.works'

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

static get_message(build, commit)

Extract the message from the commit or comment.

Parameters:

• build (dict) – The JSON data from the response.
• commit (dict) – The JSON data from the response.

Returns:

The commit or comment message.

Return type:

str

static get_name(commit)

Extract the name from the author or committer.

Parameters:commit (dict) – The JSON data from the response. Returns:The author (or committer) name. Return type:str

flash_services.codeship module

Defines the Codeship CI service integration.

class flash_services.codeship.Codeship(*, project_id, **kwargs)

Bases: flash_services.auth.UrlParamMixin, flash_services.core.ContinuousIntegrationService

Show the current build status on Codeship.

Parameters:

• api_token (str) – A valid token for the Codeship API.
• project_id (int) – The ID of the Codeship project.

AUTH_PARAM = 'api_key'

ENDPOINT = '/projects/{project_id}.json'

FRIENDLY_NAME = 'Codeship CI'

OUTCOMES = {'cancelled': 'cancelled', 'error': 'failed', 'infrastructure_failure': 'crashed', 'stopped': 'cancelled', 'success': 'passed', 'testing': 'working'}

PROVIDED = {}

REQUIRED = {'api_token', 'project_id'}

ROOT = 'https://codeship.com/api/v1'

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

classmethod format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

flash_services.core module

Core service description.

class flash_services.core.ContinuousIntegrationService(**kwargs)

Bases: flash_services.core.Service

Service subclass for common CI behaviour.

FRIENDLY_NAME = 'ContinuousIntegrationService'

OUTCOMES = {}

Mapping from service to Flash outcomes.

Type:dict

PROVIDED = {}

REQUIRED = {}

TEMPLATE = 'ci-section'

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

class flash_services.core.CustomRootMixin(*, root, **kwargs)

Bases: object

Mix-in class for implementing custom service roots.

PROVIDED = {}

REQUIRED = {'root'}

ROOT = ''

url_builder(endpoint, *, root=None, params=None, url_params=None)

Create a URL for the specified endpoint.

Parameters:

• endpoint (str) – The API endpoint to access.
• root – (str, optional): The root URL for the service API.
• params – (dict, optional): The values for format into the created URL (defaults to None).
• url_params – (dict, optional): Parameters to add to the end of the URL (defaults to None).

Returns:

The resulting URL.

Return type:

str

class flash_services.core.MixinMeta

Bases: type

Metaclass for all mix-ins.

class flash_services.core.Service(**kwargs)

Bases: object

Abstract base class for services.

ENDPOINT = None

The endpoint URL template for the service API.

Type:str

FRIENDLY_NAME = None

The friendly name of the service.

Type:str

PROVIDED = {}

REQUIRED = {}

The service’s required configuration keys.

Type:set

ROOT = None

The root URL for the service API.

Type:str

TEMPLATE = 'undefined-section'

The name of the template to render.

Type:str

static calculate_timeout(http_date)

Extract request timeout from e.g. Retry-After header.

Note

Per RFC 2616#section-14.37, the Retry-After header can be either an integer number of seconds or an HTTP date. This function can handle either.

Parameters:http_date (str) – The date to parse. Returns:The timeout, in seconds. Return type:int

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

classmethod from_config(**config)

Manipulate the configuration settings.

headers

Get the headers for the service requests.

update()

Get the current state to display on the dashboard.

url

Generate the URL for the service request.

url_builder(endpoint, *, root=None, params=None, url_params=None)

Create a URL for the specified endpoint.

Parameters:

• endpoint (str) – The API endpoint to access.
• root – (str, optional): The root URL for the service API.
• params – (dict, optional): The values for format into the created URL (defaults to None).
• url_params – (dict, optional): Parameters to add to the end of the URL (defaults to None).

Returns:

The resulting URL.

Return type:

str

url_params

class flash_services.core.ServiceMeta

Bases: abc.ABCMeta, flash_services.core.MixinMeta

Metaclass to simplify configuration.

class flash_services.core.ThresholdMixin(*, ok_threshold=None, neutral_threshold=None, **kwargs)

Bases: object

Mix-in class for defining health thresholds.

NEUTRAL_THRESHOLD

The threshold beyond which the service is considered to be in an error state.

OK_THRESHOLD

The threshold beyond which the service is considered to be in a neutral state.

NEUTRAL_THRESHOLD = None

OK_THRESHOLD = None

PROVIDED = {}

REQUIRED = {}

class flash_services.core.VersionControlService(**kwargs)

Bases: flash_services.core.Service

Service subclass for common (D)VCS behaviour.

FRIENDLY_NAME = 'VersionControlService'

PROVIDED = {}

REQUIRED = {}

TEMPLATE = 'vcs-section'

classmethod format_commit(commit)

Format the raw commit from the service.

Parameters:commit (dict) – The raw commit from the service. Returns:The formatted commit. Return type:dict)

flash_services.coveralls module

Defines the GitHub service integration.

class flash_services.coveralls.Coveralls(*, vcs_name, account, repo, **kwargs)

Bases: flash_services.auth.Unauthenticated, flash_services.core.ThresholdMixin, flash_services.core.Service

Show the current status of a Coveralls repository.

Parameters:

• vcs_name (str) – The name of the linked VCS (e.g. 'github').
• account (str) – The name of the account.
• repo (str) – The name of the repository.
• ok_threshold (int, optional) – The minimum coverage for OK tile status (defaults to 80).
• neutral_threshold (int, optional) – The minimum coverage for neutral tile status (defaults to 50).

repo_name

The repository name, in the format vcs_name/account/repo.

Type:str

ENDPOINT = '/{repo_name}.json'

FRIENDLY_NAME = 'Coveralls'

NEUTRAL_THRESHOLD = 50

OK_THRESHOLD = 80

PROVIDED = {}

REQUIRED = {'account', 'repo', 'vcs_name'}

ROOT = 'https://coveralls.io'

TEMPLATE = 'coveralls-section'

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

health(last_build)

Determine the health of the last build.

Parameters:last_build (dict) – The last build. Returns:The health rating. Return type:str

url_params

flash_services.github module

Defines the GitHub service integration.

class flash_services.github.GitHub(*, account, repo, branch=None, **kwargs)

Bases: flash_services.auth.BasicAuthHeaderMixin, flash_services.core.VersionControlService

Show the current status of a GitHub repository.

Parameters:

• api_token (str) – A valid token for the GitHub API.
• account (str) – The name of the account.
• repo (str) – The name of the repository.
• branch (str, optional) – The branch to get commit data from.

repo_name

The repository name, in the format account/repo.

Type:str

ENDPOINT = '/repos/{repo_name}/commits'

FRIENDLY_NAME = 'GitHub'

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'username'}

ROOT = 'https://api.github.com'

classmethod format_commit(commit)

Re-format the commit data for the front-end.

Parameters:commit (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (list) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

headers

Add authentication header.

name

The full name of the repo, including branch if provided.

url_params

class flash_services.github.GitHubActions(*, account, repo, branch=None, **kwargs)

Bases: flash_services.core.ContinuousIntegrationService, flash_services.github.GitHub

Show the current build status on GitHub Actions.

ENDPOINT = '/repos/{repo_name}/actions/runs'

FRIENDLY_NAME = 'GitHub Actions'

OUTCOMES = {'action_required': 'crashed', 'cancelled': 'cancelled', 'failure': 'failed', 'in_progress': 'working', 'neutral': 'passed', 'queued': 'working', 'skipped': 'cancelled', 'stale': 'crashed', 'success': 'passed', 'timed_out': 'crashed'}

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'username'}

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

url_params

class flash_services.github.GitHubEnterprise(*, root, **kwargs)

Bases: flash_services.core.CustomRootMixin, flash_services.github.GitHub

Current status of GHE repositories.

FRIENDLY_NAME = 'GitHub'

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'root', 'username'}

class flash_services.github.GitHubEnterpriseActions(*, root, **kwargs)

Bases: flash_services.core.CustomRootMixin, flash_services.github.GitHubActions

Actions from GHE repositories.

FRIENDLY_NAME = 'GitHub Actions'

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'root', 'username'}

class flash_services.github.GitHubEnterpriseIssues(*, root, **kwargs)

Bases: flash_services.core.CustomRootMixin, flash_services.github.GitHubIssues

Issues and pull requests from GHE repositories.

FRIENDLY_NAME = 'GitHub Issues'

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'root', 'username'}

class flash_services.github.GitHubIssues(**kwargs)

Bases: flash_services.core.ThresholdMixin, flash_services.github.GitHub

Show the current status of GitHub issues and pull requests.

ENDPOINT = '/repos/{repo_name}/issues'

FRIENDLY_NAME = 'GitHub Issues'

NEUTRAL_THRESHOLD = 30

OK_THRESHOLD = 7

PROVIDED = {}

REQUIRED = {'account', 'password', 'repo', 'username'}

TEMPLATE = 'gh-issues-section'

format_data(data)

Re-format the response data for the front-end.

Parameters:data (list) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

static half_life(issues)

Calculate the half life of the service’s issues.

Parameters:issues (list) – The service’s issue data. Returns:The half life of the issues. Return type:datetime.timedelta

health_summary(half_life)

Calculate the health of the service.

Parameters:half_life (datetime.timedelta) – The half life of the service’s issues. Returns:

The health of the service, either 'ok',

'neutral' or 'error'.

Return type:str

url_params

flash_services.jenkins module

Defines the Jenkins CI service integration.

class flash_services.jenkins.Jenkins(*, job, **kwargs)

Bases: flash_services.auth.BasicAuthHeaderMixin, flash_services.core.CustomRootMixin, flash_services.core.ContinuousIntegrationService

Show the current build status on a Jenkins instance.

Parameters:

• username (str) – A valid username for the Jenkins instance.
• password (str) – A valid password for the Jenkins instance.
• root (str) – The root URL for the Jenkins instance.
• job (str) – The name of the job (must match the job URL).

ENDPOINT = '/job/{job}/api/json'

FRIENDLY_NAME = 'Jenkins'

OUTCOMES = {None: 'working', 'WORKING': 'working', 'FAILURE': 'failed', 'UNSTABLE': 'failed', 'SUCCESS': 'passed', 'ABORTED': 'cancelled'}

PROVIDED = {}

REQUIRED = {'job', 'password', 'root', 'username'}

TREE_PARAMS = 'name,builds[building,timestamp,duration,result,description,changeSets[items[author[fullName],comment]]]'

Definition of JSON tree to return.

Type:str

classmethod format_build(build)

Re-format the build data for the front-end.

Parameters:build (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

Note

Jenkins returns timestamps in milliseconds, and always has a zero duration for the in-progress build.

classmethod format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

url_params

flash_services.tracker module

Defines the Pivotal Tracker service integration.

class flash_services.tracker.Tracker(*, project_id, **kwargs)

Bases: flash_services.auth.HeaderMixin, flash_services.core.Service

Show the current status of a Pivotal Tracker project.

Parameters:

• api_token (str) – A valid token for the Tracker API.
• project_id (int) – The ID of the Tracker project.

project_version

The current project version, used to invalidate the cached data as appropriate.

Type:int

AUTH_HEADER = 'X-TrackerToken'

FRIENDLY_NAME = 'Pivotal Tracker'

PROVIDED = {}

REQUIRED = {'api_token', 'project_id'}

ROOT = 'https://www.pivotaltracker.com/services/v5'

TEMPLATE = 'tracker-section'

details(iteration)

Update the project data with more details.

Parameters:iteration (int) – The current iteration number. Returns:Additional detail on the current iteration. Return type:dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

static story_summary(stories)

Get a summary of stories in each state.

Parameters:stories (list) – A list of stories. Returns:

Summary of points by

story state.

Return type:collections.defaultdict

update()

Get the current state to display on the dashboard.

flash_services.travis module

Defines the Travis CI service integrations.

class flash_services.travis.TravisOS(*, account, app, **kwargs)

Bases: flash_services.core.ContinuousIntegrationService

Show the current status of an open-source project.

Parameters:

• account (str) – The name of the account.
• app (str) – The name of the application.

repo

The repository name, in the format account/application.

Type:str

ENDPOINT = '/repos/{repo}/builds'

FRIENDLY_NAME = 'Travis CI'

OUTCOMES = {'canceled': 'cancelled', 'created': 'working', 'errored': 'crashed', 'failed': 'failed', 'passed': 'passed', 'started': 'working'}

PROVIDED = {}

REQUIRED = {'account', 'app'}

ROOT = 'https://api.travis-ci.org'

classmethod format_build(build, commit)

Re-format the build and commit data for the front-end.

Parameters:

• build (dict) – The build data from the response.
• commit (dict) – The commit data from the response.

Returns:

The re-formatted data.

Return type:

dict

format_data(data)

Re-format the response data for the front-end.

Parameters:data (dict) – The JSON data from the response. Returns:The re-formatted data. Return type:dict

headers

Get the headers for the service requests.

class flash_services.travis.TravisPro(*, api_token, **kwargs)

Bases: flash_services.auth.HeaderMixin, flash_services.travis.TravisOS

Show the current status of a pro (travis-ci.com) project.

Parameters:

• account (str) – The name of the account.
• api_token (str) – The API token.
• app (str) – The name of the application.

repo

The repository name, in the format account/application.

Type:str

FRIENDLY_NAME = 'Travis CI'

PROVIDED = {}

REQUIRED = {'account', 'api_token', 'app'}

ROOT = 'https://api.travis-ci.com'

flash_services.utils module

Useful utility functions for services.

flash_services.utils.GITHUB_ISSUE = re.compile('\n (?: # one of:\n fix(?:e(?:s|d))? # fix, fixes or fixed\n | close(?:s|d)? # close, closes or closed\n | resolve(?:s|d)? # resolve, resolves or r, re.IGNORECASE|re.VERBOSE)

Pattern for commit comment issue ID format, per GitHub documentation.

class flash_services.utils.Outcome

Bases: object

Possible outcomes for a CI build.

CANCELLED = 'cancelled'

CRASHED = 'crashed'

FAILED = 'failed'

PASSED = 'passed'

WORKING = 'working'

flash_services.utils.TRACKER_STORY = re.compile('\n \\[(?:\n (?:\n finish(?:e(?:s|d))? # finish, finishes or finished\n | complete(?:s|d)? # complete, completes or completed\n | fix(?:e(?:s|d))? # fix, f, re.IGNORECASE|re.VERBOSE)

Pattern for commit hook story ID format, per Tracker documentation.

flash_services.utils.elapsed_time(start, end)

Calculate the elapsed time for a service activity.

Parameters:

• start (str) – The activity start time.
• end (str) – The activity end time.

Returns:

The start and end times and humanized elapsed

time.

Return type:

tuple

flash_services.utils.estimate_time(builds)

Update the working build with an estimated completion time.

Takes a simple average over the previous builds, using those whose outcome is 'passed'.

Parameters:builds (list) – All builds.

flash_services.utils.friendlier(func)

Replace numbers to make functions friendlier.

Parameters:func – The function to wrap. Returns:A wrapper function applying _numeric_words().

flash_services.utils.health_summary(builds)

Summarise the health of a project based on builds.

Parameters:builds (list) – List of builds. Returns:The health summary. Return type:str

flash_services.utils.naturaldelta(*args, **kwargs)

Wrapper function to apply _numeric_words.

flash_services.utils.naturaltime(*args, **kwargs)

Wrapper function to apply _numeric_words.

flash_services.utils.occurred(at_)

Calculate when a service event occurred.

Parameters:at (str) – When the event occurred. Returns:The humanized occurrence time. Return type:str

flash_services.utils.provided_args(attrs)

Extract the provided arguments from a class’s attrs.

Parameters:attrs (dict) – The attributes of a class. Returns:The provided arguments. Return type:set

flash_services.utils.remove_tags(commit_message)

Remove issue/tracker tags from a commit message.

Note

Currently implemented for Tracker and GitHub commit messages.

Parameters:commit_message (str) – The commit message. Returns:The message with tags removed. Return type:str

flash_services.utils.required_args(attrs)

Extract the required arguments from a class’s attrs.

Parameters:attrs (dict) – The attributes of a class. Returns:The required arguments. Return type:set

flash_services.utils.safe_parse(time)

Parse a string without throwing an error.

Parameters:time (str) – The string to parse. Returns:The parsed datetime. Return type:datetime.datetime

flash_services.utils.to_utc_timestamp(date_time)

Convert a naive or timezone-aware datetime to UTC timestamp.

Parameters:date_time (datetime.datetime) – The datetime to convert. Returns:The timestamp (in seconds). Return type:int