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