##// 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 25 from IPython.utils import io
26 26 from IPython.utils.path import filefind
27 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 30 from IPython.utils.importstring import import_item
31 31 from IPython.kernel import write_connection_file
@@ -102,7 +102,7 class IPKernelApp(BaseIPythonApplication, InteractiveShellApp,
102 102 flags = Dict(kernel_flags)
103 103 classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session]
104 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 106 help="""The Kernel subclass to be used.
107 107
108 108 This should allow easy re-use of the IPKernelApp entry point
@@ -20,6 +20,7 on the IPython GitHub wiki.
20 20 :maxdepth: 1
21 21
22 22 messaging
23 wrapperkernels
23 24 execution
24 25 parallel_messages
25 26 parallel_connections
@@ -409,6 +409,7 When status is 'error', the following extra fields are present::
409 409 When status is 'abort', there are for now no additional data fields. This
410 410 happens when the kernel was interrupted by a signal.
411 411
412 .. _msging_inspection:
412 413
413 414 Introspection
414 415 -------------
@@ -465,6 +466,8 Message type: ``inspect_reply``::
465 466
466 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 471 Completion
469 472 ----------
470 473
@@ -512,6 +515,7 Message type: ``complete_reply``::
512 515 - ``matched_text`` is removed in favor of ``cursor_start`` and ``cursor_end``.
513 516 - ``metadata`` is added for extended information.
514 517
518 .. _msging_history:
515 519
516 520 History
517 521 -------
@@ -590,6 +594,7 Message type: ``connect_reply``::
590 594 'hb_port' : int, # The port the heartbeat socket is listening on.
591 595 }
592 596
597 .. _msging_kernel_info:
593 598
594 599 Kernel info
595 600 -----------
@@ -650,6 +655,7 Message type: ``kernel_info_reply``::
650 655
651 656 ``implementation``, ``implementation_version``, and ``banner`` keys are added.
652 657
658 .. _msging_shutdown:
653 659
654 660 Kernel shutdown
655 661 ---------------
General Comments 0
You need to be logged in to leave comments. Login now