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