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