Anaconda Enterprise: Documentation

# bokeh.protocol

Implement and provide message protocols for communication between Bokeh Servers and clients.

class `bokeh.protocol.``Protocol`(version)

  Provide a message factory for a given version of the Bokeh Server message protocol.

  Parameters: | version (str) – a string identifying a protocol version, e.g. “1.0”

  `assemble`(header_json, metadata_json, content_json)

    Create a Message instance assembled from json fragments.

    Parameters:

    - header_json (`JSON`) –
    - metadata_json (`JSON`) –
    - content_json (`JSON`) –

    Returns: | message

  `create`(msgtype, *args, **kwargs)

    Create a new Message instance for the given type.

    Parameters: | msgtype (str) –

## bokeh.protocol.exceptions

Provide named exceptions having to do with handling Bokeh Protocol messages.

exception `bokeh.protocol.exceptions.``MessageError`

  Indicate an error in constructing a Bokeh Message object.

  This exception usually indicates that the JSON fragments of a message cannot be decoded at all.

exception `bokeh.protocol.exceptions.``ProtocolError`

  Indicate an error in processing wire protocol fragments.

  This exception indicates that decoded message fragments cannot be properly assembled.

exception `bokeh.protocol.exceptions.``ValidationError`

  Indicate an error validating wire protocol fragments.

  This exception typically indicates that a binary message fragment was received when a text fragment was expected, or vice-versa.

## bokeh.protocol.message

Provide a base class for all Bokeh Server Protocol message types.

Boker messages are comprised of a sequence of JSON fragments. Specified as Python JSON-like data, messages have the general form:

    [
        # these are required
        b'{header}',        # serialized header dict
        b'{metadata}',      # serialized metadata dict
        b'{content},        # serialized content dict

        # these are optional, and come in pairs; header contains num_buffers
        b'{buf_header}',    # serialized buffer header dict
        b'array'            # raw buffer payload data
        ...
    ]

The `header` fragment will have the form:

    header = {
        # these are required
        'msgid'       : <str> # a unique id for the message
        'msgtype'     : <str> # a message type, e.g. 'ACK', 'PATCH-DOC', etc

        # these are optional
        'num_buffers' : <int> # the number of additional buffers, if any
    }

The `metadata` fragment may contain any arbitrary information. It is not processed by Bokeh for any purpose, but may be useful for external monitoring or instrumentation tools.

The `content` fragment is defined by the specific message type.

class `bokeh.protocol.message.``Message`(header, metadata, content)

  The Message base class encapsulates creating, assembling, and validating the integrity of Bokeh Server messages. Additionally, it provide hooks

  `add_buffer`(buf_header, buf_payload)

    Associate a buffer header and payload with this message.

    Parameters:

    - buf_header (`JSON`) – a buffer header
    - buf_payload (`JSON` or bytes) – a buffer payload

    Returns: | None
    Raises: | `MessageError`

  classmethod `assemble`(header_json, metadata_json, content_json)

    Creates a new message, assembled from JSON fragments.

    Parameters:

    - header_json (`JSON`) –
    - metadata_json (`JSON`) –
    - content_json (`JSON`) –

    Returns: | Message subclass
    Raises: | `MessageError`

  `assemble_buffer`(buf_header, buf_payload)

    Add a buffer header and payload that we read from the socket.

    This differs from add_buffer() because we’re validating vs. the header’s num_buffers, instead of filling in the header.

    Parameters:

    - buf_header (`JSON`) – a buffer header
    - buf_payload (`JSON` or bytes) – a buffer payload

    Returns: | None
    Raises: | `ProtocolError`

  classmethod `create_header`(request_id=None)

    Return a message header fragment dict.

    Parameters: | request_id (str or None) – Message ID of the message this message replies to
    Returns: | a message header
    Return type: | dict

  `send`(*args, **kwargs)

    Send the message on the given connection.

    Parameters: | conn (WebSocketHandler) – a WebSocketHandler to send messages
    Returns: | number of bytes sent
    Return type: | int

  `write_buffers`(*args, **kwargs)

    Write any buffer headers and payloads to the given connection.

    Parameters:

    - conn (object) – May be any object with a `write_message` method. Typically, a Tornado `WSHandler` or `WebSocketClientConnection`
    - locked (bool) –

    Returns: | number of bytes sent
    Return type: | int

  `complete`

    Returns whether all required parts of a message are present.

    Returns: | True if the message is complete, False otherwise
    Return type: | bool

## bokeh.protocol.messages

`bokeh.protocol.messages.``register`(cls)

  Decorator to add a Message (and its revision) to the Protocol index.

  Example

      @register
      class some_msg_1(Message):

          msgtype  = 'SOME-MSG'
          revision = 1

          @classmethod
          def create(cls, **metadata):
              header = cls.create_header()
              content = {}
              return cls(header, metadata, content)

### `ACK`

class `bokeh.protocol.messages.ack.``ack_1`(header, metadata, content)

  Define the `ACK` message (revision 1) for acknowledging successful client connection to a Bokeh server.

  The `content` fragment of for this message is empty.

  classmethod `create`(**metadata)

    Create an `ACK` message

    Any keyword arguments will be put into the message `metadata` fragment as-is.

### `EVENT`

class `bokeh.protocol.messages.event.``event_1`(header, metadata, content)

  Define the `EVENT` message (revision 1) for sending events between a Bokeh server and clients.

  This message is currently only generated by clients.

  `notify_event`(document)

### `ERROR`

class `bokeh.protocol.messages.error.``error_1`(header, metadata, content)

  Define the `ERROR` message (revision 1) for reporting error conditions back to a Bokeh server.

  The `content` fragment of for this message is has the form:

      {
          'text'      : <error message text>

          # this is optional
          'traceback' : <traceback text>
      }

  classmethod `create`(request_id, text, **metadata)

    Create an `ERROR` message

    Parameters:

    - request_id (str) – The message ID for the message the precipitated the error.
    - text (str) – The text of any error message or traceback, etc.

    Any additional keyword arguments will be put into the message `metadata` fragment as-is.

### `OK`

class `bokeh.protocol.messages.ok.``ok_1`(header, metadata, content)

  Define the `OK` message (revision 1) for acknowledging successful handling of a previous message.

  The `content` fragment of for this message is empty.

  classmethod `create`(request_id, **metadata)

    Create an `OK` message

    Parameters: | request_id (str) – The message ID for the message the precipitated the OK.

    Any additional keyword arguments will be put into the message `metadata` fragment as-is.

### `PATCH-DOC`

class `bokeh.protocol.messages.patch_doc.``patch_doc_1`(header, metadata, content)

  Define the `PATCH-DOC` message (revision 1) for sending Document patch events between remote documents.

  The `content` fragment of for this message is has the form:

      {
          'events'     : <protocol document events>
          'references' : <model references>
      }

  `apply_to_document`(doc, setter=None)
  classmethod `create`(events, use_buffers=True, **metadata)

    Create a `PATCH-DOC` message

    Parameters: | events (list) – A list of patch events to apply to a document

    Any additional keyword arguments will be put into the message `metadata` fragment as-is.

`bokeh.protocol.messages.patch_doc.``process_document_events`(events, use_buffers=True)

  Create a JSON string describing a patch to be applied as well as any optional buffers.

  Parameters: | events – list of events to be translated into patches
  Returns: | JSON string which can be applied to make the given updates to obj as well as any optional buffers
  Return type: | str, list

### `PULL-DOC-REPLY`

class `bokeh.protocol.messages.pull_doc_reply.``pull_doc_reply_1`(header, metadata, content)

  Define the `PULL-DOC-REPLY` message (revision 1) for replying to Document pull requests from clients

  The `content` fragment of for this message is has the form:

      {
          'doc' : <Document JSON>
      }

  classmethod `create`(request_id, document, **metadata)

    Create an `PULL-DOC-REPLY` message

    Parameters:

    - request_id (str) – The message ID for the message that issues the pull request
    - document (Document) – The Document to reply with

    Any additional keyword arguments will be put into the message `metadata` fragment as-is.

### `PULL-DOC-REQ`

class `bokeh.protocol.messages.pull_doc_req.``pull_doc_req_1`(header, metadata, content)

  Define the `PULL-DOC-REQ` message (revision 1) for requesting a Bokeh server reply with a new Bokeh Document.

  The `content` fragment of for this message is empty.

  classmethod `create`(**metadata)

    Create an `PULL-DOC-REQ` message

    Any keyword arguments will be put into the message `metadata` fragment as-is.

### `PUSH-DOC`

class `bokeh.protocol.messages.push_doc.``push_doc_1`(header, metadata, content)

  Define the `PUSH-DOC` message (revision 1) for pushing Documents from clients to a Bokeh server.

  The `content` fragment of for this message is has the form:

      {
          'doc' : <Document JSON>
      }

  classmethod `create`(document, **metadata)
  `push_to_document`(doc)

    Raises: | `ProtocolError`

### `SERVER-INFO-REPLY`

class `bokeh.protocol.messages.server_info_reply.``server_info_reply_1`(header, metadata, content)

  Define the `SERVER-INFO-REPLY` message (revision 1) for replying to Server info requests from clients.

  The `content` fragment of for this message is has the form:

      {
          'version_info' : {
              'bokeh'  : <bokeh library version>
              'server' : <bokeh server version>
          }
      }

  classmethod `create`(request_id, **metadata)

    Create an `SERVER-INFO-REPLY` message

    Parameters: | request_id (str) – The message ID for the message that issues the info request

    Any additional keyword arguments will be put into the message `metadata` fragment as-is.

### `SERVER-INFO-REQ`

class `bokeh.protocol.messages.server_info_req.``server_info_req_1`(header, metadata, content)

  Define the `SERVER-INFO-REQ` message (revision 1) for requesting a Bokeh server provide information about itself.

  The `content` fragment of for this message is empty.

  classmethod `create`(**metadata)

    Create an `SERVER-INFO-REQ` message

    Any keyword arguments will be put into the message `metadata` fragment as-is.

## bokeh.protocol.receiver

Assemble WebSocket wire message fragments into complete Bokeh Server message objects that can be processed.

class `bokeh.protocol.receiver.``Receiver`(protocol)

  Receive wire message fragments and assemble complete Bokeh server message objects.

  On `MessageError` or `ValidationError`, the receiver will reset its state and attempt to consume a new message.

  The fragment received can be either bytes or unicode, depending on the transport’s semantics (WebSocket allows both).

      [
          # these are required
          b'{header}',        # serialized header dict
          b'{metadata}',      # serialized metadata dict
          b'{content},        # serialized content dict

          # these are optional, and come in pairs; header contains num_buffers
          b'{buf_header}',    # serialized buffer header dict
          b'array'            # raw buffer payload data
          ...
      ]

  The `header` fragment will have the form:

      header = {
          # these are required
          'msgid'       : <str> # a unique id for the message
          'msgtype'     : <str> # a message type, e.g. 'ACK', 'PATCH-DOC', etc

          # these are optional
          'num_buffers' : <int> # the number of additional buffers, if any
      }

  The `metadata` fragment may contain any arbitrary information. It is not processed by Bokeh for any purpose, but may be useful for external monitoring or instrumentation tools.

  The `content` fragment is defined by the specific message type.

  `consume`(*args, **kwargs)

    Consume individual protocol message fragments.

    Parameters:

    - fragment (`JSON`) – A message fragment to assemble. When a complete message is assembled, the receiver state will reset to begin consuming a new message.
    - callback (callable, optional) – Argument required by `return_future` decorator

## bokeh.protocol.versions

Provide definitions for Bokeh WebSocket prototol versions.

A protocol specification is a sequence of tuples of the form:

    (
        (<message_type>, <revision>),
        (<message_type>, <revision>),
        ...
    )

Where `<message_type>` is string that identifies a message type, e.g, `'ACK'`, `'SERVER-INFO-REQ'`, etc. and `<revision>` is an integer that identifies what revision of the message this version of the protocol uses.

A protocol version is a string of the form `'<major>.<minor>'`. The guidelines for updating the major or minor version are:

`<major>`
  bump when new messages are added or deleted (and reset minor version to zero)
`<minor>`
  bump when existing message revisions change

`bokeh.protocol.versions.``spec`

  A mapping of protocol versions to protocol specifications.

      {
          "1.0" : (
              ("ACK", 1),
              ("OK", 1),
              ("ERROR", 1),
              ("EVENT", 1),
              ('SERVER-INFO-REPLY', 1),
              ('SERVER-INFO-REQ', 1),
              ('PULL-DOC-REQ', 1),
              ('PULL-DOC-REPLY', 1),
              ('PUSH-DOC', 1),
              ('PATCH-DOC', 1)
          ),
      }