.. bb:reporter:: HttpStatusPush

HttpStatusPush
++++++++++++++

.. py:currentmodule:: buildbot.reporters

.. code-block:: python

    from buildbot.plugins import reporters
    sp = reporters.HttpStatusPush(serverUrl="http://example.com/submit")
    c['services'].append(sp)

:class:`HttpStatusPush` sends HTTP POST requests to ``serverUrl``.
The body of request contains json-encoded data of the build as returned by the data API.
It is useful to create a status front end outside of Buildbot for better scalability.

It requires either `txrequests`_ or `treq`_ to be installed to allow interaction with http server.

.. note::

   The json data object sent is completely different from the one that was generated by 0.8.x buildbot.
   It is indeed generated using data api.

.. py:class:: HttpStatusPush(serverUrl, user=None, password=None, auth=None, headers=None, generators=None, format_fn=None, builders=None, wantProperties=False, wantSteps=False, wantPreviousBuild=False, wantLogs=False, debug=None, verify=None)

    :param string serverUrl: the url where to do the HTTP POST request
    :param string user: the BasicAuth user to post as
    :param string password: the BasicAuth user's password (can be a :ref:`Secret`).
    :param auth: the authentication method to use.
        Refer to the documentation of the requests library for more information.
    :param dict headers: pass custom headers to HTTP request.
    :type generators: list of IReportGenerator instances
    :param generators: A list of report generators that will be used to generate reports to be sent by this reporter.
        Currently the reporter will consider only the report generated by the first generator.
    :param function format_fn: a function that takes the build as parameter and returns a dictionary to be pushed to the server (as json).    
        This parameter is deprecated, use ``generators`` instead.
    :param list builders: only send update for specified builders.
        This parameter is deprecated, use ``generators`` instead.
    :param boolean wantProperties: include 'properties' in the build dictionary.
        This parameter is deprecated, use ``generators`` instead.
    :param boolean wantSteps: include 'steps' in the build dictionary.
        This parameter is deprecated, use ``generators`` instead.
    :param boolean wantLogs: include 'logs' in the steps dictionaries.
        This needs wantSteps=True.
        This dumps the *full* content of logs and may consume lots of memory and CPU depending on the log size.
        This parameter is deprecated, use ``generators`` instead.
    :param boolean wantPreviousBuild: include 'prev_build' in the build dictionary.
        This parameter is deprecated, use ``generators`` instead.
    :param boolean debug: logs every requests and their response
    :param boolean verify: disable ssl verification for the case you use temporary self signed certificates
    :param boolean skipEncoding: disables encoding of json data to bytes before pushing to server

Json object spec
~~~~~~~~~~~~~~~~

The default json object sent is a build object augmented with some more data as follow.

.. code-block:: json

    {
        "url": "http://yourbot/path/to/build",
        "<build data api values>": "[...]",
        "buildset": "<buildset data api values>",
        "builder": "<builder data api values>",
        "buildrequest": "<buildrequest data api values>"
    }


If you want another format, don't hesitate to use the ``format_fn`` parameter to customize the payload.
The ``build`` parameter given to that function is of type :bb:rtype:`build`, optionally enhanced with properties, steps, and logs information.

.. _txrequests: https://pypi.python.org/pypi/txrequests
.. _treq: https://pypi.python.org/pypi/treq
