# Client API

Clients manage the main user facing API, and provide functions for sending events and querying the Riemann server. UDP, TCP and TLS transports are provided by the `riemann_client.transport` module, and the protocol buffer objects are provided by the `riemann_client.riemann_pb2` module.

class `riemann_client.client.``Client`(transport=None)

  Bases: `object`

  A client for sending events and querying a Riemann server.

  Two sets of methods are provided - an API dealing directly with protocol buffer objects and an extended API that takes and returns dictionaries representing events.

  Protocol buffer API:

  > - `send_event()`
  > - `send_events()`
  > - `send_query()`

  Extended API:

  > - `event()`
  > - `events()`
  > - `query()`

  Clients do not directly manage connections to a Riemann server - these are managed by `riemann_client.transport.Transport` instances, which provide methods to read and write messages to the server. Client instances can be used as a context manager, and will connect and disconnect the transport when entering and exiting the context.

      >>> with Client(transport) as client:
      ...     # Calls transport.connect()
      ...     client.query('true')
      ...     # Calls transport.disconnect()

  static `create_event`(data)

    Translates a dictionary of event attributes to an Event object

    Parameters: | data (dict) – The attributes to be set on the event
    Returns: | A protocol buffer `Event` object

  `send_events`(events)

    Sends multiple events to Riemann in a single message

    Parameters: | events – A list or iterable of `Event` objects
    Returns: | The response message from Riemann

  `send_event`(event)

    Sends a single event to Riemann

    Parameters: | event – An `Event` protocol buffer object
    Returns: | The response message from Riemann

  `events`(*events)

    Sends multiple events in a single message

        >>> client.events({'service': 'riemann-client', 'state': 'awesome'})

    > param *events: | event dictionaries for `create_event()`
    > returns: | The response message from Riemann

  `event`(**data)

    Sends an event, using keyword arguments to create an Event

        >>> client.event(service='riemann-client', state='awesome')

    Parameters: | **data – keyword arguments used for `create_event()`
    Returns: | The response message from Riemann

  static `create_dict`(event)

    Translates an Event object to a dictionary of event attributes

    All attributes are included, so `create_dict(create_event(input))` may return more attributes than were present in the input.

    Parameters: | event – A protocol buffer `Event` object
    Returns: | A dictionary of event attributes

  `send_query`(query)

    Sends a query to the Riemann server

    Returns: | The response message from Riemann

  `query`(query)

    Sends a query to the Riemann server

        >>> client.query('true')

    Returns: | A list of event dictionaries taken from the response
    Raises: | Exception – if used with a `UDPTransport`

class `riemann_client.client.``QueuedClient`(transport=None)

  Bases: `riemann_client.client.Client`

  A Riemann client using a queue that can be used to batch send events.

  A message object is used as a queue, with the `send_event()` and `send_events()` methods adding new events to the message and the `flush()` sending the message.

  `flush`()

    Sends the waiting message to Riemann

    Returns: | The response message from Riemann

  `send_event`(event)

    Adds a single event to the queued message

    Returns: | None - nothing has been sent to the Riemann server yet

  `send_events`(events)

    Adds multiple events to the queued message

    Returns: | None - nothing has been sent to the Riemann server yet

  `clear_queue`()

    Resets the message/queue to a blank `Msg` object

class `riemann_client.client.``AutoFlushingQueuedClient`(transport, max_delay=0.5, max_batch_size=100, stay_connected=False, clear_on_fail=False)

  Bases: `riemann_client.client.QueuedClient`

  A Riemann client using a queue and a timer that will automatically flush its contents if either:

  > - the queue size exceeds :param max_batch_size: or
  > - more than :param max_delay: has elapsed since the last flush and

  > > the queue is non-empty.

  if :param stay_connected: is False, then the transport will be disconnected after each flush and reconnected at the beginning of the next flush. if :param clear_on_fail: is True, then the client will discard its buffer after the second retry in the event of a socket error.

  A message object is used as a queue, and the following methods are given:

  > - `send_event()` - add a new event to the queue

  > - `send_events()` add a tuple of new events to the queue

  > - `event()` - add a new event to the queue from

  >     keyword arguments

  > - `events()` - add new events to the queue from

  >     dictionaries

  > - `flush()` - manually force flush the queue to the

  >     transport

  `connect`()

    Connect the transport if it is not already connected.

  `is_connected`()

    Check whether the transport is connected.

  `event`(**data)

    Enqueues an event, using keyword arguments to create an Event

        >>> client.event(service='riemann-client', state='awesome')

    Parameters: | **data – keyword arguments used for `create_event()`

  `events`(*events)

    Enqueues multiple events in a single message

        >>> client.events({'service': 'riemann-client',
        >>>                'state': 'awesome'})

    > param *events: | event dictionaries for `create_event()`
    > returns: | The response message from Riemann

  `send_events`(events)

    Enqueues multiple events

    Parameters: | events – A list or iterable of `Event` objects
    Returns: | The response message from Riemann

  `flush`()

    Sends the events in the queue to Riemann in a single protobuf message

    Returns: | The response message from Riemann

  `check_for_flush`()

    Checks the conditions for flushing the queue

  `start_timer`()

    Cycle the timer responsible for periodically flushing the queue

  `stop_timer`()

    Stops the current timer

    a `flush()` event will reactviate the timer