##// END OF EJS Templates
Fix invalid json....
Matthias Bussonnier -
Show More
@@ -1,175 +1,175 b''
1 1 Making simple Python wrapper kernels
2 2 ====================================
3 3
4 4 .. versionadded:: 3.0
5 5
6 6 You can now re-use the kernel machinery in IPython to easily make new kernels.
7 7 This is useful for languages that have Python bindings, such as `Octave
8 8 <http://www.gnu.org/software/octave/>`_ (via
9 9 `Oct2Py <http://blink1073.github.io/oct2py/docs/index.html>`_), or languages
10 10 where the REPL can be controlled in a tty using `pexpect <http://pexpect.readthedocs.org/en/latest/>`_,
11 11 such as bash.
12 12
13 13 .. seealso::
14 14
15 15 `bash_kernel <https://github.com/takluyver/bash_kernel>`_
16 16 A simple kernel for bash, written using this machinery
17 17
18 18 Required steps
19 19 --------------
20 20
21 21 Subclass :class:`IPython.kernel.zmq.kernelbase.Kernel`, and implement the
22 22 following methods and attributes:
23 23
24 24 .. class:: MyKernel
25 25
26 26 .. attribute:: implementation
27 27 implementation_version
28 28 language
29 29 language_version
30 30 banner
31 31
32 32 Information for :ref:`msging_kernel_info` replies. 'Implementation' refers
33 33 to the kernel (e.g. IPython), and 'language' refers to the language it
34 34 interprets (e.g. Python). The 'banner' is displayed to the user in console
35 35 UIs before the first prompt. All of these values are strings.
36 36
37 37 .. attribute:: language_info
38 38
39 39 Language information for :ref:`msging_kernel_info` replies, in a dictionary.
40 40 This should contain the key ``mimetype`` with the mimetype of code in the
41 41 target language (e.g. ``'text/x-python'``), and ``file_extension`` (e.g.
42 42 ``'py'``).
43 43 It may also contain keys ``codemirror_mode`` and ``pygments_lexer`` if they
44 44 need to differ from :attr:`language`.
45 45
46 46 Other keys may be added to this later.
47 47
48 48 .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
49 49
50 50 Execute user code.
51 51
52 52 :param str code: The code to be executed.
53 53 :param bool silent: Whether to display output.
54 54 :param bool store_history: Whether to record this code in history and
55 55 increase the execution count. If silent is True, this is implicitly
56 56 False.
57 57 :param dict user_expressions: Mapping of names to expressions to evaluate
58 58 after the code has run. You can ignore this if you need to.
59 59 :param bool allow_stdin: Whether the frontend can provide input on request
60 60 (e.g. for Python's :func:`raw_input`).
61 61
62 62 Your method should return a dict containing the fields described in
63 63 :ref:`execution_results`. To display output, it can send messages
64 64 using :meth:`~IPython.kernel.zmq.kernelbase.Kernel.send_response`.
65 65 See :doc:`messaging` for details of the different message types.
66 66
67 67 To launch your kernel, add this at the end of your module::
68 68
69 69 if __name__ == '__main__':
70 70 from IPython.kernel.zmq.kernelapp import IPKernelApp
71 71 IPKernelApp.launch_instance(kernel_class=MyKernel)
72 72
73 73 Example
74 74 -------
75 75
76 76 ``echokernel.py`` will simply echo any input it's given to stdout::
77 77
78 78 from IPython.kernel.zmq.kernelbase import Kernel
79 79
80 80 class EchoKernel(Kernel):
81 81 implementation = 'Echo'
82 82 implementation_version = '1.0'
83 83 language = 'no-op'
84 84 language_version = '0.1'
85 85 language_info = {'mimetype': 'text/plain'}
86 86 banner = "Echo kernel - as useful as a parrot"
87 87
88 88 def do_execute(self, code, silent, store_history=True, user_expressions=None,
89 89 allow_stdin=False):
90 90 if not silent:
91 91 stream_content = {'name': 'stdout', 'text': code}
92 92 self.send_response(self.iopub_socket, 'stream', stream_content)
93 93
94 94 return {'status': 'ok',
95 95 # The base class increments the execution count
96 96 'execution_count': self.execution_count,
97 97 'payload': [],
98 98 'user_expressions': {},
99 99 }
100 100
101 101 if __name__ == '__main__':
102 102 from IPython.kernel.zmq.kernelapp import IPKernelApp
103 103 IPKernelApp.launch_instance(kernel_class=EchoKernel)
104 104
105 105 Here's the Kernel spec ``kernel.json`` file for this::
106 106
107 107 {"argv":["python","-m","echokernel", "-f", "{connection_file}"],
108 "display_name":"Echo",
108 "display_name":"Echo"
109 109 }
110 110
111 111
112 112 Optional steps
113 113 --------------
114 114
115 115 You can override a number of other methods to improve the functionality of your
116 116 kernel. All of these methods should return a dictionary as described in the
117 117 relevant section of the :doc:`messaging spec <messaging>`.
118 118
119 119 .. class:: MyKernel
120 120
121 121 .. method:: do_complete(code, cusor_pos)
122 122
123 123 Code completion
124 124
125 125 :param str code: The code already present
126 126 :param int cursor_pos: The position in the code where completion is requested
127 127
128 128 .. seealso::
129 129
130 130 :ref:`msging_completion` messages
131 131
132 132 .. method:: do_inspect(code, cusor_pos, detail_level=0)
133 133
134 134 Object introspection
135 135
136 136 :param str code: The code
137 137 :param int cursor_pos: The position in the code where introspection is requested
138 138 :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets
139 139 the source code.
140 140
141 141 .. seealso::
142 142
143 143 :ref:`msging_inspection` messages
144 144
145 145 .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)
146 146
147 147 History access. Only the relevant parameters for the type of history
148 148 request concerned will be passed, so your method definition must have defaults
149 149 for all the arguments shown with defaults here.
150 150
151 151 .. seealso::
152 152
153 153 :ref:`msging_history` messages
154 154
155 155 .. method:: do_is_complete(code)
156 156
157 157 Is code entered in a console-like interface complete and ready to execute,
158 158 or should a continuation prompt be shown?
159 159
160 160 :param str code: The code entered so far - possibly multiple lines
161 161
162 162 .. seealso::
163 163
164 164 :ref:`msging_is_complete` messages
165 165
166 166 .. method:: do_shutdown(restart)
167 167
168 168 Shutdown the kernel. You only need to handle your own clean up - the kernel
169 169 machinery will take care of cleaning up its own things before stopping.
170 170
171 171 :param bool restart: Whether the kernel will be started again afterwards
172 172
173 173 .. seealso::
174 174
175 175 :ref:`msging_shutdown` messages
General Comments 0
You need to be logged in to leave comments. Login now