Show More
@@ -140,6 +140,11 b" inputs, and run all multiline input in 'exec' mode. This would preserve the" | |||||
140 | natural behavior of single-line inputs while allowing long cells to behave more |
|
140 | natural behavior of single-line inputs while allowing long cells to behave more | |
141 | likea a script. This design will be refined as we complete the implementation. |
|
141 | likea a script. This design will be refined as we complete the implementation. | |
142 |
|
142 | |||
|
143 | .. Note:: | |||
|
144 | ||||
|
145 | What today we call 'prompt requests' will be encoded in the | |||
|
146 | ``state_template`` field. | |||
|
147 | ||||
143 | Message type: ``execute_request``:: |
|
148 | Message type: ``execute_request``:: | |
144 |
|
149 | |||
145 | content = { |
|
150 | content = { | |
@@ -148,17 +153,44 b' Message type: ``execute_request``::' | |||||
148 |
|
153 | |||
149 | # A boolean flag which, if True, signals the kernel to execute this |
|
154 | # A boolean flag which, if True, signals the kernel to execute this | |
150 | # code as quietly as possible. This means that the kernel will compile |
|
155 | # code as quietly as possible. This means that the kernel will compile | |
151 |
# the code with 'exec' instead of 'single' (so |
|
156 | # the code witIPython/core/tests/h 'exec' instead of 'single' (so | |
152 | # fire), and will *not*: |
|
157 | # sys.displayhook will not fire), and will *not*: | |
153 | # - broadcast exceptions on the PUB socket |
|
158 | # - broadcast exceptions on the PUB socket | |
154 | # - do any logging |
|
159 | # - do any logging | |
155 | # - populate any history |
|
160 | # - populate any history | |
|
161 | # | |||
156 | # The default is False. |
|
162 | # The default is False. | |
157 | 'silent' : bool, |
|
163 | 'silent' : bool, | |
|
164 | ||||
|
165 | # An optional string to request arbitrary state information from the | |||
|
166 | # kernel. This string is evaluated via the itpl module, and it can | |||
|
167 | # therefore contain arbitrary code for execution. | |||
|
168 | ||||
|
169 | 'state_template' : str, | |||
158 | } |
|
170 | } | |
159 |
|
171 | |||
160 | Upon execution, the kernel *always* sends a reply, with a status code |
|
172 | Execution semantics | |
161 | indicating what happened and additional data depending on the outcome. |
|
173 | Upon execution of the ``code`` field, the kernel *always* sends a reply, | |
|
174 | with a status code indicating what happened and additional data depending | |||
|
175 | on the outcome. | |||
|
176 | ||||
|
177 | Any code in the ``state_template`` string is evaluated, but full exceptions | |||
|
178 | that may occur are *not* propagated back. If any error occurs during the | |||
|
179 | evaluation, the value of the string will simply be:: | |||
|
180 | ||||
|
181 | [ERROR in <contents of template>: ExceptionType - Exception message] | |||
|
182 | ||||
|
183 | The user can simply send the same code contained in the template for normal | |||
|
184 | evaluation to see a regular traceback. | |||
|
185 | ||||
|
186 | Execution counter (old prompt number) | |||
|
187 | The kernel has a single, monotonically increasing counter of all execution | |||
|
188 | requests that are made with ``silent=False``. This counter is used to | |||
|
189 | populate the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will | |||
|
190 | likely want to display it in some form to the user, which will typically | |||
|
191 | (but not necessarily) be done in the prompts. The value of this counter | |||
|
192 | will be returned as the ``execution_count`` field of all ``execute_reply``` | |||
|
193 | messages. | |||
162 |
|
194 | |||
163 | Message type: ``execute_reply``:: |
|
195 | Message type: ``execute_reply``:: | |
164 |
|
196 | |||
@@ -166,30 +198,25 b' Message type: ``execute_reply``::' | |||||
166 | # One of: 'ok' OR 'error' OR 'abort' |
|
198 | # One of: 'ok' OR 'error' OR 'abort' | |
167 | 'status' : str, |
|
199 | 'status' : str, | |
168 |
|
200 | |||
169 | # This has the same structure as the output of a prompt request, but is |
|
201 | # The global kernel counter that increases by one with each non-silent | |
170 | # for the client to set up the *next* prompt (with identical limitations |
|
202 | # executed request. This will typically be used by clients to display | |
171 | # to a prompt request) |
|
203 | # prompt numbers to the user. If the request was a silent one, this will | |
172 | 'next_prompt' : { |
|
204 | # be the current value of the counter in the kernel. | |
173 | 'prompt_string' : str, |
|
205 | 'execution_count' : int, | |
174 | 'prompt_number' : int, |
|
206 | ||
175 | 'input_sep' : str |
|
207 | # If the state_template was provided, this will contain the evaluated | |
176 | }, |
|
208 | # form of the template. | |
177 |
|
209 | 'state' : str, | ||
178 | # The prompt number of the actual execution for this code, which may be |
|
|||
179 | # different from the one used when the code was typed, which was the |
|
|||
180 | # 'next_prompt' field of the *previous* request. They will differ in the |
|
|||
181 | # case where there is more than one client talking simultaneously to a |
|
|||
182 | # kernel, since the numbers can go out of sync. GUI clients can use this |
|
|||
183 | # to correct the previously written number in-place, terminal ones may |
|
|||
184 | # re-print a corrected one if desired. |
|
|||
185 | 'prompt_number' : int, |
|
|||
186 | } |
|
210 | } | |
187 |
|
211 | |||
188 | When status is 'ok', the following extra fields are present:: |
|
212 | When status is 'ok', the following extra fields are present:: | |
189 |
|
213 | |||
190 | { |
|
214 | { | |
191 |
# The kernel will often transform the input provided to it. |
|
215 | # The kernel will often transform the input provided to it. If the | |
192 | # contains the transformed code, which is what was actually executed. |
|
216 | # '---->' transform had been applied, this is filled, otherwise it's the | |
|
217 | # empty string. So transformations like magics don't appear here, only | |||
|
218 | # autocall ones. | |||
|
219 | ||||
193 | 'transformed_code' : str, |
|
220 | 'transformed_code' : str, | |
194 |
|
221 | |||
195 | # The execution payload is a dict with string keys that may have been |
|
222 | # The execution payload is a dict with string keys that may have been | |
@@ -235,31 +262,65 b" When status is 'error', the following extra fields are present::" | |||||
235 | When status is 'abort', there are for now no additional data fields. This |
|
262 | When status is 'abort', there are for now no additional data fields. This | |
236 | happens when the kernel was interrupted by a signal. |
|
263 | happens when the kernel was interrupted by a signal. | |
237 |
|
264 | |||
|
265 | Kernel attribute access | |||
|
266 | ----------------------- | |||
238 |
|
267 | |||
239 | Prompt |
|
268 | While this protocol does not specify full RPC access to arbitrary methods of | |
240 | ------ |
|
269 | the kernel object, the kernel does allow read (and in some cases write) access | |
|
270 | to certain attributes. | |||
241 |
|
271 | |||
242 | A simple request for a current prompt string. |
|
272 | The policy for which attributes can be read is: any attribute of the kernel, or | |
|
273 | its sub-objects, that belongs to a :class:`Configurable` object and has been | |||
|
274 | declared at the class-level with Traits validation, is in principle accessible | |||
|
275 | as long as its name does not begin with a leading underscore. The attribute | |||
|
276 | itself will have metadata indicating whether it allows remote read and/or write | |||
|
277 | access. The message spec follows for attribute read and write requests. | |||
243 |
|
278 | |||
244 |
Message type: `` |
|
279 | Message type: ``getattr_request``:: | |
245 |
|
280 | |||
246 |
content = { |
|
281 | content = { | |
|
282 | # The (possibly dotted) name of the attribute | |||
|
283 | 'name' : str | |||
|
284 | } | |||
247 |
|
285 | |||
248 | In the reply, the prompt string comes back with the prompt number placeholder |
|
286 | When a ``getattr_request`` fails, there are two possible error types: | |
249 | *unevaluated*. The message format is: |
|
287 | ||
250 |
|
288 | - AttributeError: this type of error was raised when trying to access the | ||
251 | Message type: ``prompt_reply``:: |
|
289 | given name by the kernel itself. This means that the attribute likely | |
|
290 | doesn't exist. | |||
|
291 | ||||
|
292 | - AccessError: the attribute exists but its value is not readable remotely. | |||
|
293 | ||||
|
294 | ||||
|
295 | Message type: ``getattr_reply``:: | |||
|
296 | ||||
|
297 | content = { | |||
|
298 | # One of ['ok', 'AttributeError', 'AccessError']. | |||
|
299 | 'status' : str | |||
|
300 | # If status is 'ok', a JSON object. | |||
|
301 | 'value' : object | |||
|
302 | } | |||
|
303 | ||||
|
304 | Message type: ``setattr_request``:: | |||
252 |
|
305 | |||
253 | content = { |
|
306 | content = { | |
254 | 'prompt_string' : str, |
|
307 | # The (possibly dotted) name of the attribute | |
255 | 'prompt_number' : int, |
|
308 | 'name' : str | |
256 | 'input_sep' : str |
|
309 | ||
|
310 | # A JSON-encoded object, that will be validated by the Traits | |||
|
311 | # information in the kernel | |||
|
312 | 'value' : object | |||
257 | } |
|
313 | } | |
258 |
|
314 | |||
259 | Clients can produce a prompt with ``prompt_string.format(prompt_number)``, but |
|
315 | When a ``setattr_request`` fails, there are also two possible error types with | |
260 | they should be aware that the actual prompt number for that input could change |
|
316 | similar meanings as those of the ``getattr_request`` case, but for writing. | |
261 | later, in the case where multiple clients are interacting with a single |
|
317 | ||
262 | kernel. |
|
318 | Message type: ``setattr_reply``:: | |
|
319 | ||||
|
320 | content = { | |||
|
321 | # One of ['ok', 'AttributeError', 'AccessError']. | |||
|
322 | 'status' : str | |||
|
323 | } | |||
263 |
|
324 | |||
264 |
|
325 | |||
265 | Object information |
|
326 | Object information | |
@@ -276,12 +337,12 b' Message type: ``object_info_request``::' | |||||
276 |
|
337 | |||
277 | content = { |
|
338 | content = { | |
278 | # The (possibly dotted) name of the object to be searched in all |
|
339 | # The (possibly dotted) name of the object to be searched in all | |
279 |
|
|
340 | # relevant namespaces | |
280 | 'name' : str, |
|
341 | 'name' : str, | |
281 |
|
342 | |||
282 | # The level of detail desired. The default (0) is equivalent to typing |
|
343 | # The level of detail desired. The default (0) is equivalent to typing | |
283 |
|
|
344 | # 'x?' at the prompt, 1 is equivalent to 'x??'. | |
284 |
|
|
345 | 'detail_level' : int, | |
285 | } |
|
346 | } | |
286 |
|
347 | |||
287 | The returned information will be a dictionary with keys very similar to the |
|
348 | The returned information will be a dictionary with keys very similar to the | |
@@ -315,9 +376,29 b' Message type: ``object_info_reply``::' | |||||
315 | 'file' : str, |
|
376 | 'file' : str, | |
316 |
|
377 | |||
317 | # For pure Python callable objects, we can reconstruct the object |
|
378 | # For pure Python callable objects, we can reconstruct the object | |
318 | # definition line which provides its call signature |
|
379 | # definition line which provides its call signature. For convenience this | |
|
380 | # is returned as a single 'definition' field, but below the raw parts that | |||
|
381 | # compose it are also returned as the argspec field. | |||
319 | 'definition' : str, |
|
382 | 'definition' : str, | |
320 |
|
383 | |||
|
384 | # The individual parts that together form the definition string. Clients | |||
|
385 | # with rich display capabilities may use this to provide a richer and more | |||
|
386 | # precise representation of the definition line (e.g. by highlighting | |||
|
387 | # arguments based on the user's cursor position). For non-callable | |||
|
388 | # objects, this field is empty. | |||
|
389 | 'argspec' : { # The names of all the arguments | |||
|
390 | args : list, | |||
|
391 | # The name of the varargs (*args), if any | |||
|
392 | varargs : str, | |||
|
393 | # The name of the varkw (**kw), if any | |||
|
394 | varkw : str | |||
|
395 | # The values (as strings) of all default arguments. Note | |||
|
396 | # that these must be matched *in reverse* with the 'args' | |||
|
397 | # list above, since the first positional args have no default | |||
|
398 | # value at all. | |||
|
399 | func_defaults : list | |||
|
400 | } | |||
|
401 | ||||
321 | # For instances, provide the constructor signature (the definition of |
|
402 | # For instances, provide the constructor signature (the definition of | |
322 | # the __init__ method): |
|
403 | # the __init__ method): | |
323 | 'init_definition' : str, |
|
404 | 'init_definition' : str, |
General Comments 0
You need to be logged in to leave comments.
Login now