.. _MessageFormatter:

MessageFormatter
++++++++++++++++

.. py:currentmodule:: buildbot.reporters.message

This formatter is used to format messages in :ref:`Reportgen-BuildStatusGenerator` and
:ref:`Reportgen-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
    :py:meth:`buildAdditionalContext` in order to grab more context from the data API.

    .. py:method:: buildAdditionalContext(master, ctx)
        :noindex:

        :param master: the master object
        :param 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 :bb:rtype:`buildset` dictionary from data API.

``build``
    The :bb:rtype:`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 :bb:rtype:`builder` dictionary from the data API that describes the builder of the build.

    ``buildrequest``
        The :bb:rtype:`buildrequest` dictionary from the data API that describes the build request
        that the build was built for.

    ``buildset``
        The :bb:rtype:`buildset` dictionary from the data API that describes the buildset that the
        build was built for.

    ``parentbuild``
        The :bb:rtype:`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 :bb:rtype:`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 :bb:rtype:`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 :bb:rtype:`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 :bb:rtype:`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 :bb:rtype:`buildset` dictionary from data API.

``builds``
    A list of  :bb:rtype:`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(', ') }}``

.. _Jinja2: http://jinja.pocoo.org/docs/dev/templates/
