Show More
@@ -0,0 +1,106 | |||
|
1 | Making simple Python wrapper kernels | |
|
2 | ==================================== | |
|
3 | ||
|
4 | .. versionadded:: 3.0 | |
|
5 | ||
|
6 | You can now re-use the kernel machinery in IPython to easily make new kernels. | |
|
7 | This is useful for languages that have Python bindings, such as `Octave | |
|
8 | <http://www.gnu.org/software/octave/>`_ (via | |
|
9 | `Oct2Py <http://blink1073.github.io/oct2py/docs/index.html>`_), or languages | |
|
10 | where the REPL can be controlled in a tty using `pexpect <http://pexpect.readthedocs.org/en/latest/>`_, | |
|
11 | such as bash. | |
|
12 | ||
|
13 | Required steps | |
|
14 | -------------- | |
|
15 | ||
|
16 | Subclass :class:`IPython.kernel.zmq.kernelbase.KernelBase`, and implement the | |
|
17 | following methods and attributes: | |
|
18 | ||
|
19 | .. class:: MyKernel | |
|
20 | ||
|
21 | .. attribute:: implementation | |
|
22 | implementation_version | |
|
23 | language | |
|
24 | language_version | |
|
25 | banner | |
|
26 | ||
|
27 | Information for :ref:`msging_kernel_info` replies. 'Implementation' refers | |
|
28 | to the kernel (e.g. IPython), and 'language' refers to the language it | |
|
29 | interprets (e.g. Python). The 'banner' is displayed to the user in console | |
|
30 | UIs before the first prompt. All of these values are strings. | |
|
31 | ||
|
32 | .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False) | |
|
33 | ||
|
34 | Execute user code. | |
|
35 | ||
|
36 | :param str code: The code to be executed. | |
|
37 | :param bool silent: Whether to display output. | |
|
38 | :param bool store_history: Whether to record this code in history and | |
|
39 | increase the execution count. If silent is True, this is implicitly | |
|
40 | False. | |
|
41 | :param dict user_expressions: Mapping of names to expressions to evaluate | |
|
42 | after the code has run. You can ignore this if you need to. | |
|
43 | :param bool allow_stdin: Whether the frontend can provide input on request | |
|
44 | (e.g. for Python's :func:`raw_input`). | |
|
45 | ||
|
46 | Your method should return a dict containing the fields described in | |
|
47 | :ref:`execution_results`. To display output, it can send messages | |
|
48 | using :meth:`~IPython.kernel.zmq.kernelbase.KernelBase.send_response`. | |
|
49 | See :doc:`messaging` for details of the different message types. | |
|
50 | ||
|
51 | To launch your kernel:: | |
|
52 | ||
|
53 | from IPython.kernel.zmq.kernelapp import IPKernelApp | |
|
54 | IPKernelApp.launch_instance(kernel_class=MyKernel) | |
|
55 | ||
|
56 | Optional steps | |
|
57 | -------------- | |
|
58 | ||
|
59 | You can override a number of other methods to improve the functionality of your | |
|
60 | kernel. All of these methods should return a dictionary as described in the | |
|
61 | relevant section of the :doc:`messaging spec <messaging>`. | |
|
62 | ||
|
63 | .. class:: MyKernel | |
|
64 | ||
|
65 | .. method:: do_complete(code, cusor_pos) | |
|
66 | ||
|
67 | Code completion | |
|
68 | ||
|
69 | :param str code: The code already present | |
|
70 | :param int cursor_pos: The position in the code where completion is requested | |
|
71 | ||
|
72 | .. seealso:: | |
|
73 | ||
|
74 | :ref:`msging_completion` messages | |
|
75 | ||
|
76 | .. method:: do_inspect(code, cusor_pos, detail_level=0) | |
|
77 | ||
|
78 | Object inspection | |
|
79 | ||
|
80 | :param str code: The code | |
|
81 | :param int cursor_pos: The position in the code where inspection is requested | |
|
82 | :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets | |
|
83 | the source code. | |
|
84 | ||
|
85 | .. seealso:: | |
|
86 | ||
|
87 | :ref:`msging_inspection` messages | |
|
88 | ||
|
89 | .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False) | |
|
90 | ||
|
91 | History access | |
|
92 | ||
|
93 | .. seealso:: | |
|
94 | ||
|
95 | :ref:`msging_history` messages | |
|
96 | ||
|
97 | .. method:: do_shutdown(restart) | |
|
98 | ||
|
99 | Shutdown the kernel. You only need to handle your own clean up - the kernel | |
|
100 | machinery will take care of cleaning up its own things before stopping. | |
|
101 | ||
|
102 | :param bool restart: Whether the kernel will be started again afterwards | |
|
103 | ||
|
104 | .. seealso:: | |
|
105 | ||
|
106 | :ref:`msging_shutdown` messages |
@@ -25,7 +25,7 from IPython.core.shellapp import ( | |||
|
25 | 25 | from IPython.utils import io |
|
26 | 26 | from IPython.utils.path import filefind |
|
27 | 27 | from IPython.utils.traitlets import ( |
|
28 | Any, Instance, Dict, Unicode, Integer, Bool, DottedObjectName, | |
|
28 | Any, Instance, Dict, Unicode, Integer, Bool, DottedObjectName, Type, | |
|
29 | 29 | ) |
|
30 | 30 | from IPython.utils.importstring import import_item |
|
31 | 31 | from IPython.kernel import write_connection_file |
@@ -102,7 +102,7 class IPKernelApp(BaseIPythonApplication, InteractiveShellApp, | |||
|
102 | 102 | flags = Dict(kernel_flags) |
|
103 | 103 | classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session] |
|
104 | 104 | # the kernel class, as an importstring |
|
105 |
kernel_class = |
|
|
105 | kernel_class = Type('IPython.kernel.zmq.ipkernel.Kernel', config=True, | |
|
106 | 106 | help="""The Kernel subclass to be used. |
|
107 | 107 | |
|
108 | 108 | This should allow easy re-use of the IPKernelApp entry point |
@@ -20,6 +20,7 on the IPython GitHub wiki. | |||
|
20 | 20 | :maxdepth: 1 |
|
21 | 21 | |
|
22 | 22 | messaging |
|
23 | wrapperkernels | |
|
23 | 24 | execution |
|
24 | 25 | parallel_messages |
|
25 | 26 | parallel_connections |
@@ -409,6 +409,7 When status is 'error', the following extra fields are present:: | |||
|
409 | 409 | When status is 'abort', there are for now no additional data fields. This |
|
410 | 410 | happens when the kernel was interrupted by a signal. |
|
411 | 411 | |
|
412 | .. _msging_inspection: | |
|
412 | 413 | |
|
413 | 414 | Introspection |
|
414 | 415 | ------------- |
@@ -465,6 +466,8 Message type: ``inspect_reply``:: | |||
|
465 | 466 | |
|
466 | 467 | Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel. |
|
467 | 468 | |
|
469 | .. _msging_completion: | |
|
470 | ||
|
468 | 471 | Completion |
|
469 | 472 | ---------- |
|
470 | 473 | |
@@ -512,6 +515,7 Message type: ``complete_reply``:: | |||
|
512 | 515 | - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``. |
|
513 | 516 | - ``metadata`` is added for extended information. |
|
514 | 517 | |
|
518 | .. _msging_history: | |
|
515 | 519 | |
|
516 | 520 | History |
|
517 | 521 | ------- |
@@ -590,6 +594,7 Message type: ``connect_reply``:: | |||
|
590 | 594 | 'hb_port' : int, # The port the heartbeat socket is listening on. |
|
591 | 595 | } |
|
592 | 596 | |
|
597 | .. _msging_kernel_info: | |
|
593 | 598 | |
|
594 | 599 | Kernel info |
|
595 | 600 | ----------- |
@@ -650,6 +655,7 Message type: ``kernel_info_reply``:: | |||
|
650 | 655 | |
|
651 | 656 | ``implementation``, ``implementation_version``, and ``banner`` keys are added. |
|
652 | 657 | |
|
658 | .. _msging_shutdown: | |
|
653 | 659 | |
|
654 | 660 | Kernel shutdown |
|
655 | 661 | --------------- |
General Comments 0
You need to be logged in to leave comments.
Login now