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)[source]¶ 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
[source]¶ Bases:
object
Root class for all authentication mix-ins.
-
PROVIDED
= {}¶
-
REQUIRED
= {}¶
-
-
class
flash_services.auth.
BasicAuthHeaderMixin
(*, username, password, **kwargs)[source]¶ 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)[source]¶ Bases:
flash_services.auth.HeaderMixin
Mix-in class for bearer token authentication.
-
PROVIDED
= {}¶
-
REQUIRED
= {'api_token'}¶
-
-
class
flash_services.auth.
HeaderMixin
(*, api_token, **kwargs)[source]¶ Bases:
flash_services.auth.TokenAuthMixin
Mix-in class for implementing header authentication.
-
PROVIDED
= {}¶
-
REQUIRED
= {'api_token'}¶
-
headers
¶ Add authentication header.
-
-
class
flash_services.auth.
TokenAuthMixin
(*, api_token, **kwargs)[source]¶ Bases:
flash_services.auth.AuthMixin
Mix-in class for implementing token authentication.
-
PROVIDED
= {}¶
-
REQUIRED
= {'api_token'}¶
-
-
class
flash_services.auth.
Unauthenticated
[source]¶ Bases:
flash_services.auth.AuthMixin
No-op mix-in class for unauthenticated services.
-
PROVIDED
= {}¶
-
REQUIRED
= {}¶
-
flash_services.buddy module¶
Defines the Buddy CI service integration.
-
class
flash_services.buddy.
Buddy
(*, domain, pipeline_id, project_name, **kwargs)[source]¶ Bases:
flash_services.auth.BearerAuthHeaderMixin
,flash_services.core.ContinuousIntegrationService
Show the current build status on Buddy.
Parameters: -
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)[source]¶ 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)[source]¶ 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.codeship module¶
Defines the Codeship CI service integration.
-
class
flash_services.codeship.
Codeship
(*, project_id, **kwargs)[source]¶ Bases:
flash_services.auth.UrlParamMixin
,flash_services.core.ContinuousIntegrationService
Show the current build status on Codeship.
Parameters: -
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'¶
-
flash_services.core module¶
Core service description.
-
class
flash_services.core.
ContinuousIntegrationService
(**kwargs)[source]¶ Bases:
flash_services.core.Service
Service subclass for common CI behaviour.
-
FRIENDLY_NAME
= 'ContinuousIntegrationService'¶
-
PROVIDED
= {}¶
-
REQUIRED
= {}¶
-
TEMPLATE
= 'ci-section'¶
-
-
class
flash_services.core.
CustomRootMixin
(*, root, **kwargs)[source]¶ Bases:
object
Mix-in class for implementing custom service roots.
-
PROVIDED
= {}¶
-
REQUIRED
= {'root'}¶
-
ROOT
= ''¶
-
-
class
flash_services.core.
Service
(**kwargs)[source]¶ Bases:
object
Abstract base class for services.
-
PROVIDED
= {}¶
-
static
calculate_timeout
(http_date)[source]¶ 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)[source]¶ 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.
-
url
¶ Generate the URL for the service request.
-
url_builder
(endpoint, *, root=None, params=None, url_params=None)[source]¶ Create a URL for the specified endpoint.
Parameters: Returns: The resulting URL.
Return type:
-
url_params
¶
-
-
class
flash_services.core.
ServiceMeta
[source]¶ Bases:
abc.ABCMeta
,flash_services.core.MixinMeta
Metaclass to simplify configuration.
-
class
flash_services.core.
ThresholdMixin
(*, ok_threshold=None, neutral_threshold=None, **kwargs)[source]¶ 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
= {}¶
-
flash_services.coveralls module¶
Defines the GitHub service integration.
-
class
flash_services.coveralls.
Coveralls
(*, vcs_name, account, repo, **kwargs)[source]¶ 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 to80
). - neutral_threshold (
int
, optional) – The minimum coverage for neutral tile status (defaults to50
).
-
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)[source]¶ 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)[source]¶ 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)[source]¶ Determine the health of the last build.
Parameters: last_build ( dict
) – The last build.Returns: The health rating. Return type: str
-
url_params
¶
- vcs_name (
flash_services.github module¶
Defines the GitHub service integration.
-
class
flash_services.github.
GitHub
(*, account, repo, branch=None, **kwargs)[source]¶ Bases:
flash_services.auth.BasicAuthHeaderMixin
,flash_services.core.VersionControlService
Show the current status of a GitHub repository.
Parameters: -
ENDPOINT
= '/repos/{repo_name}/commits'¶
-
FRIENDLY_NAME
= 'GitHub'¶
-
PROVIDED
= {}¶
-
REQUIRED
= {'account', 'password', 'repo', 'username'}¶
-
ROOT
= 'https://api.github.com'¶
-
classmethod
format_commit
(commit)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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
- The health of the service, either
-
url_params
¶
-
flash_services.jenkins module¶
Defines the Jenkins CI service integration.
-
class
flash_services.jenkins.
Jenkins
(*, job, **kwargs)[source]¶ Bases:
flash_services.auth.BasicAuthHeaderMixin
,flash_services.core.CustomRootMixin
,flash_services.core.ContinuousIntegrationService
Show the current build status on a Jenkins instance.
Parameters: -
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)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
flash_services.auth.HeaderMixin
,flash_services.core.Service
Show the current status of a Pivotal Tracker project.
Parameters: -
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)[source]¶ 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)[source]¶ 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)[source]¶ 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
-
flash_services.travis module¶
Defines the Travis CI service integrations.
-
class
flash_services.travis.
TravisOS
(*, account, app, **kwargs)[source]¶ Bases:
flash_services.core.ContinuousIntegrationService
Show the current status of an open-source project.
Parameters: -
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)[source]¶ Re-format the build and commit data for the front-end.
Parameters: Returns: The re-formatted data.
Return type:
-
format_data
(data)[source]¶ 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)[source]¶ Bases:
flash_services.auth.HeaderMixin
,flash_services.travis.TravisOS
Show the current status of a pro (travis-ci.com) project.
Parameters: -
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
[source]¶ 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)[source]¶ Calculate the elapsed time for a service activity.
Parameters: Returns: - The start and end times and humanized elapsed
time.
Return type:
-
flash_services.utils.
estimate_time
(builds)[source]¶ 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)[source]¶ 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)[source]¶ 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_)[source]¶ 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)[source]¶ Extract the provided arguments from a class’s attrs.
Parameters: attrs ( dict
) – The attributes of a class.Returns: The provided arguments. Return type: set
Remove issue/tracker tags from a commit message.
Parameters: commit_message ( str
) – The commit message.Returns: The message with tags removed. Return type: str
-
flash_services.utils.
required_args
(attrs)[source]¶ 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)[source]¶ 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)[source]¶ 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