##// END OF EJS Templates
Clarify generic message spec vs. Python message API in docs
Alex Kramer -
Show More
@@ -78,22 +78,11 b' representation of all the data, we can communicate with such clients.'
78 Not all of these have yet been fully fleshed out, but the key ones are, see
78 Not all of these have yet been fully fleshed out, but the key ones are, see
79 kernel and frontend files for actual implementation details.
79 kernel and frontend files for actual implementation details.
80
80
81
82 Python functional API
83 =====================
84
85 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
86 should develop, at a few key points, functional forms of all the requests that
87 take arguments in this manner and automatically construct the necessary dict
88 for sending.
89
90
91 General Message Format
81 General Message Format
92 ======================
82 ======================
93
83
94 All messages send or received by any IPython process should have the following
84 A message is defined by the following three-dictionary structure::
95 generic structure::
85
96
97 {
86 {
98 # The message header contains a pair of unique identifiers for the
87 # The message header contains a pair of unique identifiers for the
99 # originating session and the actual message id, in addition to the
88 # originating session and the actual message id, in addition to the
@@ -108,22 +97,40 b' generic structure::'
108 # All recognized message type strings are listed below.
97 # All recognized message type strings are listed below.
109 'msg_type' : str,
98 'msg_type' : str,
110 },
99 },
111 # The msg's unique identifier and type are stored in the header, but
112 # are also accessible at the top-level for convenience.
113 'msg_id' : uuid,
114 'msg_type' : str,
115
100
116 # In a chain of messages, the header from the parent is copied so that
101 # In a chain of messages, the header from the parent is copied so that
117 # clients can track where messages come from.
102 # clients can track where messages come from.
118 'parent_header' : dict,
103 'parent_header' : dict,
119
104
120 # The actual content of the message must be a dict, whose structure
105 # The actual content of the message must be a dict, whose structure
121 # depends on the message type.x
106 # depends on the message type.
122 'content' : dict,
107 'content' : dict,
123 }
108 }
124
109
125 For each message type, the actual content will differ and all existing message
110
126 types are specified in what follows of this document.
111 Python functional API
112 =====================
113
114 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
115 should develop, at a few key points, functional forms of all the requests that
116 take arguments in this manner and automatically construct the necessary dict
117 for sending.
118
119 In addition, the Python implementation of the message specification extends
120 messages upon deserialization to the following form for convenience::
121
122 {
123 'header' : dict,
124 # The msg's unique identifier and type are always stored in the header,
125 # but the Python implementation copies them to the top level.
126 'msg_id' : uuid,
127 'msg_type' : str,
128 'parent_header' : dict
129 'content' : dict
130 }
131
132 All messages sent to or received by any IPython process should have this
133 extended structure.
127
134
128
135
129 Messages on the shell ROUTER/DEALER sockets
136 Messages on the shell ROUTER/DEALER sockets
General Comments 0
You need to be logged in to leave comments. Login now