##// END OF EJS Templates
Document how to create wrapper kernels
Thomas Kluyver -
Show More
@@ -0,0 +1,106
1 Making simple Python wrapper kernels
2 ====================================
3
4 .. versionadded:: 3.0
5
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
8 <http://www.gnu.org/software/octave/>`_ (via
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/>`_,
11 such as bash.
12
13 Required steps
14 --------------
15
16 Subclass :class:`IPython.kernel.zmq.kernelbase.KernelBase`, and implement the
17 following methods and attributes:
18
19 .. class:: MyKernel
20
21 .. attribute:: implementation
22 implementation_version
23 language
24 language_version
25 banner
26
27 Information for :ref:`msging_kernel_info` replies. 'Implementation' refers
28 to the kernel (e.g. IPython), and 'language' refers to the language it
29 interprets (e.g. Python). The 'banner' is displayed to the user in console
30 UIs before the first prompt. All of these values are strings.
31
32 .. method:: do_execute(code, silent, store_history=True, user_expressions=None, allow_stdin=False)
33
34 Execute user code.
35
36 :param str code: The code to be executed.
37 :param bool silent: Whether to display output.
38 :param bool store_history: Whether to record this code in history and
39 increase the execution count. If silent is True, this is implicitly
40 False.
41 :param dict user_expressions: Mapping of names to expressions to evaluate
42 after the code has run. You can ignore this if you need to.
43 :param bool allow_stdin: Whether the frontend can provide input on request
44 (e.g. for Python's :func:`raw_input`).
45
46 Your method should return a dict containing the fields described in
47 :ref:`execution_results`. To display output, it can send messages
48 using :meth:`~IPython.kernel.zmq.kernelbase.KernelBase.send_response`.
49 See :doc:`messaging` for details of the different message types.
50
51 To launch your kernel::
52
53 from IPython.kernel.zmq.kernelapp import IPKernelApp
54 IPKernelApp.launch_instance(kernel_class=MyKernel)
55
56 Optional steps
57 --------------
58
59 You can override a number of other methods to improve the functionality of your
60 kernel. All of these methods should return a dictionary as described in the
61 relevant section of the :doc:`messaging spec <messaging>`.
62
63 .. class:: MyKernel
64
65 .. method:: do_complete(code, cusor_pos)
66
67 Code completion
68
69 :param str code: The code already present
70 :param int cursor_pos: The position in the code where completion is requested
71
72 .. seealso::
73
74 :ref:`msging_completion` messages
75
76 .. method:: do_inspect(code, cusor_pos, detail_level=0)
77
78 Object inspection
79
80 :param str code: The code
81 :param int cursor_pos: The position in the code where inspection is requested
82 :param int detail_level: 0 or 1 for more or less detail. In IPython, 1 gets
83 the source code.
84
85 .. seealso::
86
87 :ref:`msging_inspection` messages
88
89 .. method:: do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)
90
91 History access
92
93 .. seealso::
94
95 :ref:`msging_history` messages
96
97 .. method:: do_shutdown(restart)
98
99 Shutdown the kernel. You only need to handle your own clean up - the kernel
100 machinery will take care of cleaning up its own things before stopping.
101
102 :param bool restart: Whether the kernel will be started again afterwards
103
104 .. seealso::
105
106 :ref:`msging_shutdown` messages
@@ -25,7 +25,7 from IPython.core.shellapp import (
25 from IPython.utils import io
25 from IPython.utils import io
26 from IPython.utils.path import filefind
26 from IPython.utils.path import filefind
27 from IPython.utils.traitlets import (
27 from IPython.utils.traitlets import (
28 Any, Instance, Dict, Unicode, Integer, Bool, DottedObjectName,
28 Any, Instance, Dict, Unicode, Integer, Bool, DottedObjectName, Type,
29 )
29 )
30 from IPython.utils.importstring import import_item
30 from IPython.utils.importstring import import_item
31 from IPython.kernel import write_connection_file
31 from IPython.kernel import write_connection_file
@@ -102,7 +102,7 class IPKernelApp(BaseIPythonApplication, InteractiveShellApp,
102 flags = Dict(kernel_flags)
102 flags = Dict(kernel_flags)
103 classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session]
103 classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session]
104 # the kernel class, as an importstring
104 # the kernel class, as an importstring
105 kernel_class = DottedObjectName('IPython.kernel.zmq.ipkernel.Kernel', config=True,
105 kernel_class = Type('IPython.kernel.zmq.ipkernel.Kernel', config=True,
106 help="""The Kernel subclass to be used.
106 help="""The Kernel subclass to be used.
107
107
108 This should allow easy re-use of the IPKernelApp entry point
108 This should allow easy re-use of the IPKernelApp entry point
@@ -20,6 +20,7 on the IPython GitHub wiki.
20 :maxdepth: 1
20 :maxdepth: 1
21
21
22 messaging
22 messaging
23 wrapperkernels
23 execution
24 execution
24 parallel_messages
25 parallel_messages
25 parallel_connections
26 parallel_connections
@@ -409,6 +409,7 When status is 'error', the following extra fields are present::
409 When status is 'abort', there are for now no additional data fields. This
409 When status is 'abort', there are for now no additional data fields. This
410 happens when the kernel was interrupted by a signal.
410 happens when the kernel was interrupted by a signal.
411
411
412 .. _msging_inspection:
412
413
413 Introspection
414 Introspection
414 -------------
415 -------------
@@ -465,6 +466,8 Message type: ``inspect_reply``::
465
466
466 Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel.
467 Reply is changed from structured data to a mime bundle, allowing formatting decisions to be made by the kernel.
467
468
469 .. _msging_completion:
470
468 Completion
471 Completion
469 ----------
472 ----------
470
473
@@ -512,6 +515,7 Message type: ``complete_reply``::
512 - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
515 - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
513 - ``metadata`` is added for extended information.
516 - ``metadata`` is added for extended information.
514
517
518 .. _msging_history:
515
519
516 History
520 History
517 -------
521 -------
@@ -590,6 +594,7 Message type: ``connect_reply``::
590 'hb_port' : int, # The port the heartbeat socket is listening on.
594 'hb_port' : int, # The port the heartbeat socket is listening on.
591 }
595 }
592
596
597 .. _msging_kernel_info:
593
598
594 Kernel info
599 Kernel info
595 -----------
600 -----------
@@ -650,6 +655,7 Message type: ``kernel_info_reply``::
650
655
651 ``implementation``, ``implementation_version``, and ``banner`` keys are added.
656 ``implementation``, ``implementation_version``, and ``banner`` keys are added.
652
657
658 .. _msging_shutdown:
653
659
654 Kernel shutdown
660 Kernel shutdown
655 ---------------
661 ---------------
General Comments 0
You need to be logged in to leave comments. Login now