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 = |
|
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