# Module: `kernel.zmq.session`

Session object for building, serializing, sending, and receiving messages in IPython. The Session object supports serialization, HMAC signatures, and metadata on messages.

Also defined here are utilities for working with Sessions: * A SessionFactory to be used as a base class for configurables that work with Sessions. * A Message object for convenience that allows attribute-access to the msg dict.

Authors:

- Min RK
- Brian Granger
- Fernando Perez

## 3 Classes

class `IPython.kernel.zmq.session.``SessionFactory`(**kwargs)

  Bases: `IPython.config.configurable.LoggingConfigurable`

  The Base class for configurables that have a Session, Context, logger, and IOLoop.

  `__init__`(**kwargs)

class `IPython.kernel.zmq.session.``Message`(msg_dict)

  Bases: `object`

  A simple message object that maps dict keys to attributes.

  A Message can be created from a dict and a dict from a Message instance simply by calling dict(msg_obj).

  `__init__`(msg_dict)

class `IPython.kernel.zmq.session.``Session`(**kwargs)

  Bases: `IPython.config.configurable.Configurable`

  Object for handling serialization and sending of messages.

  The Session object handles building messages and sending them with ZMQ sockets or ZMQStream objects. Objects can communicate with each other over the network via Session objects, and only need to work with the dict-based IPython message spec. The Session will handle serialization/deserialization, security, and metadata.

  Sessions support configurable serialization via packer/unpacker traits, and signing with HMAC digests via the key/keyfile traits.

  Parameters:

  debug : bool

  > whether to trigger extra debugging statements

  packer/unpacker : str

  > importstrings for methods to serialize message parts. If just ‘json’ or ‘pickle’, predefined JSON and pickle packers will be used. Otherwise, the entire importstring must be used.

  > The functions must accept at least valid JSON input, and output bytes.

  > For example, to use msgpack: packer = ‘msgpack.packb’, unpacker=’msgpack.unpackb’

  pack/unpack : callables

  > You can also set the pack/unpack callables for serialization directly.

  session : bytes

  > the ID of this Session object. The default is to generate a new UUID.

  username : unicode

  > username added to message headers. The default is to ask the OS.

  key : bytes

  > The key used to initialize an HMAC signature. If unset, messages will not be signed or checked.

  keyfile : filepath

  > The file containing a key. If this is set, key will be initialized to the contents of the file.

  `__init__`(**kwargs)

    create a Session object

    Parameters:

    debug : bool

    > whether to trigger extra debugging statements

    packer/unpacker : str

    > importstrings for methods to serialize message parts. If just ‘json’ or ‘pickle’, predefined JSON and pickle packers will be used. Otherwise, the entire importstring must be used.

    > The functions must accept at least valid JSON input, and output bytes.

    > For example, to use msgpack: packer = ‘msgpack.packb’, unpacker=’msgpack.unpackb’

    pack/unpack : callables

    > You can also set the pack/unpack callables for serialization directly.

    session : unicode (must be ascii)

    > the ID of this Session object. The default is to generate a new UUID.

    bsession : bytes

    > The session as bytes

    username : unicode

    > username added to message headers. The default is to ask the OS.

    key : bytes

    > The key used to initialize an HMAC signature. If unset, messages will not be signed or checked.

    signature_scheme : str

    > The message digest scheme. Currently must be of the form ‘hmac-HASH’, where ‘HASH’ is a hashing function available in Python’s hashlib. The default is ‘hmac-sha256’. This is ignored if ‘key’ is empty.

    keyfile : filepath

    > The file containing a key. If this is set, key will be initialized to the contents of the file.

  `feed_identities`(msg_list, copy=True)

    Split the identities from the rest of the message.

    Feed until DELIM is reached, then return the prefix as idents and remainder as msg_list. This is easily broken by setting an IDENT to DELIM, but that would be silly.

    Parameters:

    msg_list : a list of Message or bytes objects

    > The message to be split.

    copy : bool

    > flag determining whether the arguments are bytes or Messages

    Returns:

    (idents, msg_list) : two lists

    > idents will always be a list of bytes, each of which is a ZMQ identity. msg_list will be a list of bytes or zmq.Messages of the form [HMAC,p_header,p_parent,p_content,buffer1,buffer2,...] and should be unpackable/unserializable via self.unserialize at this point.

  `msg`(msg_type, content=None, parent=None, header=None, metadata=None)

    Return the nested message dict.

    This format is different from what is sent over the wire. The serialize/unserialize methods converts this nested message dict to the wire format, which is a list of message parts.

  `msg_id`

    always return new uuid

  `recv`(socket, mode=1, content=True, copy=True)

    Receive and unpack a message.

    Parameters:

    socket : ZMQStream or Socket

    > The socket or stream to use in receiving.

    Returns:

    [idents], msg

    > [idents] is a list of idents and msg is a nested message dict of same format as self.msg returns.

  `send`(stream, msg_or_type, content=None, parent=None, ident=None, buffers=None, track=False, header=None, metadata=None)

    Build and send a message via stream or socket.

    The message format used by this function internally is as follows:

    [ident1,ident2,...,DELIM,HMAC,p_header,p_parent,p_content,
      buffer1,buffer2,...]

    The serialize/unserialize methods convert the nested message dict into this format.

    Parameters:

    stream : zmq.Socket or ZMQStream

    > The socket-like object used to send the data.

    msg_or_type : str or Message/dict

    > Normally, msg_or_type will be a msg_type unless a message is being sent more than once. If a header is supplied, this can be set to None and the msg_type will be pulled from the header.

    content : dict or None

    > The content of the message (ignored if msg_or_type is a message).

    header : dict or None

    > The header dict for the message (ignored if msg_to_type is a message).

    parent : Message or dict or None

    > The parent or parent header describing the parent of this message (ignored if msg_or_type is a message).

    ident : bytes or list of bytes

    > The zmq.IDENTITY routing path.

    metadata : dict or None

    > The metadata describing the message

    buffers : list or None

    > The already-serialized buffers to be appended to the message.

    track : bool

    > Whether to track. Only for use with Sockets, because ZMQStream objects cannot track messages.

    Returns:

    msg : dict

    > The constructed message.

  `send_raw`(stream, msg_list, flags=0, copy=True, ident=None)

    Send a raw message via ident path.

    This method is used to send a already serialized message.

    Parameters:

    stream : ZMQStream or Socket

    > The ZMQ stream or socket to use for sending the message.

    msg_list : list

    > The serialized list of messages to send. This only includes the [p_header,p_parent,p_metadata,p_content,buffer1,buffer2,...] portion of the message.

    ident : ident or list

    > A single ident or a list of idents to use in sending.

  `serialize`(msg, ident=None)

    Serialize the message components to bytes.

    This is roughly the inverse of unserialize. The serialize/unserialize methods work with full message lists, whereas pack/unpack work with the individual message parts in the message list.

    Parameters:

    msg : dict or Message

    > The next message dict as returned by the self.msg method.

    Returns:

    msg_list : list

    > The list of bytes objects to be sent with the format:

    >     [ident1, ident2, ..., DELIM, HMAC, p_header, p_parent,
    >      p_metadata, p_content, buffer1, buffer2, ...]

    > In this list, the `p_*` entities are the packed or serialized versions, so if JSON is used, these are utf8 encoded JSON strings.

  `sign`(msg_list)

    Sign a message with HMAC digest. If no auth, return b’‘.

    Parameters:

    msg_list : list

    > The [p_header,p_parent,p_content] part of the message list.

  `unserialize`(msg_list, content=True, copy=True)

    Unserialize a msg_list to a nested message dict.

    This is roughly the inverse of serialize. The serialize/unserialize methods work with full message lists, whereas pack/unpack work with the individual message parts in the message list.

    Parameters:

    msg_list : list of bytes or Message objects

    > The list of message parts of the form [HMAC,p_header,p_parent, p_metadata,p_content,buffer1,buffer2,...].

    content : bool (True)

    > Whether to unpack the content dict (True), or leave it packed (False).

    copy : bool (True)

    > Whether to return the bytes (True), or the non-copying Message object in each place (False).

    Returns:

    msg : dict

    > The nested message dict with top-level keys [header, parent_header, content, buffers].

## 6 Functions

`IPython.kernel.zmq.session.``compare_digest`(a, b) → bool

  Return ‘a == b’. This function uses an approach designed to prevent timing analysis, making it appropriate for cryptography. a and b must both be of the same type: either str (ASCII only), or any type that supports the buffer protocol (e.g. bytes).

  Note: If a and b are of different lengths, or if an error occurs, a timing attack could theoretically reveal information about the types and lengths of a and b–but not their values.

`IPython.kernel.zmq.session.``squash_unicode`(obj)

  coerce unicode back to bytestrings.

`IPython.kernel.zmq.session.``default_secure`(cfg)

  Set the default behavior for a config environment to be secure.

  If Session.key/keyfile have not been set, set Session.key to a new random UUID.

`IPython.kernel.zmq.session.``msg_header`(msg_id, msg_type, username, session)

`IPython.kernel.zmq.session.``extract_header`(msg_or_header)

  Given a message or header, return the header.

`IPython.kernel.zmq.session.``test_msg2obj`()