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_typeso it may make sense to specify appropriate- template_typeeven 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_buildsetkey 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 - buildAdditionalContextin 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.ctxinto the current template context
 
- want_properties
- This parameter (defaults to True) will extend the content of the given - buildobject with the Properties from the build.
- want_steps
- This parameter (defaults to False) will extend the content of the given - buildobject 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 - buildobject with the log metadata of each steps from the build. This implies- wantStepsto 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.- Falsedisables log content inclusion.- Trueenables 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_contentbeing not- Falseimplies- want_logs=Trueand- 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 - workernameproperty of the build or- <unknown>if it’s not available.
- buildset
- The - buildsetdictionary from data API.
- build
- The - builddictionary from data API. The- propertiesattribute is populated only if- want_propertiesis set to- True. It has the following extra properties:- builder
- The - builderdictionary from the data API that describes the builder of the build.
- buildrequest
- The - buildrequestdictionary from the data API that describes the build request that the build was built for.
- buildset
- The - buildsetdictionary from the data API that describes the buildset that the build was built for.
- parentbuild
- The - builddictionary from the data API that describes the parent build. This build is identified by the- parent_buildidattribute of the buildset.
- parentbuilder
- The - builderdictionary from the data API that describes the builder of the parent build.
- url
- URL to the build in the Buildbot UI. 
- prev_build
- The - builddictionary from the data API that describes previous build, if any. This attribute is populated only if- wantPreviousBuildis set to- True.
- steps
- A list of - stepdictionaries from the data API that describe steps in the build, if any. This attribute is populated only if- wantStepsis set to- True.- Additionally, if - want_logsis set to- Truethen the step dictionaries will contain- logsattribute with a list of- logdictionaries from the data API that describe the logs of the step. The log dictionaries will additionally contain- urlkey with URL to the log in the web UI as the value.- Additionally, if - want_logs_contentis set to- Truethen the log dictionaries will contain- contentskey 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 - buildsetdictionary from data API.
- builds
- A list of - builddictionaries 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 - ctxparameter 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(', ') }}