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