Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

2.5.14.6. MessageFormatter

This formatter is used to format messages in BuildStatusGenerator and BuildSetStatusGenerator.

It formats a message using the Jinja2 templating language and picks the template either from a string.

The constructor of the class takes the following arguments:

template_type

This indicates the type of the generated template. Use either ‘plain’ (the default) or ‘html’.

template

If set, specifies the template used to generate the message body. If not set, a default template will be used. The default template is selected according to template_type so it may make sense to specify appropriate template_type even if the default template is used.

subject

If set, specifies the template used to generate the message subject. In case of messages generated for multiple builds within a buildset (e.g. from within BuildSetStatusGenerator), the subject of the first message will be used. The is_buildset key of the context can be used to detect such case and adjust the message appropriately.

ctx

This is an extension of the standard context that will be given to the templates. Use this to add content to the templates that is otherwise not available.

Alternatively, you can subclass MessageFormatter and override the buildAdditionalContext in order to grab more context from the data API.

buildbot.reporters.message.buildAdditionalContext(master, ctx)

Parameters:

• master – the master object

• ctx – the context dictionary to enhance

Returns:

optionally deferred

default implementation will add self.ctx into the current template context

want_properties

This parameter (defaults to True) will extend the content of the given build object with the Properties from the build.

want_steps

This parameter (defaults to False) will extend the content of the given build object with information about the steps of the build. Use it only when necessary as this increases the overhead in terms of CPU and memory on the master.

want_logs

This parameter (defaults to False) will extend the content of the steps of the given build object with the log metadata of each steps from the build. This implies wantSteps to be True. Use it only when mandatory, as this greatly increases the overhead in terms of CPU and memory on the master.

want_logs_content

This parameter (defaults to False) controls whether to include log content together with log metadata as controlled by want_logs.

False disables log content inclusion. True enables log content inclusion for all logs. A list of strings specifies which logs to include. The logs can be included by name; or by step name and log name separated by dot character. If log name is specified, logs with that name will be included regardless of the step it is in. If both step and log names are specified, then logs with that name will be included only from the specific step.

want_logs_content being not False implies want_logs=True and want_steps=True.

Enabling want_logs_content dumps the full content of logs and may consume lots of memory and CPU depending on the log size.

extra_info_cb

This parameter (defaults to None) can be used to customize extra information that is passed to reporters. If set, this argument must be a function that returns a dictionary of dictionaries either directly or via a Deferred. The interpretation of the return value depends on the exact reporter being used.

Context (build)

In the case the message formatter is used to create message for a build the context that is given to the template consists of the following data:

results

The results of the build as an integer. Equivalent to build['results'].

result_names

A collection that allows accessing a textual identifier of build result. The intended usage is result_names[results].

The following are possible values: success, warnings, failure, skipped, exception, retry, cancelled.

buildername

The name of the builder. Equivalent to build['builder']['name']

mode

The mode argument that has been passed to the report generator.

workername

The name of the worker. Equivalent to the workername property of the build or <unknown> if it’s not available.

buildset

The buildset dictionary from data API.

build

The build dictionary from data API. The properties attribute is populated only if want_properties is set to True. It has the following extra properties:

builder

The builder dictionary from the data API that describes the builder of the build.

buildrequest

The buildrequest dictionary from the data API that describes the build request that the build was built for.

buildset

The buildset dictionary from the data API that describes the buildset that the build was built for.

parentbuild

The build dictionary from the data API that describes the parent build. This build is identified by the parent_buildid attribute of the buildset.

parentbuilder

The builder dictionary from the data API that describes the builder of the parent build.

url

URL to the build in the Buildbot UI.

prev_build

The build dictionary from the data API that describes previous build, if any. This attribute is populated only if wantPreviousBuild is set to True.

steps

A list of step dictionaries from the data API that describe steps in the build, if any. This attribute is populated only if wantSteps is set to True.

Additionally, if want_logs is set to True then the step dictionaries will contain logs attribute with a list of log dictionaries from the data API that describe the logs of the step. The log dictionaries will additionally contain url key with URL to the log in the web UI as the value.

Additionally, if want_logs_content is set to True then the log dictionaries will contain contents key with full contents of the log.

is_buildset

A boolean identifying whether the current message will form a larger message that describes multiple builds in a buildset. This mostly concerns generation of the subject as the message bodies will be merged.

projects

A string identifying the projects that the build was built for.

previous_results

Results of the previous build, if available, otherwise None.

status_detected

String that describes the build in terms of current build results, previous build results and mode.

build_url

URL to the build in the Buildbot UI.

buildbot_title

The title of the Buildbot instance as per c['title'] from the master.cfg

buildbot_url

The URL of the Buildbot instance as per c['buildbotURL'] from the master.cfg

blamelist

The list of users responsible for the build.

summary

A string that summarizes the build result.

sourcestamps

A string identifying the source stamps for which the build was made.

Context (buildset)

In the case the message formatter is used to create message for an buildset itself (see BuildSetCombinedStatusGenerator), the context that is given to the template consists of the following data:

results

The results of the buildset as an integer. Equivalent to build['results'].

result_names

A collection that allows accessing a textual identifier of build result. The intended usage is result_names[results].

The following are possible values: success, warnings, failure, skipped, exception, retry, cancelled.

mode

The mode argument that has been passed to the report generator.

buildset

The buildset dictionary from data API.

builds

A list of build dictionaries from data API. The builds are part of the buildset that is being formatted.

is_buildset

Always True.

projects

A string identifying the projects that the buildset was built for.

status_detected

String that describes the build in terms of current buildset results, previous build results and mode.

buildbot_title

The title of the Buildbot instance as per c['title'] from the master.cfg

buildbot_url

The URL of the Buildbot instance as per c['buildbotURL'] from the master.cfg

blamelist

The list of users responsible for the buildset.

sourcestamps

A string identifying the source stamps for which the buildset was made.

Examples

The following examples describe how to get some useful pieces of information from the various data objects:

Name of the builder that generated this event

{{ buildername }}

Title of the BuildMaster

{{ projects }}

MailNotifier mode

{{ mode }} (a combination of change, failing, passing, problem, warnings, exception, all)

URL to build page

{{ build_url }}

URL to Buildbot main page

{{ buildbot_url }}

Status of the build as string.

This require extending the context of the Formatter via the ctx parameter with: ctx={"statuses": util.Results}.

{{ statuses[results] }}

Build text

{{ build['state_string'] }}

Mapping of property names to (values, source)

{{ build['properties'] }}

For instance the build reason (from a forced build)

{{ build['properties']['reason'][0] }}

Worker name

{{ workername }}

List of responsible users

{{ blamelist | join(', ') }}